Claude Code: organize agentes em paralelo com Git Worktrees

Enquanto fazia o curso Claude Code: Software Engineering with Generative AI Agents, imaginei um produto mantido por várias squads: Checkout muda a criação do pedido, Pagamentos atualiza o status, Contas consome o evento e Plataforma prepara o pacote de release/homolog. Cada equipe cuida de uma parte, mas uma mudança compartilhada pode fazer essas frentes se atropelarem.

É como várias equipes numa oficina: cada uma precisa da própria vaga para desmontar um carro, mas todas ainda dependem do mesmo estoque de peças e da inspeção final. O curso me ajudou a perceber que a mesma disputa acontece entre agentes: duas sessões podem tentar trabalhar no mesmo checkout e misturar alterações. Os worktrees dão uma vaga isolada a cada sessão; o Claude Code Desktop torna essas frentes visíveis e aproxima branch, diff, PR e CI.

O Git cria o worktree; o mérito do harness do Claude Code é transformar essa capacidade num fluxo visual guiado e amarrar cada sessão ao seu diretório, branch e trabalho em andamento.

O Claude Code já oferece partes desse fluxo no CLI, no Desktop e em comandos de orquestração. A oportunidade é conectá-las ao processo que cada squad usa e aos contratos que coordenam mudanças entre equipes.

Índice

• 1. O problema da squad não é criar branches
• 2. A camada visual que organiza o trabalho paralelo
• 3. A unidade de trabalho liga tarefa, worktree e PR
• 4. Cinco formas de adotar dentro e entre squads
• 5. O harness precisa de guia e sensor
• 6. Onde worktrees não resolvem o problema
• 7. Um rollout pequeno antes de escalar

1. O problema da squad não é criar branches

Squads grandes já sabem criar branches. O problema aparece quando a quantidade de trabalho simultâneo cresce dentro da equipe:

• uma pessoa interrompe a feature para corrigir um incidente;
• outra precisa revisar um PR sem perder o estado local;
• um agente altera dependências enquanto outro mexe na mesma configuração;
• várias mudanças ficam prontas ao mesmo tempo e encontram a mesma fila de CI e review;
• uma migration, um lockfile ou um contrato compartilhado aproxima tarefas que pareciam independentes.

Entre squads, a colisão pode acontecer mesmo quando ninguém edita o mesmo arquivo:

• uma squad muda a API enquanto outra ainda depende da versão anterior;
• um PR de infraestrutura precisa entrar antes dos PRs consumidores;
• dois repositórios avançam em ritmos diferentes dentro da mesma iniciativa;
• um pacote compartilhado não tem owner ou política de compatibilidade clara;
• a mudança passa no CI isolado de cada squad, mas falha quando os componentes se encontram.

Uma branch separa o histórico, mas um checkout tradicional continua ocupando um único working directory. Trocar de branch muda os arquivos daquela pasta. Para trabalho humano sequencial, isso costuma bastar. Para sessões paralelas de coding agents, o diretório compartilhado vira um gargalo.

Um worktree acrescenta o isolamento físico:

repo/
├── main/          → main
├── exportacao/    → feature/exportacao
├── dashboard/     → feature/dashboard
└── notificacoes/  → feature/notificacoes

Cada diretório tem seus próprios arquivos e sua própria branch, enquanto todos compartilham o histórico do mesmo repositório.

Isso não elimina conflito de merge nem coordena contratos entre squads. O que ele elimina é uma classe anterior de colisão: duas tarefas modificando o mesmo checkout enquanto ainda estão sendo executadas.

2. A camada visual que organiza o trabalho paralelo

Git worktree não foi inventado pelo Claude Code. O diferencial do Claude Code Desktop está em incorporar essa capacidade nativa do Git a uma interface que torna o trabalho paralelo compreensível e revisável.

Captura: Anthropic. A barra lateral reúne projetos e sessões; o worktree dá a cada sessão local um diretório de trabalho isolado.

A barra lateral vira um quadro operacional

Na aba Code, cada conversa é uma sessão independente, com histórico, pasta do projeto e alterações próprias. Em repositórios Git, o Desktop cria automaticamente um worktree para cada sessão local. A barra lateral mostra essas sessões, permite executar várias em paralelo e oferece filtros por status, projeto e ambiente, além do agrupamento por projeto.

Isso cria um mapa operacional como este:

