Vale a pena pedir ao Claude Code para resolver conflito de merge?

Fala aí, beleza? Poucas coisas são mais tentadoras que abrir o arquivo, ver aquele monte de <<<<<<< HEAD na tela e pensar "deixa o agente resolver isso e eu vou tomar um café"

E a tentação faz sentido: o Claude Code é uma ferramenta agêntica de terminal que lida com fluxo de git por linguagem natural, executando tarefa de rotina e explicando código complexo

Ele faz stage, escreve mensagem de commit, cria branch, abre PR

Então parece a ferramenta óbvia pro conflito de merge também

Só que tem uma pegadinha aqui: o resultado depende MUITO do tipo de conflito que tu tem na frente. Tem conflito que é trabalho braçal puro, e aí o agente voa. E tem conflito em que a informação que decide a parada nem está no arquivo…

O que o Git realmente marca como conflito:

Antes de decidir se joga pro agente ou não, vale entender o porquê do Git travar

O Git só bloqueia o merge quando ele não consegue escolher sozinho com segurança. Tipicamente em dois casos: quando os dois lados mudam a mesma linha do mesmo arquivo, ou quando um lado edita um arquivo e o outro lado apaga esse mesmo arquivo

Repara que o critério é textual, não semântico. O Git não sabe o que a tua regra de negócio significa, ele sabe que duas pessoas mexeram no mesmo pedaço de texto

Formação Recomendada

Formação Claude Code

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

• 118 aulas
• 4 projetos
• 9h 33min

Conhecer formação

E o que são aqueles símbolos? São os marcadores de conflito. Resolver na linha de comando significa apagar os marcadores <<<<<<<, ======= e >>>>>>> e escrever a versão final que tu quer no merge

Ou seja: o Git te entrega um texto sujo e transfere a decisão pra ti

Guarda isso, porque é exatamente daqui que sai o acerto e o erro do agente 🙂

Conflito mecânico x conflito de intenção: quando o Claude Code ajuda e quando atrapalha

Eu gosto de separar conflito em duas famílias, e essa separação resolve quase toda a dúvida de "peço ou não peço pro agente?"

A linha do meio é a mais importante da tabela

No conflito de intenção, o dado que decide (o motivo de cada lado ter mudado aquilo) simplesmente NÃO está no texto que o agente lê. Ele vai preencher a lacuna com o que parece razoável

E "parece razoável" é diferente de "é o que o time combinou"

Onde o agente resolve bem (e onde eu não deixaria)

Bora pros cenários concretos, com o critério de decisão de cada um:

• Import reordenado nos dois lados: caso clássico de conflito mecânico. Os dois querem o import lá, só que em posições diferentes. Critério: se o resultado final contém tudo que os dois lados precisavam, tá resolvido
• Formatação, indentação, quebra de linha: mesma coisa. Não tem decisão de negócio escondida, tem estilo. O linter é o juiz aqui
• Blocos independentes que cada lado adicionou: um lado acrescentou uma função, o outro acrescentou outra, e o Git marcou porque ficaram grudadas. Manter os dois costuma ser a resposta. Critério: os dois blocos fazem coisas diferentes e não se sobrescrevem
• Renomeação em massa de um lado e uso do nome antigo do outro: aqui o agente ajuda bastante, porque é repetição pura. Critério: a renomeação é uma decisão já tomada, não uma disputa
• Regra de negócio alterada dos dois lados: essa eu não deixaria no automático. Uma pessoa mudou o desconto por um motivo, a outra mudou por outro. Não existe "merge" dessas duas cabeças, existe escolha
• Arquivo editado de um lado e apagado do outro: conflito de intenção disfarçado de conflito de arquivo. Alguém decidiu que aquilo morreu, alguém decidiu que aquilo evoluiu. Isso é conversa humana, não prompt
• Migração de schema: o pior cenário pra delegar sem ler. Ordem de migração e estado do banco são coisas que o agente não enxerga a partir do arquivo em conflito

O padrão é fácil de decorar: se a resposta certa está contida no texto, o agente é um acelerador massa. Se a resposta certa depende de contexto que só existe fora do arquivo, ele vira um chute confiante

