Resolver conflitos Git com Claude Code com segurança

Resolver um conflito Git não é apenas apagar <<<<<<<, ======= e >>>>>>>. Esses marcadores só mostram onde o Git parou. O trabalho real é preservar a intenção das duas branches: uma pode ter corrigido uma regra de autorização, enquanto a outra adicionou uma tela, uma chamada de API e novos testes.

Claude Code ajuda porque consegue ler os arquivos em conflito, verificar código ao redor, executar comandos Git, ajustar testes e explicar o diff final. Mesmo assim, não é seguro entregar o julgamento inteiro para a IA. Um pedido vago como “corrija todos os conflitos” pode gerar código que compila, mas remove uma regra de negócio ou duplica uma validação.

O fluxo mais estável é: uma pessoa define prioridade e limite, Claude Code faz a edição mecânica, e a pessoa revisa diff, testes e comportamento. É esse padrão que uso nos projetos ClaudeCodeLab.

Visão geral

mudanças de main ou release
        |
        v
Git informa arquivos não mesclados
        |
        v
Claude Code resolve com uma política escrita
        |
        v
revisão humana de diff, testes e comportamento
        |
        v
commit do estado resolvido

Para execução não interativa, a documentação oficial Claude Code CLI reference mostra o padrão claude -p "query". Para automatizar verificações, use Claude Code hooks reference e Claude Code settings. No Git, Git rerere documenta a reutilização de resoluções registradas.

Verifique o estado primeiro

Antes de chamar Claude Code, confirme que não existem alterações locais sem relação com o conflito.

git status --short
git branch --show-current
git diff --name-only --diff-filter=U

O último comando lista apenas arquivos ainda não resolvidos. Leia essa lista você mesmo. Se aparecer um arquivo inesperado, entenda o motivo antes de pedir que Claude Code edite.

Inclua quatro informações no prompt:

Pergunta	Exemplo de política
Qual lado tem prioridade	Manter correções de segurança de main e a nova UI da feature
O que pode ser editado	Somente arquivos não resolvidos e testes diretamente relacionados
Como tratar gerados	Regenerar lockfiles e código gerado, não mesclar manualmente
Critério de conclusão	Sem marcadores, git diff --check limpo, testes passando e resumo

Essa política curta evita que Claude Code adivinhe e facilita a revisão.

Caso 1: mesclar main em uma feature branch

O cenário mais comum é uma feature branch que ficou alguns dias atrás de main e precisa ser atualizada antes do pull request.

git fetch origin
git merge origin/main

cat > /tmp/claude-conflict-plan.md <<'PROMPT'
Resolva os conflitos atuais de Git merge.

Contexto:
- A branch atual é uma feature branch.
- Mantenha correções de segurança e mudanças de tipos de origin/main.
- Mantenha a nova tela, a chamada de API e os testes da feature.
- Trabalhe apenas em arquivos de git diff --name-only --diff-filter=U.

Tarefas:
1. Explique brevemente por que cada arquivo conflitou.
2. Remova conflict markers e integre as duas intenções.
3. Atualize somente testes diretamente relacionados, se necessário.
4. Execute git diff --check.
5. Resuma decisões e comandos executados.

Não faça:
- Refatorações sem relação.
- Descartar um lado sem explicar.
- Editar package-lock.json manualmente.
PROMPT

claude -p "$(cat /tmp/claude-conflict-plan.md)"
git diff --check
npm test

O ponto central é declarar prioridade, escopo, política de arquivos gerados e condição de término. Assim o resultado fica auditável.

Um erro real: main adicionou uma autorização mais rígida e a branch feature adicionou um novo fluxo de UI. Um prompt genérico dizendo “mantenha ambos” deixou a UI visível, mas a API continuou retornando 403. Depois disso, passei a declarar que segurança e autorização precisam sobreviver e que a consistência UI/API deve ser verificada.

Caso 2: resolver rebase passo a passo

Conflitos em git rebase exigem mais cuidado que um merge comum, porque o Git pausa a cada commit. Além disso, ours e theirs podem parecer invertidos durante rebase. Não use git checkout --ours sem entender o diff.

git rebase origin/main

cat > /tmp/claude-rebase-step.md <<'PROMPT'
Resolva somente o conflito atual deste rebase.

Primeiro:
- Confirme com git status que estamos em rebase.
- Liste arquivos não resolvidos com git diff --name-only --diff-filter=U.
- Infira a intenção do commit atual pelo git log recente.
- Integre essa intenção ao comportamento atual de main.

