DEV Community

Cover image for Claude Code: organize agentes em paralelo com Git Worktrees
Tiago Vilas Boas (Montanha)
Tiago Vilas Boas (Montanha)

Posted on Edited on

Claude Code: organize agentes em paralelo com Git Worktrees

#ai #git #productivity #braziliandevs

Quando começamos a usar assistentes e agentes autônomos de código no dia a dia, um padrão comum acontece: você pede para o agente implementar uma feature complexa e, enquanto ele roda e testa os arquivos, surge um bug urgente em produção para você corrigir.

Se você estiver em um fluxo tradicional com um único terminal e uma única pasta de projeto, você entra em um beco sem saída:

  • Ou você faz git stash ou git commit -m "wip" correndo o risco de quebrar o raciocínio do agente;
  • Ou você espera o agente terminar para só depois abrir a branch de hotfix.

Pior ainda: se você rodar duas instâncias de agentes simultâneos na mesma pasta, um vai sobrescrever os arquivos e as variáveis que o outro acabou de salvar. É o caos da colisão de arquivos.

Neste artigo, vamos entender como resolver esse problema de raiz usando uma ferramenta nativa do próprio Git que existe há anos, mas que virou o maior superpoder da engenharia moderna com agentes: o Git Worktrees.

A Analogia da Oficina Mecânica

Pense no seu repositório como uma grande oficina mecânica:

[ Abordagem Tradicional: Apenas 1 Vaga ]
                      ┌──────────────────────┐
                      │    Única Vaga (Box)  │
                      │  (Mesma Pasta Local) │
                      └──────────┬───────────┘
                                 │
                 ┌───────────────┴───────────────┐
                 │                               │
                 ▼                               ▼
       [ Agente 1: Feature ]           [ Dev: Hotfix Urgente ]
       (Montando motor novo)           (Tentando trocar pneu)
                 │                               │
                 └───────────────┬───────────────┘
                                 ▼
                     CONFLITO / DESMANCHE TOTAL!
Enter fullscreen mode Exit fullscreen mode

Com o Git Worktree, você não divide a mesma vaga. Você abre baias de trabalho totalmente independentes na mesma oficina, todas compartilhando o mesmo estoque de peças (o histórico do .git), mas com carros separados:

[ Abordagem com Git Worktree: Múltiplas Vagas Independentes ]

                       ┌────────────────────────┐
                       │   Histórico Git Local  │
                       │   (.git compartilhado) │
                       └───────────┬────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
   [ Vaga 1: Main ]        [ Vaga 2: Feature ]       [ Vaga 3: Hotfix ]
   pasta: repo-main/       pasta: repo-feat/         pasta: repo-hotfix/
   branch: main            branch: feature/api       branch: bugfix/auth
         │                         │                         │
   (Código estável)       (Agente rodando testes)   (Dev alterando código)
Enter fullscreen mode Exit fullscreen mode

Nenhum arquivo colide, nenhuma dependência é sobrescrita e nenhuma sessão precisa esperar a outra terminar.

O Que é Git Worktree na Prática?

Em um fluxo Git comum, você clona um repositório e tem exatamente uma pasta de trabalho vinculada a uma branch ativa por vez.

Com git worktree, você pode fazer o checkout de múltiplas branches ao mesmo tempo em pastas físicas diferentes no seu disco rígido, sem precisar clonar o repositório inteiro novamente:

# Dentro do seu repositório principal
git worktree add ../projeto-feature-export feature/exportacao
Enter fullscreen mode Exit fullscreen mode

Esse comando cria uma pasta novinha em folha (../projeto-feature-export), configurada na branch feature/exportacao, pronta para receber uma sessão dedicada do seu agente de IA.

Quando a tarefa termina e o Pull Request é aberto, você descarta a vaga com um único comando:

git worktree remove ../projeto-feature-export
Enter fullscreen mode Exit fullscreen mode

A Integração com o Claude Code

O mérito do Claude Code Desktop e do CLI não foi inventar o Git Worktree, mas sim integrá-lo como recurso nativo de primeira classe na experiência de desenvolvimento.

1. No CLI (Terminal)

Você pode abrir uma sessão totalmente isolada em um worktree temporário diretamente da linha de comando:

claude --worktree feature-checkout-auth
Enter fullscreen mode Exit fullscreen mode

O Claude Code cria a branch, monta o worktree isolado e garante que nenhuma alteração interfira no seu terminal principal.

2. No Claude Code Desktop

Na interface gráfica, cada nova sessão na barra lateral pode ser associada a um worktree automático. Isso transforma a ferramenta em um verdadeiro painel de controle operacional:

Projeto: Voomp Core
├── Sessão 1: Refatoração de Checkout (Em andamento - Worktree isolado)
├── Sessão 2: Correção de Webhook Pagarme (Testes passando - PR aberto)
└── Sessão 3: Atualização de Dependências (Aguardando revisão humana)
Enter fullscreen mode Exit fullscreen mode

Você visualiza o diff em tempo real, os testes locais rodando e a barra de CI sem que uma tarefa contamine o ambiente da outra.

O Ciclo Completo: Da Tarefa ao Pull Request

Para que o trabalho paralelo funcione sem gerar dívida técnica, a unidade de trabalho precisa seguir um fluxo disciplinado:

Definição da Tarefa + Critérios de Aceite
                 │
                 ▼
Criação do Worktree Isolado (`git worktree add`)
                 │
                 ▼
Execução do Agente (Implementação + Testes Locais)
                 │
                 ▼
Verificação Automatizada (Linters, Testes Unitários)
                 │
                 ▼
Abertura do Pull Request (CI + Revisão Humana)
                 │
                 ▼
Merge e Limpeza do Worktree (`git worktree remove`)
Enter fullscreen mode Exit fullscreen mode

O Contrato da Tarefa

Antes de deixar o agente alterar código no worktree, passe instruções claras de limites de escrita para evitar que ele altere arquivos fora do escopo:

tarefa: Adicionar exportação de relatórios em CSV
pasta_permitida: src/reports/**
nao_alterar: src/auth/**, database/migrations/**
criterios_aceite:
  - Preservar os filtros de data existentes
  - Garantir cobertura de testes unitários para valores nulos
Enter fullscreen mode Exit fullscreen mode

Matriz de Decisão: Onde Worktrees Ajudam e Onde Não Resolvem

Nem todo problema de engenharia se resolve isolando pastas. É fundamental saber a fronteira da técnica:

Cenário Worktrees Resolvem? Explicação Prática
Dois agentes mexendo no mesmo repo ao mesmo tempo Sim Cada agente opera em sua pasta física isolada sem colisão de escrita
Pausar feature para resolver bug urgente Sim Você abre o hotfix em outro worktree sem precisar fazer stash da feature
Conflitos de merge em migrations de banco Não Se duas tarefas alteram a mesma tabela, o conflito vai acontecer no merge remoto
Disputa por portas locais (ex: porta 3000) Atenção Ambos os worktrees vão tentar subir o servidor na mesma porta; configure portas dinâmicas
Consumo excessivo de memória RAM Atenção Cada worktree com node_modules ou compilações simultâneas consome memória da máquina

Para evitar gastos desnecessários de tokens e latência com múltiplos agentes rodando em paralelo, você pode orquestrar modelos usando o Downshift (harness-downshift) localmente para classificar a complexidade de cada tarefa antes de chamar modelos de ponta via OpenRouter ou Anthropic.

Referências Didáticas e Vídeos Recomendados

Para quem quer dominar Git Worktrees e fluxos modernos com IA:

Passo a Passo para Testar Hoje Mesmo

Você não precisa esperar uma migração de ferramentas para começar. Teste agora com 3 comandos simples no seu terminal:

# 1. Crie uma nova vaga de trabalho para uma branch de teste
git worktree add ../teste-paralelo -b minha-branch-teste

# 2. Acesse a pasta isolada
cd ../teste-paralelo

# 3. Abra o seu editor ou agente nesta pasta e trabalhe livremente!
Enter fullscreen mode Exit fullscreen mode

Quando terminar, volte para a pasta principal e desmonte a vaga:

cd ../meu-projeto-original
git worktree remove ../teste-paralelo
Enter fullscreen mode Exit fullscreen mode

O isolamento com Git Worktrees transforma o paralelismo de agentes de um pesadelo de arquivos corrompidos em uma esteira de engenharia fluida, previsível e profissional.

Top comments (1)