Como dois devs podem usar Claude Code no mesmo repositório sem pisar no trabalho um do outro?

Fala aí, beleza? Cena que todo time já viveu: você está no meio de um refactor, o outro dev roda o Claude Code pra "dar uma ajeitada rapidinha" no service de pagamento, e do nada os SEUS arquivos mudaram embaixo de você

Aí vem o clássico "mas eu não mexi nisso", o git status virando um campo minado e meia hora perdida pra descobrir quem escreveu o quê

O ponto é que o problema aqui não é o modelo

O problema é falta de isolamento (as duas sessões mordendo o mesmo checkout) e falta de combinado de time (cada agente seguindo uma regra diferente)

Esse post resolve isso em três frentes: isolar as sessões em worktrees, compartilhar as regras que valem pros dois e revisar direito o código que o outro gerou com IA

Bora? 😀

O que você precisa antes de começar:

Lista curta, só o que é realmente pré-requisito:

• Um repositório git com pelo menos um commit: o worktree nasce a partir de um commit existente, então repo recém-criado e vazio não serve
• Claude Code instalado e rodando na raiz do projeto: é de lá que os caminhos padrão fazem sentido
• Acesso de escrita ao repositório: você vai criar branch e abrir PR

Duas coisas que NÃO são obrigatórias pra parte de isolamento:

A integração com GitHub (/install-github-app) só entra em cena na frente de revisão em pull request

E o Code Review automático em PR está disponível para assinaturas Team e Enterprise, então se o seu plano for outro, a parte de revisão local (/code-review na sua máquina) continua valendo normalmente

Passo a passo: isolar cada dev em um git worktree

Antes do como, o porquê: o Claude Code tem suporte nativo a git worktrees justamente pra rodar sessões paralelas sem uma pisar na outra

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Cada worktree é um checkout separado, com branch e arquivos próprios

Se você conhece aquele esquema de clonar o projeto duas vezes em pastas diferentes pra testar duas coisas ao mesmo tempo, é a mesma ideia, só que oficial e integrada ao git

A diferença prática: mudanças feitas em uma sessão nunca tocam os arquivos da outra

1. Suba a sessão já isolada. O comando cria o worktree e abre o Claude dentro dele:

claude --worktree pagamentos
# atalho
claude -w pagamentos

O valor que você passa não é só um rótulo bonitinho: ele vira o nome do diretório do worktree e é a base do nome da branch também (com um prefixo, que eu mostro no passo seguinte)

O erro comum deste passo: escolher nome genérico tipo teste e depois não saber qual sessão é qual quando as duas estiverem rodando

2. Saiba onde a coisa nasceu. O worktree é criado em .claude/worktrees/<nome>/ na raiz do repositório, numa nova branch chamada worktree-<nome>

No exemplo acima: pasta .claude/worktrees/pagamentos/ e branch worktree-pagamentos

O erro comum deste passo: procurar a branch com o nome que você digitou e achar que não criou nada. O prefixo worktree- está lá, é só listar as branches

3. Deixe o Claude nomear quando você não quiser pensar. Omitindo o nome, ele gera um automaticamente, no estilo bright-running-fox:

claude --worktree

Bom pra tarefa rápida, ruim pra tarefa longa

O erro comum deste passo: usar nome gerado em tudo e depois abrir a pasta de worktrees sem fazer ideia de qual bicho é qual tarefa

4. Ignore o diretório dos worktrees no git. Essa é a recomendação oficial e evita que o conteúdo dos worktrees apareça como arquivo não rastreado no checkout principal:

echo ".claude/worktrees/" >> .gitignore

O erro comum deste passo: só lembrar disso depois que o git status virou uma parede de arquivos novos e alguém commitou a pasta inteira sem querer 😛

5. Leve os arquivos ignorados pelo git pro worktree novo. Seu .env não vai junto sozinho, porque o git ignora ele

Pra isso existe um arquivo de configuração próprio, o .worktreeinclude, no diretório raiz do projeto:

.env
.env.local

