eu tô escrevendo um livro sobre claude code. no capítulo de paralelização, fui pesquisar a fundo como rodar múltiplas instâncias de agente no mesmo repositório sem que uma pise no pé da outra. e aí caí num buraco de coelho chamado git worktree.
o mais engraçado? a feature existe desde 2015. tava ali, quietinha, esperando a gente ter o problema certo.
o que é git worktree
worktree permite criar múltiplos diretórios de trabalho vinculados ao mesmo repositório. cada diretório fica em um branch diferente, mas todos compartilham o mesmo .git.
na prática:
git worktree add ../meu-repo-fix hotfix/loginisso cria uma pasta meu-repo-fix ao lado do seu repo original, já no branch hotfix/login. você edita, commita, faz push — tudo independente. quando terminar:
git worktree remove ../meu-repo-fixsem stash. sem clone. sem duplicar nada.
pra que criaram isso
os casos de uso originais eram legítimos:
hotfix sem interromper o que você tá fazendo. imagina que você tá no meio de uma refatoração pesada, unstaged changes pra todo lado, e aparece um bug crítico em produção. antes de worktree, suas opções eram git stash (e rezar pra lembrar de dar pop depois) ou clonar o repo inteiro. com worktree, você abre outro diretório, faz o fix, e volta pro seu trabalho como se nada tivesse acontecido.
review de pr com contexto real. em vez de ficar dando checkout entre branches e perdendo o estado do seu editor, você abre o pr num worktree separado. roda os testes, navega o código, fecha, e seu branch principal continua intacto.
builds paralelos. ci local, comparação de performance entre branches, rodar a suite de testes de uma branch enquanto desenvolve em outra.
por que quase ninguém usava
com todo respeito aos casos acima: git stash e git clone resolviam. não resolviam bonito, mas resolviam.
o workflow da maioria dos devs é linear. você tá num branch, termina, abre pr, vai pro próximo. o cenário de “preciso de dois branches ao mesmo tempo” aparecia, sei lá, uma vez por mês? e quando aparecia, um stash resolvia em 5 segundos.
clone duplicava o .git inteiro e desperdiçava espaço, mas pra um repo de 50mb? ninguém sentia. disco é barato e a maioria dos projetos não chegava nem perto de ser grande o suficiente pra isso doer.
worktree era a resposta elegante pra uma pergunta que pouca gente fazia.
aí chegaram os agentes de código
agora imagina o seguinte cenário: você quer que três instâncias de claude code trabalhem em paralelo no mesmo repositório. uma fazendo os testes de uma api, outra refatorando o módulo de autenticação, outra atualizando a documentação.
se as três operam no mesmo diretório, é caos. uma muda um arquivo que a outra tá lendo. conflitos de estado por todo lado. o agente não sabe que outro agente mexeu no package.json dois segundos atrás.
clonar o repo três vezes num projeto pequeno é imperceptível. mas pensa num monorepo de verdade — 1gb, 2gb de histórico. três clones são 3gb a 6gb de .git duplicado na sua máquina. cinco agentes em paralelo e você tá torrando disco e tempo de clone pra copiar dados que já existem ali do lado.
worktree compartilha o .git. não importa se você criar três ou dez worktrees: o histórico do repositório existe uma vez só. cada worktree adiciona só os arquivos do working directory daquele branch. num monorepo grande, a diferença entre clone e worktree não é conveniência — é viabilidade.
em vez de multiplicar o peso do repositório, worktree resolve isso de forma cirúrgica:
git worktree add ../repo-testes feat/testes-api
git worktree add ../repo-auth refactor/auth
git worktree add ../repo-docs update/docstrês diretórios. três branches. um único .git. cada agente no seu canto, isolado, sem interferir nos outros. quando cada um termina, você faz merge normalmente.
a feature que era “legal mas dispensável” pra um dev solo virou infraestrutura essencial pra quem orquestra agentes.
como o claude code usa isso
o claude code tem suporte nativo a worktrees. quando você quer paralelizar tarefas, o fluxo é:
claude --worktreeele cria um worktree automaticamente, faz o trabalho no branch isolado, e você decide o que fazer com o resultado. sem configuração manual, sem risco de colisão.
e aqui entra um detalhe que amarra tudo: cada worktree pode ter seu próprio CLAUDE.md. isso significa que você pode dar contexto específico pra cada agente dependendo da tarefa.
o worktree que tá escrevendo testes? o CLAUDE.md dele pode dizer “use vitest, siga o padrão de test factories que já existe no projeto, nunca mocke o banco”. o que tá refatorando auth? “mantenha compatibilidade com a api pública, não mude assinaturas de função sem flag de deprecation”.
cada agente recebe o contexto que precisa, opera no seu espaço isolado, e entrega um branch limpo pra review. é bonito de ver funcionando.
a lição que eu levo disso
a gente tende a avaliar ferramentas pelo problema de hoje. worktree em 2015 resolvia um incômodo menor. worktree em 2026 resolve um problema estrutural de como a gente trabalha com ia.
ninguém na equipe do git pensou “um dia vão rodar cinco agentes de ia no mesmo repo e precisar de isolamento de working directory”. eles pensaram em hotfixes e builds paralelos. mas a abstração era boa o suficiente pra sobreviver a uma mudança de paradigma inteira.
isso me lembra que vale prestar atenção nas features “obscuras” das ferramentas que a gente já usa. às vezes a solução pro problema de amanhã já tá instalada na sua máquina — só falta o problema aparecer.
to sempre no linkedin e no github. se quiser trocar ideia sobre agentes, git, ou qualquer coisa nesse universo, me chama.