Os erros conhecidos do Claude Code em conflito de merge

Aqui não é achismo, é registro público no repositório oficial

Sintoma 1: o arquivo fica com chaves desbalanceadas

A issue #28312 do anthropics/claude-code descreve um caso bem específico e bem sacana

Quando os dois branches adicionam blocos antes de uma chave de fechamento compartilhada, o algoritmo do Git tira essa chave de dentro dos marcadores de conflito

O Claude então mantém os dois blocos (o que faz sentido!) mas trata a chave de fora como contexto intocável

Resultado: falta chave de fechamento, o arquivo quebra. O relato descreve o problema como agnóstico de linguagem, citando C#, Java, TypeScript, C++, Go e Rust

Causa: a ambiguidade do formato padrão de conflito. Com só dois lados visíveis, não dá pra saber o que era o original

Prevenção: o próprio relato aponta a mitigação de custo zero disponível hoje, que é trocar o estilo de conflito

git config merge.conflictstyle zdiff3

Com isso o ancestral comum passa a aparecer entre os marcadores, e a ambiguidade some

Sintoma 2: a tela volta duplicada e com funcionalidade sumida

A issue #8287, aberta em 28/09/2025 no mesmo repositório, relata um dashboard quebrado depois de uma tentativa de merge entre dois branches: elementos de UI duplicados e funcionalidades perdidas

A issue foi fechada como not planned, então não trate como bug com correção prometida, trate como aviso

E repara que o estrago é de interface, que é justamente onde a duplicação passa despercebida no diff e só aparece quando alguém abre a página. Se tu já pediu design de tela no Claude Code, sabe que componente duplicado é fácil de nascer e difícil de notar

Prevenção: checagem de build e lint depois da resolução, sempre. E se o resultado não fechar, tem saída:

git merge --abort

O git merge --abort tenta reverter pro estado anterior ao merge. Ter esse botão de pânico na manga muda o teu nível de coragem 😀

Como descrever a intenção dos dois lados no prompt

Agora o fluxo em si. A ideia é simples: dar ao agente o contexto que o arquivo não tem, e só depois deixar ele escrever

1. Configure o estilo de conflito antes de qualquer coisa

   git config merge.conflictstyle zdiff3

O merge.conflictStyle aceita merge (que é o padrão), diff3 e zdiff3. O diff3 adiciona o marcador ||||||| com o texto original antes do =======, trazendo a versão base inline

O erro comum deste passo: deixar no padrão e esperar que o agente adivinhe o que era o original. Com a base na tela, ele para de tratar linha de fora como intocável

2. Levante a intenção dos dois lados com o próprio Git

   git log --merge
   git log --merge -p
   git diff

O git log --merge mostra só os commits de cada lado do merge que tocam arquivo atualmente em conflito. Com -p tu vê os diffs. E o git diff durante o merge mostra apenas o que ainda está em conflito

O erro comum deste passo: pular ele. É exatamente aqui que tu descobre que um lado mudou a regra por causa de um bug e o outro por causa de um pedido novo

3. Entre em plan mode antes de deixar ele editar

No modo normal, o Shift+Tab passa primeiro para auto accept edits, e o Shift+Tab seguinte entra em plan mode

Em plan mode as ferramentas somente leitura rodam normalmente e edições de arquivo nunca são auto aprovadas, mesmo que exista regra de allow que combine. Ou seja: ele lê, entende e te devolve um plano, sem mexer nos teus arquivos

O erro comum deste passo: parar no auto accept edits achando que já está no plan mode. Um Shift+Tab a menos e ele sai editando 😛

4. Escreva o prompt dizendo o que cada lado queria e qual comportamento deve valer

Nada de "resolva os conflitos". Esse é O erro clássico: tu transfere a decisão de negócio pra quem não tem como saber

O formato que funciona é mais ou menos assim: o lado A mudou X porque tal coisa, o lado B mudou X porque tal outra, o comportamento final deve ser Y, mantenha as duas funções novas e não altere a assinatura pública

O erro comum deste passo: descrever o resultado técnico e esquecer de dizer qual regra vence quando as duas não cabem juntas