O erro comum deste passo: tentar configurar isso dentro de settings. Não é lá, é um arquivo .worktreeinclude na raiz do projeto mesmo

6. Volte pro mesmo worktree depois. Retomar uma sessão que estava em um worktree devolve você pra aquele worktree

Vale pro resume interativo, pro --continue e --resume em modo não interativo com -p, e também pro Agent SDK

O erro comum deste passo: abrir o Claude na raiz do projeto no dia seguinte achando que está continuando a tarefa de ontem, e começar a editar o checkout principal

Com isso, você e o outro dev podem tocar tarefas paralelas sem sincronizar nada no braço. É a mesma lógica de quando você quer rodar dois sistemas ao mesmo tempo sem um atrapalhar o outro, só que aplicada a duas pessoas em vez de dois projetos

Passo a passo: combinar as regras que valem para os dois devs

Isolar resolve o conflito de arquivo

Mas não resolve o outro problema: a sessão dele gera código com um padrão, a sua gera com outro, e o PR vira discussão de estilo

O combinado precisa morar no repositório, não no Slack

1. Coloque as regras do time no arquivo de memória do projeto. No nível de projeto, o Claude Code lê CLAUDE.md ou .claude/CLAUDE.md no diretório de trabalho

Esses arquivos são lidos no início de cada sessão, então valem igual pra você e pro seu colega

O erro comum deste passo: escrever o combinado num doc externo que ninguém abre. Se não está no repo, não existe pro agente

2. Separe o que é seu do que é do time. Instruções globais, que valem pra você em todos os projetos, vão em ~/.claude/CLAUDE.md, no nível de usuário

O erro comum deste passo: empurrar preferência pessoal pro arquivo do projeto e obrigar o outro dev a conviver com a sua mania

3. Mantenha o arquivo curto. Acima de 200 linhas ele consome mais contexto e pode reduzir a aderência, ou seja, o agente segue MENOS as suas regras

E arquivo acima de 4 MiB o Claude Code simplesmente ignora

O erro comum deste passo: transformar o CLAUDE.md num manual de onboarding de 800 linhas e depois reclamar que o agente não obedece

4. Conte com ele depois da compactação. O CLAUDE.md da raiz do projeto sobrevive ao /compact: o Claude relê o arquivo do disco e reinjeta na sessão

Detalhe importante em sessão longa de dupla, porque o combinado não some no meio do caminho

5. Decida o que o time commita. O .claude/settings.json é a configuração de projeto, feita pra ser commitada e compartilhada com o time

Já o .claude/settings.local.json guarda preferência pessoal por projeto e não deve entrar no controle de versão

A precedência, da maior pra menor, é: local (.claude/settings.local.json), projeto (.claude/settings.json), usuário (~/.claude/settings.json)

O erro comum deste passo: commitar o settings.local.json e sobrescrever a preferência de todo mundo, já que ele ganha de tudo

6. Reaproveite regras entre projetos com symlink. O diretório .claude/rules/ suporta symlinks, então dá pra manter um conjunto de regras compartilhado e apontar vários projetos pra ele

Ótimo pra time que toca três, quatro repos com o mesmo padrão

7. Zere a conversa sem perder o combinado. Quando o papo ficar longo demais, /clear reinicia a conversa com contexto vazio e mantém a memória de projeto

O erro comum deste passo: fechar tudo e abrir de novo achando que precisa reexplicar o padrão do time. Não precisa

Se a sua dor for mais ampla que a dupla e envolver o time inteiro, vale ver como padronizar o agente entre vários devs do mesmo projeto

Passo a passo: revisar o código que o outro dev gerou com IA

Aqui mora a parte que quase ninguém faz direito

Revisar código gerado por IA de OUTRA pessoa é diferente de revisar o seu: você não viu o prompt, não viu o caminho, só o resultado

O Claude Code tem um comando embutido pra isso

1. Rode a revisão no diff atual. O /code-review revisa o diff procurando bugs de correção e limpezas:

/code-review

O erro comum deste passo: rodar sem ter nada no diff e esperar uma auditoria do projeto inteiro. Ele olha o diff atual

