Git worktree para agentes de IA: o guia que inclui o que quebra

Resposta curta: git worktree add -b nome ../pasta cria uma cópia do projeto em outra pasta, ligada ao mesmo repositório, numa branch separada. É assim que cada agente de IA trabalha sem sobrescrever o outro. O que os guias não contam é que a cópia nasce sem node_modules, sem .env e sem build, e é aí que a maioria das tentativas trava.

O comando, e o que ele faz

git worktree add -b agente/tarefa ../projeto-tarefa\ncd ../projeto-tarefa

Isso cria uma pasta nova com todos os arquivos versionados, numa branch nova, compartilhando o mesmo histórico. Não é um clone: o repositório é o mesmo, então commits aparecem para todo mundo e não há upload nem download envolvido. Ao terminar, git worktree remove ../projeto-tarefa.

O que NÃO vem junto (a parte que trava)

Só o que está versionado é copiado. Tudo que o .gitignore exclui fica para trás, e é justamente o que o projeto precisa para rodar:

• Dependências (node_modules, vendor): precisam ser instaladas na worktree. Um atalho comum é criar um link simbólico para a pasta principal, e para node_modules costuma funcionar. Para dependências de linguagens que resolvem caminho de arquivo, como o autoloader do PHP, o link pode fazer o agente de IA carregar o código da OUTRA branch sem avisar, e você passa a depurar um comportamento que não está no código que está lendo.
• Variáveis de ambiente (.env): link simbólico resolve, e aqui é seguro, porque é arquivo de texto lido uma vez.
• Build do front: se o seu framework procura um manifesto gerado, ele não existe na worktree nova e a página quebra com um erro que não menciona worktree nenhuma.

O banco de dados é compartilhado, e isso é uma armadilha

A worktree não isola o banco. Se um agente de IA roda uma migration destrutiva, ele afeta o banco de todos os outros e o seu. Vale ter isso explícito nas instruções do projeto, e vale que os testes usem um banco em memória em vez do banco de desenvolvimento.

Quando NÃO vale a pena

Com um agente de IA por vez, não vale: você paga o custo de preparar o ambiente e não ganha isolamento nenhum, porque não há com quem colidir. Também não vale para tarefas de leitura, como investigar ou explicar código, que não escrevem nada. O isolamento existe para escrita concorrente, e só se paga a partir de três ou quatro frentes simultâneas.

Worktree ou contêiner?

Worktree é mais leve e mais rápido: são arquivos no mesmo disco, e o agente continua enxergando as ferramentas da sua máquina. Contêiner isola mais fundo, inclusive processo e rede, e é o que você quer se pretende deixar um agente rodando sem supervisão. Para trabalho supervisionado no seu próprio Mac, worktree basta.

Como saber quem está em qual worktree

git worktree list mostra todas, com a branch de cada uma. É o comando que responde "quem está mexendo em quê" quando você tem cinco agentes de IA abertos e perdeu a conta.

E quando duas worktrees mexem no mesmo arquivo?

Vai acontecer, e o certo é que apareça cedo. Com isolamento, cada um trabalha na sua cópia e a colisão surge na hora de juntar, com o Git mostrando as duas versões lado a lado. O que você não quer é descobrir isso pelo teste que começou a falhar sem motivo aparente.