Usando Git Worktrees com Agentes de Codificação de IA

A forma confiável de executar múltiplos agentes de codificação de IA em um único repositório é: uma tarefa, um branch, um worktree, um agente — cada agente recebe seu próprio diretório criado com git worktree add, trabalha em seu próprio branch e nunca toca nos arquivos que outro agente está editando.

A maioria dos desenvolvedores chega a esse padrão pelo caminho mais difícil. Dois agentes em um mesmo checkout sobrescrevem silenciosamente as edições incompletas um do outro, ou um agente trava tentando fazer checkout de um branch que já está em checkout em outro lugar. Este artigo trata especificamente do workflow de agentes: o que o padrão isola, o que ele deliberadamente não isola e o que fazer quando três agentes terminam ao mesmo tempo.

O Padrão Git Worktree para Agentes de IA

O padrão de um-agente-por-worktree exige dois comandos por tarefa. Crie um worktree com um branch novo baseado no main e então inicie um agente dentro dele:

git worktree add ../task-a -b agent/task-a main
git worktree add ../task-b -b agent/task-b main

Aponte um agente para ../task-a e outro para ../task-b. Cada um tem seu próprio diretório de trabalho, seu próprio índice e seu próprio HEAD, enquanto todos os worktrees compartilham o mesmo banco de objetos e as mesmas refs, de modo que commits feitos em um são imediatamente visíveis a partir dos outros. Vincule o worktree à tarefa, não ao agente: crie-o quando o trabalho começar e exclua-o quando o branch for mesclado. A Anthropic documenta essa mesma sequência manual no guia de worktrees do Claude Code, e o Cursor executa agentes em worktrees isolados a partir da sua Agents Window; o Codex funciona da mesma maneira quando apontado para um diretório.

Por Que Um Único Diretório Compartilhado Falha?

Dois agentes em um mesmo diretório falham silenciosamente: nem o git nem os agentes emitem erro quando um sobrescreve as edições não commitadas do outro, então o dano só aparece no momento da revisão. A detecção de conflitos do git compara commits; escritas concorrentes na mesma working tree nunca chegam a esse ponto.

A segunda falha é mais ruidosa, mas pior. Operações git concorrentes em um diretório compartilhado colidem no .git/index.lock, e se um agente quebra enquanto mantém o lock, o arquivo obsoleto bloqueia os comandos git de todos os outros agentes até que alguém o exclua manualmente. Alguns agentes tentam novamente; outros desistem de commitar e continuam gerando código sobre um estado não commitado sem limites. Worktrees separados dissolvem os dois problemas, porque cada worktree faz o staging contra seu próprio índice, e não contra um compartilhado.

O Que Um Novo Worktree Não Contém

Um novo worktree contém apenas arquivos rastreados, então node_modules, .env, caches de build e qualquer outra coisa no gitignore estão ausentes até que você os crie. Um agente iniciado em um worktree vazio vai falhar na primeira execução de testes ou, pior, vai “gentilmente” reescrever configurações para compensar. Faça o bootstrap de cada worktree antes de o agente começar:

cd ../task-a
npm ci
cp ../main-repo/.env .env

npm ci é a instalação correta aqui: ele foi feito para ambientes limpos e instala exatamente o que o lockfile especifica. Se o seu agente for o Claude Code, um arquivo .worktreeinclude pode levar arquivos ignorados pelo git, como o .env, para os worktrees que o próprio Claude Code cria, mas isso não se aplica a worktrees que você cria manualmente com git worktree add — por isso a cópia manual funciona para qualquer ferramenta.

O Que Worktrees Não Isolam

Worktrees isolam arquivos, não o runtime: portas, bancos de dados, volumes Docker e caches compartilhados pertencem à máquina, então dois servidores de desenvolvimento iniciados a partir de dois worktrees continuam disputando a porta 3000. A fronteira do diretório não significa nada para qualquer coisa endereçada por hostname ou porta.

Dê a cada worktree sua própria porta e seu próprio banco de dados antes de iniciar um agente que execute migrations, porque uma alteração de schema feita através de um worktree atinge qualquer banco de dados que os outros compartilhem. Defina ambos no .env copiado:

# ../task-a/.env
PORT=3001
DATABASE_URL=postgres://localhost:5432/app_agent_task_a

Nomear o banco de dados de acordo com o branch facilita identificar e descartar os obsoletos depois. Containers também podem isolar a camada de runtime, mas isso envolve trade-offs que rendem um artigo à parte.

Como Informar ao Agente Que Ele Está em um Worktree?