Projeto: checkout
├── Sessão: corrigir autenticação
│   ├── worktree + branch próprios
│   ├── diff em revisão
│   └── PR aguardando CI
├── Sessão: atualizar SDK
│   ├── worktree + branch próprios
│   └── implementação em andamento
└── Sessão: investigar regressão
    ├── worktree + branch próprios
    └── aguardando decisão humana

Não é uma visualização de todas as branches e relações do repositório, como a de uma ferramenta dedicada a histórico Git. É uma visão das frentes de trabalho conduzidas pelo Claude Code. Para uma squad, isso já resolve uma dor importante: deixa de existir uma coleção de terminais sem identidade clara e passa a existir uma lista de tarefas isoladas, cada uma com estado e contexto próprios.

O que essa camada oferece

Recurso visual	O que oferece	Valor para a squad
Sessões na barra lateral	Lista trabalhos independentes e permite alternar entre eles	Torna visível o que está em execução e em qual estado
Worktree automático por sessão	Separa diretório e alterações sem configuração manual a cada tarefa	Reduz colisões locais e troca de branch no mesmo checkout
Filtros e agrupamento	Filtra por status, projeto ou ambiente e agrupa por projeto	Ajuda a acompanhar várias frentes sem misturar repositórios e contextos
Duas sessões lado a lado	Exibe dois trabalhos simultaneamente	Facilita comparar uma mudança com sua dependência ou acompanhar produtor e consumidor
Prefixo de branch configurável	Padroniza o nome das branches criadas nos worktrees	Facilita identificar origem, tarefa ou convenção da squad
Painéis de chat, plano, tarefas e subagent	Organiza raciocínio, execução e delegação dentro da sessão	Mantém o contexto da tarefa ligado ao código que está sendo alterado
Diff visual e comentários por linha	Permite revisar arquivos e devolver feedback ao Claude	Coloca a revisão antes do commit ou do PR
Terminal e editor integrados	Operam no diretório da mesma sessão	Evitam executar comando ou editar arquivo no worktree errado
PR e barra de CI	Acompanha verificações e pode tentar corrigir falhas quando configurado	Conecta execução local ao principal sensor de integração da squad
Arquivamento da sessão	Remove o worktree manualmente ou após o PR ser fechado ou integrado	Ajuda a controlar o acúmulo de ambientes locais temporários

Para mudanças que atravessam repositórios, uma sessão remota também pode receber vários repositórios, cada um com seu seletor de branch. Isso é útil quando uma squad altera um contrato e outras squads precisam atualizar os consumidores. Ainda assim, a tela apenas organiza as frentes; ela não decide compatibilidade, ordem de merge ou sequência de deploy.

Sessão isolada também no CLI

A documentação oficial mostra o início de uma sessão em um worktree próprio:

claude --worktree feature-auth

Você pode abrir outra sessão com outro nome e executar duas tarefas sem que as alterações locais colidam. O repositório precisa ter pelo menos um commit para que o Git consiga resolver a base. O fluxo está documentado em Common workflows.

Mudanças grandes com /batch

Para alterações que atravessam o repositório, a documentação do /batch descreve outro nível: o Claude Code pesquisa o código, propõe uma decomposição e, após aprovação, executa unidades independentes em worktrees separados. Cada unidade pode implementar, testar e abrir seu próprio PR.

Esse fluxo faz sentido para mudanças realmente separáveis, como atualizar vários módulos que obedecem ao mesmo contrato. Se todas as unidades dependem da mesma decisão arquitetural ou alteram o mesmo núcleo, a decomposição precisa acontecer antes do paralelismo.

O ciclo do PR

O Claude Code também consegue criar PRs, revisar diffs e acompanhar verificações. Onde disponível, /autofix-pr inicia uma sessão remota para observar falhas de CI e comentários de revisão. O Claude Code GitHub Actions leva o agente para eventos do repositório e permite automatizar tarefas ligadas ao PR.

Captura: Anthropic. O Claude Code Desktop mostra o estado das verificações do PR na sessão.

Essas opções transformam o PR no ponto de integração entre o trabalho do agente e os controles da squad. Elas não tornam merge automático uma boa decisão por padrão.

3. A unidade de trabalho liga tarefa, worktree e PR

O fluxo tradicional costuma ser representado assim:

Pessoa → branch → commit → pull request

Com agentes, eu usaria uma unidade mais explícita:

Tarefa + responsável humano
           ↓
Contrato de escopo e aceite
           ↓
Sessão do Claude Code
           ↓
Worktree + branch
           ↓
Implementação + testes locais
           ↓
Pull request
           ↓
CI + revisão inferencial + revisão humana
           ↓
Integração