Restrições:
- Não execute git rebase --continue.
- Pare depois de resolver e fazer git add.
- Não edite arquivos sem relação.
- Se a escolha for ambígua, explique opções em vez de adivinhar.
PROMPT

claude -p "$(cat /tmp/claude-rebase-step.md)"
git diff --check
npm test
git rebase --continue

É possível automatizar mais, mas revisar cada etapa é mais seguro. Se uma resolução ruim passa por vários commits, fica difícil descobrir onde o significado mudou.

Caso 3: lockfiles e código gerado

package-lock.json, pnpm-lock.yaml, código gerado por OpenAPI ou Prisma e snapshots grandes não devem ser mesclados linha por linha. Resolva a fonte primeiro e regenere a saída.

cat > /tmp/claude-lockfile-policy.md <<'PROMPT'
Resolva conflitos de lockfile ou arquivos gerados.

Política:
- Resolva primeiro arquivos mantidos por humanos, como package.json, schema ou OpenAPI.
- Não mescle package-lock.json manualmente.
- Quando as dependências estiverem decididas, regenere com npm install.
- Para código gerado, resolva a fonte e depois regenere.
- Explique por que o diff regenerado é esperado.

Pode executar:
- npm install
- npm test
- npm run lint
PROMPT

claude -p "$(cat /tmp/claude-lockfile-policy.md)"
npm install
npm test
git add package.json package-lock.json

A armadilha comum é manter as duas dependências em package.json, mas aceitar só um lado do lockfile. Pode funcionar localmente e falhar no CI. A regra deve ficar escrita: fonte primeiro, saída gerada depois.

Caso 4: analisar a causa

Resolver o conflito também é uma chance de reduzir a próxima ocorrência. Se rotas, permissões, schemas ou dependências entram sempre em conflito, talvez o PR esteja grande demais ou a ownership esteja difusa.

cat > /tmp/claude-conflict-retro.md <<'PROMPT'
Analise por que este Git conflict aconteceu.

Investigue:
- Liste arquivos com git diff --name-only --diff-filter=U.
- Use git log --oneline --all -- <file> para ver histórico das duas branches.
- Classifique a causa: ownership compartilhada, PR grande, ruído gerado ou regra ausente.

Saída:
- Resumo da causa em três linhas.
- Regras para adicionar ao CLAUDE.md.
- Se ajuda mais dividir PR, coordenar responsáveis ou adicionar testes.
PROMPT

claude -p "$(cat /tmp/claude-conflict-retro.md)"

Se src/routes.ts conflita toda semana, talvez seja hora de dividir registros de rota por feature. Se package.json conflita sempre, mudanças de dependência podem virar PRs separados.

Verificações e regras de equipe

Depois da edição, execute pelo menos:

git diff --check
git diff --name-only --diff-filter=U
npm test

Adicione typecheck, lint ou E2E quando o conflito tocar contratos, rotas, cobrança ou autorização. Para automatizar checks, veja o guia de Hooks do Claude Code.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git merge*)|Bash(git rebase*)",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --check && npm test"
          }
        ]
      }
    ]
  }
}

Também documente a política em CLAUDE.md, que funciona como memória de projeto para Claude Code. Veja CLAUDE.md best practices e o guia de colaboração em equipe.

## Git conflict policy
- Preservar por padrão segurança, autorização e prevenção de perda de dados.
- Verificar UI, API, schema e testes em conjunto.
- Regenerar lockfiles e código gerado em vez de editar manualmente.
- Durante rebase, uma pessoa revisa o diff antes de git rebase --continue.
- Se a decisão não for clara, apresentar opções em vez de descartar um lado.

Armadilhas e resultado testado

Não memorize ours e theirs como rótulos fixos; durante rebase eles podem surpreender. “Manter os dois” também nem sempre é correto: duas validações ou dois redirects podem duplicar comportamento. E testes verdes não substituem revisão humana quando o conflito envolve autenticação, pagamentos, migrações ou exclusão de dados.

Em um projeto TypeScript com cerca de 15 arquivos em conflito, um prompt vago corrigiu a sintaxe, mas esqueceu um teste relacionado. Com a política deste artigo, Claude Code gerou um diff menor, explicou decisões e reduziu o tempo de revisão.

Comece por uma feature branch pequena: liste arquivos não resolvidos, entregue uma política clara, rode testes e revise o diff. Quando o fluxo estiver estável, mova as regras repetidas para hooks e CLAUDE.md.