2. Escolha o nível de esforço. Os níveis são low, medium, high, xhigh e max

Em low e medium ele reporta só os achados de maior confiança

De high pra cima ele amplia a cobertura e pode incluir achados menos certos

/code-review high

O erro comum deste passo: não digitar nível nenhum e estranhar o resultado. Sem nível digitado, ele reutiliza o último nível usado

3. Aplique os achados quando fizer sentido. A flag --fix aplica o que a revisão encontrou:

/code-review high --fix

O erro comum deste passo: usar --fix com nível alto e aceitar tudo de olho fechado, inclusive os achados menos certos que o próprio nível alto assume trazer

4. Revise um pull request específico. Passando um número de PR, ele revisa aquele PR:

/code-review high 1234

É o comando pra quando o outro dev já abriu o PR e você quer uma primeira passada antes de ler linha por linha

5. Publique os achados no PR. A flag --comment publica os achados no pull request do GitHub como comentários inline:

/code-review high 1234 --comment

O erro comum deste passo: colar o resultado no chat do time e perder o contexto de qual linha era. Inline no PR resolve isso

6. Instale a integração com GitHub. Do próprio Claude Code:

/install-github-app

Ele instala o GitHub App e prepara o pull request do workflow

Rodar de novo depois permite concluir as etapas de workflow e secret

Tem também a alternativa de instalar o app e copiar o arquivo de workflow manualmente

O erro comum deste passo: rodar uma vez, ver que abriu um PR e achar que acabou

7. Confira as permissões que o app pede. São três, todas em leitura e escrita: Contents (pra modificar arquivos), Issues (pra responder issues) e Pull requests (pra criar PRs e enviar mudanças)

Tome cuidado ao aprovar isso em repositório de cliente sem avisar ninguém, beleza?

8. Saiba onde a credencial fica. O Claude Code salva a credencial como repository secret, com nome ANTHROPIC_API_KEY para chave de API ou CLAUDE_CODE_OAUTH_TOKEN para token de assinatura

O erro comum deste passo: criar o secret na mão com outro nome e ficar caçando por que nada dispara

9. Merge o PR de configuração. A menção @claude passa a funcionar no repositório depois que você cria e merge o pull request de configuração do workflow

O erro comum deste passo: mencionar @claude numa issue antes do merge e concluir que a integração está quebrada

Como funciona o Code Review automático em PR:

Vale entender o que roda por baixo, porque muda a sua expectativa sobre o resultado

Vários agentes analisam o diff e o código ao redor em paralelo na infraestrutura da Anthropic, cada um procurando uma classe diferente de problema

Depois, uma etapa de verificação confere os candidatos contra o comportamento real do código pra filtrar falso positivo

Os resultados são deduplicados, ordenados por severidade e publicados como comentários inline nas linhas onde o problema foi achado, com um resumo no corpo da revisão

Um detalhe que pega muita gente: pull request vindo de fork não é revisado automaticamente, independentemente da configuração de Review Behavior do repositório

Nesse caso, pra iniciar a revisão, é preciso comentar @claude review no pull request

Três cenários de dupla e como dividir o trabalho em cada um

Teoria é bonita, mas a dupla precisa saber o que fazer na segunda de manhã

Aqui vão os três arranjos mais comuns

Dois devs em features diferentes:

O caso mais fácil e o que o worktree resolve quase sozinho

Cada um sobe a própria sessão com claude -w <nome>, trabalha na branch worktree-<nome> e abre PR separado

Zero negociação de arquivo, porque os checkouts são diferentes

Dois devs na mesma feature:

Aqui não tem mágica: precisa de combinado humano

O jeito que funciona é dividir por camada (um no backend, outro no front) ou por arquivo, e registrar essa divisão no CLAUDE.md do projeto

Assim as duas sessões leem o mesmo combinado no início, e o agente do seu colega sabe que aquela pasta não é dele

Isso não é regra oficial de ferramenta, é prática de time mesmo

Um dev gerando enquanto o outro revisa:

Meu arranjo favorito pra tarefa grande

Quem gera fica isolado no worktree e não encosta no checkout principal

Quem revisa roda /code-review no PR e devolve os achados inline, sem nunca ter aberto o editor na mesma pasta

E pra enxergar quem está rodando o quê, existe um comando que lista as sessões vivas em JSON:

claude agents --json

Serve pra script, tipo barra de status ou seletor de sessão

Dá pra montar um indicadorzinho simples mostrando as sessões abertas da dupla. Mto massa pra quem gosta de tunar o terminal 😀

Problemas comuns quando duas sessões dividem o mesmo repositório

O worktree não é criado e aparece erro de base branch:

Sintoma: o comando falha com Failed to resolve base branch "HEAD": git rev-parse failed

Causa: o repositório não tem nenhum commit. O worktree é criado a partir de um commit existente

Solução: faça o primeiro commit no repositório e rode o comando de novo

Como prevenir: commit inicial antes de qualquer coisa em projeto novo, mesmo que seja só o README

Edit, Write ou comando de terminal recusado:

Sintoma: a sessão se recusa a editar um arquivo ou a rodar um comando que sempre funcionou

Causa: você está isolado em um worktree, e o Claude Code bloqueia chamadas de ferramenta que apontem pro checkout principal

Ele bloqueia Edit, Write ou NotebookEdit em caminho do checkout principal

Bloqueia comando Bash, PowerShell ou Monitor cujo diretório de trabalho caia no checkout principal OU não possa ser verificado

E bloqueia comando que redirecione o git pro checkout principal

As mesmas regras valem pra subagentes e pra sessões em background

Solução: trabalhe nos caminhos do próprio worktree, e se a intenção era mesmo mexer no principal, saia da sessão isolada

Como prevenir: nada de caminho absoluto apontando pra raiz antiga no meio dos seus scripts

Um monte de arquivo não rastreado no checkout principal:

Sintoma: git status cuspindo dezenas de arquivos estranhos

Causa: falta .claude/worktrees/ no .gitignore

Solução: adicione a linha e o barulho some

Como prevenir: isso entra junto com o setup do projeto, na mesma hora em que você configura o CLAUDE.md

App quebrado dentro do worktree:

Sintoma: o projeto roda no checkout principal, mas no worktree estoura falta de variável de ambiente

Causa: o .env é ignorado pelo git, então não foi pro worktree novo

Solução: liste esses arquivos no .worktreeinclude, no diretório raiz do projeto

Como prevenir: crie o .worktreeinclude junto com o primeiro worktree, não depois do primeiro erro

Histórico poluído com atribuição automática:

Sintoma: todo commit da dupla aparece com um co-autor que ninguém colocou

Causa: por padrão o commit inclui o trailer Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Solução: a configuração attribution controla o texto de commit e de PR, e tem precedência sobre a antiga includeCoAuthoredBy (depreciada)

Pra esconder tudo, basta deixar commit e pr como strings vazias

Como prevenir: decidam isso em dupla e deixem registrado no .claude/settings.json, que é o arquivo feito pra ser commitado e compartilhado

Conclusão

Dois devs usando Claude Code no mesmo repositório não é problema de ferramenta, é problema de arranjo

E o arranjo tem três frentes: isolar (worktree por tarefa), combinar (regras versionadas que as duas sessões leem) e revisar (/code-review antes do PR)

Se você quiser fazer só uma coisa hoje, faça três coisas pequenas, que dão uns dez minutos no total:

1. Adicione .claude/worktrees/ ao .gitignore
2. Suba um CLAUDE.md curto com o combinado do time (curto mesmo, lembre do limite de 200 linhas)
3. Abra a próxima tarefa com claude --worktree <nome> em vez de abrir na raiz

Depois disso, o hábito que muda o jogo é rodar /code-review antes de TODO pull request, e não só quando o código parece suspeito

Quando a revisão vira rotina, a dupla para de brigar com o repositório e volta a brigar com o problema real, que é o que interessa

até o próximo post! 😀