O responsável humano continua aparecendo no começo. O agente pode produzir a mudança, mas alguém precisa responder pela decomposição, pelos limites de escrita e pela decisão de integrar.

Antes de abrir a sessão, a tarefa pode carregar um contrato pequeno:

task: adicionar exportação CSV
owner: squad-relatorios
owns:
  - src/export/**
must_not_change:
  - migrations/**
acceptance:
  - preserva os filtros atuais
  - neutraliza fórmulas em células exportadas
  - passa nos testes de exportação
integration:
  base_branch: main
  human_review: required

O worktree isola os arquivos. Esse contrato orienta o trabalho. Os testes e o review verificam se a mudança respeitou o combinado.

Quando a iniciativa atravessa squads, o contrato precisa carregar também a dependência entre entregas:

initiative: evoluir contrato de notificacoes
contract_owner: squad-plataforma
producers:
  - service-events
consumers:
  - app-web
  - app-mobile
compatibility: backward-compatible
merge_order:
  - contrato e produtor
  - consumidores
  - remoção da versão anterior
sensors:
  - contract tests
  - CI por repositório
  - revisão dos owners

Cada tarefa ainda pode ter seu worktree e seu PR. O que conecta as squads é o contrato compartilhado, a ordem explícita e os sensores de compatibilidade.

4. Cinco formas de adotar dentro e entre squads

Não começaria com todos os recursos ligados. Existem pelo menos cinco cortes possíveis.

Opção	Como funciona	Quando usar	Principal risco
1. Worktree assistido	Cada pessoa abre uma sessão com claude --worktree <tarefa>	Feature, bug e interrupções locais	Criar muitas branches sem disciplina de limpeza
2. Quadro visual no Desktop	A barra lateral organiza sessões e worktrees; painéis ligam tarefa, diff, PR e CI	Squads com várias frentes que precisam enxergar estado e contexto	Confundir visibilidade com coordenação e paralelizar tarefas dependentes
3. Contrato entre squads	Cada squad trabalha em seu worktree/PR, ligado por contrato, owners e ordem de integração	API, pacote compartilhado ou iniciativa multi-repo	Isolar execução e esquecer compatibilidade e rollout
4. Orquestração com /batch	Claude propõe unidades independentes e distribui em worktrees	Migração ou mudança repetitiva em módulos separados	Decomposição ruim multiplicar PRs e retrabalho
5. Loop de PR e CI	GitHub Actions, review e /autofix-pr reagem ao PR	Repositórios com testes confiáveis e critérios claros	Agente corrigir sintomas ou ampliar escopo sem limite

Minha recomendação seria começar pela opção 1 dentro de uma squad. Ela muda pouco o processo atual e torna o isolamento observável. Depois, escolher uma mudança pequena entre duas squads para testar a opção 3: contrato compatível, PRs ligados, owners definidos e ordem de integração explícita.

/batch entra por último. Ele amplia throughput, mas também amplia custo, volume de PRs e carga de integração. É uma ferramenta de orquestração para trabalho decomponível, não um botão universal de produtividade.

5. O harness precisa de guia e sensor

O coding agent é modelo + harness. Nesse caso, o harness do Claude Code fornece sessão, ferramentas, permissões, subagents e integração com Git. A squad ainda precisa construir o user harness do repositório: contexto, limites, testes, CI e regras de revisão.

Preocupação	Guia antes da geração	Tipo	Sensor depois da geração	Tipo	Eixo
Escopo da tarefa	contrato com owns e must_not_change	inferencial	script de paths + revisão humana	computacional + inferencial	behaviour
Convenções do repositório	CLAUDE.md e rules por caminho	inferencial	linter, formatter e review	computacional + inferencial	maintainability
Limites arquiteturais	mapa de módulos e dependências permitidas	inferencial	teste arquitetural + review de arquitetura	computacional + inferencial	architecture fitness
Comportamento esperado	critérios de aceite e exemplos	inferencial	testes unitários, integração e E2E	computacional	behaviour
Integração	branch base, ordem e responsável	inferencial	CI obrigatório e proteção de branch	computacional	behaviour
Contrato entre squads	owner, versão, compatibilidade e ordem de rollout	inferencial	contract tests + revisão dos owners	computacional + inferencial	architecture fitness / behaviour
Segurança	permissões mínimas e arquivos proibidos	computacional + inferencial	scanner, revisão de diff e aprovação humana	computacional + inferencial	behaviour

O worktree é infraestrutura computacional de isolamento. Ele não substitui nenhum desses sensores.

A interface também não vira sensor apenas porque exibe um status. O prefixo de branch, a base escolhida e o contrato da tarefa funcionam como guias antes da mudança. O diff comentado funciona como sensor inferencial; testes e proteções de branch são sensores computacionais. A barra de CI apenas traz o resultado desses sensores para a mesma superfície em que a sessão está sendo conduzida.

Se o CLAUDE.md disser “não quebre compatibilidade”, mas o CI não tiver teste de contrato, a equipe continua confiando numa instrução inferencial para proteger um comportamento objetivo. O harness fica mais forte quando a regra repetível vira sensor computacional.

6. Onde worktrees não resolvem o problema

O risco de promover a ferramenta sem seus limites é trocar um gargalo por outro.

Worktrees não resolvem:

• duas tarefas alterando o mesmo contrato, migration ou lockfile;
• ownership indefinido e incompatibilidade entre APIs de squads diferentes;
• ordem de deploy entre produtor e consumidores em repositórios separados;
• uma fila de review que já não acompanha a quantidade de PRs;
• ambientes locais disputando a mesma porta, banco ou recurso externo;
• testes lentos, instáveis ou incapazes de detectar regressão;
• branches longas acumulando divergência da base;
• custo e contexto consumidos por várias sessões simultâneas;
• responsabilidade difusa sobre quem aprova e integra cada mudança.

A camada visual também não conhece sozinha o fluxo develop → release/homolog → pacote de produção. Ela mostra a sessão e a branch associada, mas não impede que uma tarefa nasça da base errada, entre no pacote incorreto ou seja promovida fora de ordem. A política de branch é um guia; proteção de branch, testes e CI são os sensores computacionais que precisam barrar esses desvios.

Alguns arquivos ignorados podem precisar existir em cada worktree. O Claude Code oferece .worktreeinclude, mas eu trataria isso como allowlist de artefatos locais necessários. Credenciais e segredos não deveriam ser replicados automaticamente entre diretórios.

Também evitaria auto-merge no primeiro estágio. Antes, a squad precisa observar se os testes, a revisão e as proteções de branch realmente seguram os erros que importam.

7. Um rollout pequeno antes de escalar

Eu proporia dois experimentos reversíveis.

Primeiro, dentro de uma squad:

1. Escolher duas tarefas independentes e com testes confiáveis.
2. Definir responsável, arquivos permitidos e critérios de aceite.
3. Abrir uma sessão/worktree do Claude Code para cada tarefa.
4. Exigir PR separado, CI verde e revisão humana.
5. Registrar conflitos, reexecuções do CI, retrabalho e tempo de review.
6. Comparar com tarefas semelhantes feitas sem sessões paralelas.

Depois, entre duas squads:

1. Escolher uma mudança pequena de contrato ou biblioteca compartilhada.
2. Nomear o owner do contrato e os owners consumidores.
3. Definir compatibilidade, PRs dependentes e ordem de merge/deploy.
4. Executar cada parte em sessão e worktree próprios.
5. Exigir contract tests, CI por repositório e revisão cruzada.
6. Medir espera entre squads, falhas de integração e retrabalho.

Se o fluxo funcionar, o próximo passo é transformar o contrato da tarefa em template e mover regras determinísticas para CI. Só depois faz sentido experimentar /batch, rotinas ou correção automática de PR.

O sinal de sucesso não é “abrimos mais PRs”. Dentro da squad, é reduzir espera e troca de contexto sem aumentar regressões. Entre squads, é diminuir bloqueios de integração sem quebrar compatibilidade nem transferir retrabalho para outra equipe.

Foi isso que o curso mudou na minha leitura de Git. Em uma squad grande, branch continua sendo linha de mudança e PR continua sendo unidade de revisão. O worktree acrescenta a vaga isolada em que uma pessoa ou agente consegue trabalhar sem desmontar o ambiente dos demais. Entre squads, contratos, owners e sensores coordenam como essas vagas entregam partes compatíveis da mesma iniciativa.

E o Claude Code Desktop dá forma visual a essa capacidade do Git: a barra lateral organiza as sessões paralelas e os painéis mantêm por perto o contexto, as alterações, o PR e o CI. O mérito do harness é amarrar essas peças num fluxo que cada dev consegue acompanhar e retomar. A coordenação entre squads continua nas branches remotas, nos contratos, nos PRs e no CI. Foi essa combinação que me impressionou.

Onde está seu maior gargalo hoje: paralelismo dentro da squad ou dependências entre squads? E você começaria por worktree por tarefa, contrato compartilhado ou automação no ciclo do PR?