Um branch só pode estar em checkout em um worktree por vez, então um agente que tenta sincronizar executando git checkout main recebe um erro e frequentemente empaca. O manual do git checkout descreve esse comportamento e aponta --ignore-other-worktrees como a forma de sobrescrevê-lo. Não deixe o agente descobrir isso em tempo de execução; coloque no arquivo de instruções que o agente lê (AGENTS.md, CLAUDE.md ou equivalente):

You are working inside a git worktree.
Stay on the current branch. Never run `git checkout` or `git switch`.
To sync with main, run `git fetch origin` and `git rebase origin/main`.

Quando um agente só precisa ler ou buildar um commit específico, dispense os branches por completo: git worktree add --detach cria um worktree com HEAD desanexado (detached), o que contorna totalmente a regra de exclusividade.

git worktree add --detach ../review-b1a2c3 b1a2c3

Como Integrar o Que Volta?

Worktrees não eliminam conflitos de merge; eles os movem de sobrescritas silenciosas em tempo de execução para conflitos visíveis no momento do merge, onde o ferramental normal do git dá conta. Quando vários agentes terminam juntos, integre serialmente: faça o merge de um branch, aplique rebase do próximo sobre o main atualizado, faça o merge dele e repita.

cd ../main-repo
git merge agent/task-a

cd ../task-b
git rebase main
cd ../main-repo
git merge agent/task-b

Cada rebase expõe conflitos contra tudo o que já foi mesclado, um branch por vez, em vez de acumular surpresas de merge de três vias. A regra de ordenação está a montante do merge: tarefas que tocam os mesmos arquivos, ou nas quais uma consome a saída da outra, devem ser sequenciadas em vez de paralelizadas. Nenhum arranjo de worktrees corrige uma decomposição de tarefas que nunca foi independente.

Quantos Agentes, e Quando Limpar

O teto prático não é o git nem o disco; é a sua capacidade de revisão, já que cada agente paralelo produz um branch que você precisa ler, testar e mesclar. Equipes que publicam sobre esse workflow, como o time de engenharia da incident.io, descrevem rodar quatro ou cinco agentes ao mesmo tempo, e a maioria dos desenvolvedores acha que menos já é suficiente. Quando um branch é mesclado, execute git worktree remove ../task-a; como o bootstrap adicionou arquivos não rastreados, espere precisar de --force, que o git worktree remove exige para worktrees não limpos. Se um diretório foi excluído com rm -rf em vez disso, o git worktree prune limpa os metadados obsoletos que o git ainda mantém.

Começando Com Dois Agentes

Uma tarefa, um branch, um worktree, um agente transforma agentes paralelos de uma fonte de corrupção silenciosa em um conjunto de branches revisáveis. Comece com dois: crie os worktrees, faça o bootstrap de cada um com npm ci e um .env por tarefa, adicione a instrução de permanecer no branch e pratique a sequência rebase-depois-merge antes de escalar além do que você realmente consegue revisar.

Perguntas Frequentes

Devo usar git worktrees ou clones separados para executar agentes de IA em paralelo?

Worktrees geralmente são melhores porque compartilham um único banco de objetos, então um commit feito em um worktree fica imediatamente visível a partir dos outros sem push ou fetch, e o histórico é armazenado apenas uma vez em disco. Clones separados duplicam todo o histórico e precisam de push e fetch para trocar commits. Clones só levam vantagem quando você precisa de isolamento completo, como em repositórios com submodules.

Git worktrees funcionam com repositórios que usam submodules?

Apenas parcialmente. O próprio manual de worktree do Git registra o suporte a submodules na seção BUGS, classifica múltiplos checkouts como experimental e recomenda não fazer checkout de um superprojeto em mais de um lugar ao mesmo tempo. Um worktree que contém submodules também não pode ser realocado com git worktree move. Para agentes em paralelo em um repositório com submodules, clones completos separados são o mecanismo de isolamento mais seguro, mesmo que dupliquem o histórico e exijam push para compartilhar commits entre checkouts.

Todos os git worktrees compartilham a mesma configuração do git?

Sim. Todo worktree lê a mesma configuração do repositório, a menos que você opte por sair disso. Para dar a um worktree suas próprias configurações, execute git config extensions.worktreeConfig true e então grave os valores com git config --worktree, que os mantém no arquivo config.worktree daquele worktree. O trade-off: versões mais antigas do Git não conseguirão abrir o repositório depois que a extensão estiver ativada.

Remover um worktree exclui o branch do agente?

Não. Branches são refs compartilhadas por todo o repositório, então git worktree remove exclui o diretório de trabalho e seus metadados, mas mantém intactos o branch e todos os commits nele. Apenas alterações não commitadas naquele diretório são perdidas, e é por isso que o remove recusa worktrees não limpos a menos que você passe --force. Exclua o branch separadamente com git branch -d depois que ele for mesclado.