5. Revise o diff e rode build e testes

Leia o diff inteiro, sem pular. É o mesmo cuidado de quando tu pede refatoração sem mudar comportamento: o código pode ficar bonito e a semântica sair diferente do combinado

O erro comum deste passo: aceitar porque compilou. Compilar não é o mesmo que estar certo

6. Se não fechar, aborta e resolve na mão

   git merge --abort

Voltar ao estado anterior custa segundos. Consertar merge ruim que já virou commit custa a tarde inteira

O erro comum deste passo: insistir em pedir "conserta isso agora" em cima de um arquivo já bagunçado, empilhando erro sobre erro

Alternativas e reforços: mergetool, Copilot, GitHub web, worktrees, rerere e hooks

Um panorama honesto do entorno, porque conflito de merge não se resolve só com prompt

• claude-mergetool: existe, funciona como mergetool do Git, mas é projeto de terceiro. O claude-mergetool é mantido pelo usuário 9999years no GitHub, exige o CLI claude instalado e no PATH, e roda via git mergetool -t claude (ou jj resolve --tool claude). Detalhe importante: o projeto lança o Claude com --permission-mode=acceptEdits, então ele edita sem te perguntar
• Fix with Copilot no GitHub: o GitHub tem resolução automática de conflito por IA no merge box, com o botão Fix with Copilot, que aparece quando o acesso ao Copilot cloud agent está habilitado no repositório. O Copilot analisa as mudanças conflitantes, resolve e verifica se build, testes e linter continuam passando. Só que isso é Copilot, não é Claude Code
• Editor web do GitHub: dá pra resolver na interface apenas conflitos simples envolvendo mudanças concorrentes de linha. Os outros tipos pedem linha de comando mesmo
• git worktrees: ótimo pra reduzir colisão antes dela existir. Cada worktree é um checkout separado no próprio branch, criado a partir de um commit existente, então o repositório precisa ter ao menos um commit. Trabalhos paralelos ficam isolados e tu evita edição em cima de edição
• git rerere: esse é subestimado demais. O git rerere grava o resultado do automerge conflitado junto com a tua resolução manual e reaplica depois, e o git merge invoca ele automaticamente quando o automerge falha. Basta habilitar a variável de config rerere.enabled. Se tu resolve o mesmo conflito toda semana, isso é ouro
• Hooks do Claude Code: hooks de PreToolUse podem negar comandos de Bash considerados perigosos, o que serve bem pra barrar comando de git que tu não quer que rode nunca. Só lembra que o PostToolUse dispara depois que o comando termina e não desfaz a ação, então prevenção só existe no Pre

Veredito: quando pedir, quando resolver na mão

Vale a pena? Vale, com escopo definido

Use o agente como acelerador de conflito mecânico: import, formatação, blocos independentes, renomeação repetitiva. É trabalho chato, repetitivo e verificável pelo build. Delegar isso é ganho puro

Use o agente também como leitor de contexto nos casos de intenção. Pedir pra ele ler o git log --merge -p e te explicar o que cada lado estava tentando fazer é MUITO útil, e não tem risco nenhum: ele não está decidindo, está resumindo

O que não delega: a escolha de qual regra vence. Essa continua humana, e vai continuar sendo por um bom tempo

E a regra que não tem exceção: ninguém aceita o merge sem ler o diff e rodar build e testes. Nem quando o agente jura que está tudo certo 😀

Conclusão

Conflito de merge é um daqueles casos em que o agente parece perfeito e nem sempre é

Ele enxerga o texto, e o texto é metade do problema. A outra metade (o porquê de cada lado) tu precisa colocar no prompt na mão

Próximo passo concreto, que dá pra fazer agora em dois comandos: habilita o zdiff3 e o rerere no teu repositório

git config merge.conflictstyle zdiff3
git config rerere.enabled true

Depois treina o fluxo em um conflito pequeno, em plan mode, antes de confiar em um merge grande. Erra barato primeiro, beleza?

E me conta aqui nos comentários qual tipo de conflito mais aparece no teu dia: mecânico ou daqueles em que duas pessoas mudaram a mesma regra por motivos diferentes?

até o próximo post!