Git worktree no Claude Code: tarefas em paralelo sem conflito
Aprenda a usar git worktree com o Claude Code para rodar tarefas em paralelo em pastas isoladas e revisar cada resultado antes de mesclar na main.
Quer aplicar isso na sua empresa?
Agendar conversa com o Juan →Git worktree no Claude Code: tarefas em paralelo sem conflito
Para usar git worktree com o Claude Code, crie um worktree por tarefa, cada um com sua própria branch e sua própria pasta, e abra uma sessão do Claude Code dentro de cada pasta. Assim as sessões não editam os mesmos arquivos ao mesmo tempo, e você revisa cada resultado separadamente antes de mesclar na branch principal.
Principais pontos
- Um worktree é uma pasta de trabalho extra do mesmo repositório, com branch própria. Ele isola os arquivos em edição, não o ambiente inteiro.
- Uma sessão do Claude Code por worktree evita que duas tarefas pisem nos mesmos arquivos ou troquem a branch uma debaixo da outra.
- O isolamento vale durante o trabalho. Conflitos de lógica ainda podem aparecer na mescla, por isso a revisão e a ordem de mesclagem importam.
- Dependências, variáveis de ambiente, portas e bancos de dados compartilhados continuam sendo pontos de atenção em cada pasta.
- Cada tarefa precisa de escopo escrito, comando de teste e critério de aceite antes de a sessão começar.
O que é um git worktree e por que ele evita conflito entre sessões?
Normalmente, um repositório Git tem uma pasta de trabalho e uma branch ativa nela. Se você abre duas sessões do Claude Code nessa mesma pasta, as duas leem e escrevem nos mesmos arquivos. Uma pode ler um arquivo que a outra deixou pela metade, ou uma pode trocar de branch enquanto a outra ainda trabalha. O resultado é uma mistura de mudanças difícil de separar depois.
A documentação oficial do Git descreve o git worktree como a forma de manter várias árvores de trabalho ligadas ao mesmo repositório. O histórico e os objetos ficam compartilhados. Cada pasta tem seus arquivos e seu índice próprios, e uma mesma branch normalmente não pode estar ativa em dois worktrees ao mesmo tempo. Isso é exatamente a proteção que a execução paralela precisa.
A alternativa é clonar o repositório várias vezes. Funciona, mas duplica o histórico e exige sincronizar cada cópia. O worktree é mais leve e mantém tudo conectado, inclusive para listar e remover as pastas depois.
Quando vale rodar tarefas em paralelo e quando não vale?
Paralelizar só ajuda quando as tarefas são realmente independentes. Um guia de decisão simples:
- Vale paralelizar quando as tarefas mexem em áreas diferentes do código, como uma correção de cálculo, um ajuste de texto e uma atualização de documentação.
- Vale paralelizar quando cada tarefa tem um teste ou uma verificação própria que diz se terminou.
- Vale paralelizar quando você consegue revisar cada resultado sem depender do outro.
- Não vale paralelizar quando duas tarefas alteram o mesmo módulo, o mesmo arquivo de configuração ou o mesmo esquema de banco.
- Não vale paralelizar quando a segunda tarefa depende da decisão tomada na primeira. Faça em sequência.
- Não vale paralelizar quando você não tem tempo de revisar. Três resultados sem revisão são pior do que um resultado revisado.
O gargalo real costuma ser a sua atenção para revisar, não a velocidade da IA. Comece com duas tarefas, não com cinco.
Como criar os worktrees e iniciar o Claude Code em cada um?
O passo a passo abaixo usa apenas comandos do próprio Git. A documentação do Claude Code também descreve o uso de worktrees para sessões paralelas, e algumas versões podem oferecer atalhos para isso. Confira a documentação da versão que você usa antes de depender de um atalho.
- Passo um: no repositório principal, confirme que a branch principal está limpa e atualizada, com git status e git pull.
- Passo dois: crie um worktree por tarefa, em uma pasta irmã do repositório, com uma branch nova. Exemplo: git worktree add ../meuapp-fatura -b fix/calculo-fatura
- Passo três: repita para as outras tarefas, cada uma com pasta e branch próprias. Prefira pastas fora do repositório para não sujar o git status da pasta principal.
- Passo quatro: em cada pasta, prepare o ambiente. Instale as dependências, copie as variáveis de ambiente necessárias e confirme que o teste básico roda.
- Passo cinco: abra um terminal por pasta, entre nela e inicie o claude. Entregue um escopo escrito: objetivo, arquivos que pode alterar, comando de teste e o que não deve ser feito.
- Passo seis: acompanhe o conjunto com git worktree list, que mostra cada pasta e a branch associada.
- Passo sete: quando a tarefa terminar, revise (próxima seção), mescle e remova o worktree com git worktree remove seguido do caminho da pasta. Depois apague a branch já mesclada.
Se você repete esse escopo toda semana, vale transformá-lo em instrução reutilizável. O artigo sobre skills no Claude Code mostra como padronizar isso para a equipe.
O que o worktree não isola?
O worktree separa arquivos versionados. Muita coisa que afeta o resultado fica fora disso, e é aqui que surgem os conflitos inesperados.
- Arquivos não versionados: o arquivo de variáveis de ambiente e as dependências instaladas não vêm junto. Cada pasta precisa do seu preparo.
- Portas: dois servidores de desenvolvimento tentando usar a mesma porta vão colidir. Defina uma porta por worktree.
- Banco de dados e serviços: se todos os worktrees apontam para o mesmo banco de desenvolvimento, uma migração de uma tarefa afeta as outras. Use bancos de teste separados ou desative tarefas que alterem o esquema em paralelo.
- Efeitos externos: uma sessão que dispara mensagens reais, chamadas de API ou escrita em sistemas da empresa age no mundo, não na pasta. Use credenciais de teste e ambientes de homologação.
- Contexto da IA: cada sessão tem sua própria janela de contexto e não sabe o que a outra decidiu. Se uma decisão vale para as duas, escreva no escopo de ambas. Veja mais em janela de contexto em IA.
- Permissões: rodar várias sessões multiplica o que pode ser executado na sua máquina. Para código gerado por IA, considere um ambiente restrito, como descrito em sandbox para código gerado por IA.
Como revisar cada resultado antes de mesclar?
A revisão é a parte que torna o paralelismo seguro. Trate cada branch como se viesse de uma pessoa nova no time: útil, mas ainda não confiável por padrão. Um checklist por worktree:
- Leia o diff completo contra a branch principal, por exemplo com git diff main...fix/calculo-fatura. Procure arquivos alterados que não estavam no escopo.
- Confirme que a mudança resolve o que foi pedido, não apenas que o teste passa.
- Rode a suíte de testes dentro do próprio worktree e verifique se os testes novos fazem sentido. O texto sobre testes automatizados gerados por IA explica como evitar testes que só confirmam o próprio código.
- Procure alterações indesejadas: arquivos de configuração, dependências adicionadas, segredos, remoções amplas.
- Verifique efeitos fora do repositório: migrações, chamadas externas, mensagens enviadas.
- Peça a um humano da equipe para aprovar mudanças que tocam dinheiro, dados pessoais ou comunicação com clientes.
- Só então mescle, de preferência por pull request, para ficar registrado quem aprovou.
Sobre a ordem: mescle uma branch por vez. Depois de cada mescla, atualize as outras branches com a principal e rode os testes de novo. Se houver conflito, resolva com a pessoa responsável pela decisão de negócio, não deixe a IA escolher sozinha qual versão vale.
Como fica na prática? (cenário ilustrativo)
Imagine uma equipe pequena que mantém o sistema interno de uma loja virtual. Na segunda-feira existem três pedidos: corrigir um erro no cálculo de uma fatura, ajustar o texto de um aviso enviado ao cliente e atualizar a documentação de instalação.
A pessoa responsável cria três worktrees, cada um com uma branch. Na tarefa da fatura, o escopo diz quais arquivos podem mudar e exige um teste que reproduza o erro. Na tarefa do aviso, o escopo proíbe disparar mensagens reais e pede apenas a alteração do texto do modelo. A documentação não depende de nada.
Quando as três sessões terminam, a revisão começa pela fatura, porque envolve dinheiro. O diff revela que a sessão também mexeu em um arquivo de configuração fora do escopo. A pessoa pede a reversão dessa parte, roda os testes e mescla. A documentação entra em seguida. O aviso fica para o dia seguinte, aguardando aprovação de quem responde pelo atendimento, já que o texto chega ao cliente. Nenhuma tarefa travou a outra, e nada foi mesclado sem olhar humano.
Para mensagens ativas em canais como o WhatsApp, vale ainda conferir as regras de modelos e consentimento em mensagens ativas no WhatsApp: templates e opt-in.
Como esse método se encaixa na forma como trabalhamos?
O mesmo raciocínio que usamos para levar IA a processos de negócio vale para desenvolvimento paralelo. Mapear: listar as tarefas e descobrir quais tocam as mesmas áreas. Limitar: definir arquivos permitidos, credenciais de teste e ações proibidas em cada sessão. Pilotar: começar com duas tarefas reais, registrar o que deu certo e o que exigiu retrabalho, e combinar um critério simples de sucesso, como mudanças revisadas sem surpresas. Transferir: documentar o procedimento para que a equipe repita sem depender de quem montou, e decidir se amplia, ajusta ou para.
Vale separar o que é documentação oficial (os comandos do Git, o funcionamento dos worktrees), o que é experiência de implementação (a ordem de mescla, a revisão por risco) e o que é hipótese (quantas sessões em paralelo a sua equipe consegue revisar bem). Esta última só se descobre testando no seu contexto.
Perguntas frequentes
Preciso de um comando especial do Claude Code para usar worktrees? Não necessariamente. Os worktrees são um recurso do Git, e basta iniciar o Claude Code dentro da pasta de cada um. Algumas versões da ferramenta podem trazer atalhos, então consulte a documentação oficial da sua versão.
Posso ter duas sessões na mesma branch em worktrees diferentes? Por padrão, o Git não permite que a mesma branch fique ativa em dois worktrees ao mesmo tempo, justamente para evitar edições concorrentes. O caminho recomendado é uma branch por tarefa, mesclada depois de revisada.
O worktree elimina todos os conflitos de mescla? Não. Ele evita conflito durante a edição, mas duas branches que alteram o mesmo trecho continuam em conflito quando você mescla. Por isso a recomendação é escolher tarefas independentes, mesclar uma por vez e rodar os testes após cada mescla.
Como limpo os worktrees depois de terminar? Depois de mesclar, use git worktree remove com o caminho da pasta e apague a branch já incorporada. Se alguma pasta foi apagada manualmente, o comando git worktree prune limpa os registros que ficaram órfãos.