Você está rodando o Claude Code em uma branch de feature. O agente já trabalhou por 20 minutos, leu sua base de código e começou a fazer progresso real. Então chega a mensagem no Slack: produção caiu, alguém precisa de um hotfix no main agora. Você faz stash, troca de branch, perde todo o contexto que o agente construiu, corrige o bug, volta — e gasta mais 10 minutos reorientando o agente.
Se estiver rodando dois agentes em paralelo no mesmo diretório, a situação é pior: ambos editam os mesmos arquivos, e o segundo sobrescreve o primeiro silenciosamente. Nenhum aviso. Apenas trabalho corrompido que você descobre uma hora depois.
Os Git Worktrees eliminam essa classe inteira de problemas. Não são uma invenção nova — o recurso existe desde o Git 2.5 (2015) — mas a onda de agentes de IA para código em 2025-2026 os tornou infraestrutura essencial.
O que são Git Worktrees
Um repositório Git padrão tem um único diretório de trabalho. Para alternar entre branches, você muda todos os arquivos daquele diretório. Se tem trabalho não commitado, precisa fazer stash. Se o agente de IA está no meio de uma tarefa, você o interrompe.
Um worktree é um diretório separado fazendo checkout do mesmo repositório. Você pode ter quantos precisar, cada um em sua própria branch, todos coexistindo simultaneamente no sistema de arquivos:
meu-projeto/ # worktree principal (branch: main)
meu-projeto-feat-auth/ # worktree vinculado (branch: feat/auth)
meu-projeto-feat-api/ # worktree vinculado (branch: feat/api)
meu-projeto-hotfix-login/ # worktree vinculado (branch: hotfix/login)
Todos os diretórios compartilham a mesma pasta .git. Compartilham histórico, objetos e commits. Mas cada um tem seus próprios arquivos, seu próprio índice e seu próprio estado de trabalho. Um agente editando em meu-projeto-feat-auth/ não pode ver nem tocar em nada dentro de meu-projeto-feat-api/.
Por que isso é melhor que múltiplos clones? A alternativa ingênua é clonar o repositório duas vezes. Isso duplica todo o histórico em disco, os commits em um clone não são imediatamente visíveis no outro, e não há coordenação entre eles na camada Git. Com worktrees, você clona uma vez. Cada worktree adicional custa apenas o espaço dos arquivos em checkout.
Os 7 comandos que você precisa
| Comando | O que faz |
|---|---|
git worktree add <caminho> -b <branch> | Cria novo worktree em nova branch |
git worktree add <caminho> <branch> | Checkout de branch existente em novo worktree |
git worktree list | Lista todos os worktrees ativos com branches e hashes |
git worktree lock <caminho> | Impede que o worktree seja removido (use com agente rodando) |
git worktree unlock <caminho> | Libera o bloqueio |
git worktree remove <caminho> | Remove o worktree após merge |
git worktree prune | Limpa metadados de worktrees removidos manualmente |
Rodando agentes de IA em paralelo
O fluxo real com agentes como Claude Code ou Codex:
# Criar worktrees isolados para cada tarefa
git worktree add ../meu-projeto-feat-auth -b feat/auth
git worktree add ../meu-projeto-hotfix -b hotfix/login
# Cada worktree é um diretório independente
cd ../meu-projeto-feat-auth && claude "implemente autenticação OAuth"
cd ../meu-projeto-hotfix && claude "corrija o bug de timeout no login"
Cada agente trabalha em seu próprio diretório, em sua própria branch, sem risco de colisão. Nenhum arquivo é sobrescrito. Quando ambas as tarefas terminam, você faz merge de cada branch no main como faria normalmente.
Dica prática: use git worktree lock enquanto um agente está ativo para evitar remoção acidental. Ao terminar a tarefa e fazer merge, use git worktree remove para liberar o espaço.
Evitando que os worktrees fiquem desatualizados
Worktrees não se atualizam sozinhos. Se o main avança enquanto seu agente trabalha em feat/auth, você precisa sincronizar manualmente:
# Do worktree da feature
git fetch origin
git rebase origin/main # ou git merge origin/main
Estabeleça uma rotina: antes de iniciar um agente, faça rebase. Após concluir, faça rebase novamente antes do merge. Isso mantém o histórico limpo e evita conflitos surpresa.
Erros comuns e correções
- ❌ “fatal: ‘xyz’ is already checked out” → Você tentou criar um worktree para uma branch que já está em checkout em outro lugar. Use
git worktree listpara encontrar onde e mude para lá ou remova o worktree antigo. - ❌ “fatal: invalid reference” → A branch que você especificou não existe. Crie-a com
-bou verifique o nome. - ❌ Worktree órfão após remover diretório manualmente → Se você deletou a pasta sem usar
git worktree remove, executegit worktree prunepara limpar os metadados. - ❌ Merge conflict ao tentar remover worktree → O Git não remove worktrees com alterações não commitadas. Faça commit ou stash antes de remover.
- ❌ Agentes conflitando em
package.json→ Isso acontece quando ambos estão no mesmo diretório. Worktrees resolvem isso completamente: cada agente tem sua própria cópia do arquivo.
Por que isso importa agora
Em 2026, 51% dos desenvolvedores profissionais usam ferramentas de IA diariamente, mas apenas 17% dos que usam agentes de IA dizem que essas ferramentas melhoraram a colaboração em equipe. A lacuna entre esses números não é um problema de ferramenta — é um problema de infraestrutura. Times adotaram agentes de IA sem a camada de workflow por baixo.
Git Worktrees são essa camada. Simples, nativos do Git desde 2015, e resolvem o problema fundamental de agentes trabalhando em paralelo sem se atropelarem.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
