Claude Code corrigiu o bug e quebrou meu código: como pedir a correção sem efeito colateral

O bug sumiu e o teste do lado quebrou

"O Claude Code quebrou meu código" é uma frase que quase todo vibe coder já falou depois de pedir uma correção pequena e receber de volta um diff com arquivos que ele nem citou no prompt

Só que isso não é azar, nem dia ruim do modelo

É comportamento previsível de mudança ampla: quanto maior a superfície que a correção toca, maior a chance de ela passar por cima de código que estava saudável

Então aqui a gente ataca dois pontos bem específicos: COMO pedir a correção com o raio delimitado, e como revisar o diff atrás daquilo que ninguém pediu

Bora ver na prática? 🙂

Por que uma correção pequena mexe em código que estava saudável

O sintoma:

Você pediu uma coisa pontual, tipo um cálculo errado numa função

O Claude volta dizendo que resolveu, e o diff traz mudança em arquivo que você não mencionou, função renomeada, import reorganizado e um "aproveitei e simplifiquei aqui"

O bug original até sumiu, mas alguma outra coisa foi junto

A causa:

Prompt sem escopo é convite pra reescrita

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Se você não diz onde mexer e o que não pode mudar, qualquer arquivo relacionado vira território livre

A documentação oficial é bem direta nisso: quanto mais precisas as instruções, menos correções são necessárias, e instruções específicas, concisas e bem estruturadas são seguidas com mais consistência

Ou seja, o prompt frouxo não gera só um resultado ruim, ele gera uma segunda rodada de conserto… que é justamente onde a regressão nasce

A solução:

Três coisas que a doc recomenda e que mudam o jogo no pedido de correção:

• referenciar arquivos específicos, em vez de descrever o bug no vácuo
• mencionar restrições, o que precisa continuar igual
• apontar padrões de exemplo, um trecho do próprio projeto que serve de modelo

Parece óbvio, mas quase ninguém faz na hora que o bug tá pegando fogo em produção

Prevenção:

O que se repete em todo prompt não deveria estar no prompt, e sim no CLAUDE.md, que é o arquivo de memória de projeto

Ele ainda aceita importar outros arquivos com a sintaxe @caminho/do/arquivo, então dá pra separar convenções por área do projeto em vez de empilhar tudo num arquivão

E a orientação oficial é tratar edição no CLAUDE.md como qualquer outra mudança de documentação, pra convenção andar junto com o código e não virar peça de museu

E se te consola: mudança ampla derrapa até na origem

A própria Anthropic publicou um postmortem sobre relatos de qualidade no Claude Code em que uma alteração de prompt de sistema, com limites de tamanho de resposta, teve efeito colateral desproporcional e foi revertida no release de 20 de abril

Se acontece com quem escreve o prompt de sistema, imagina no teu prompt de terça à noite haha

Como delimitar o raio da mudança no prompt da correção

O sintoma:

O Claude aproveita a visita e refatora o que estava funcionando

É o clássico "já que eu tô aqui": ele arruma o bug e de quebra reorganiza a função vizinha, troca a assinatura de um método, mexe no formato de retorno

A causa:

Não existe limite explícito de superfície no pedido

O modelo não sabe o que é intocável no teu projeto se você não disser qual é a parte intocável

A solução:

O prompt de correção precisa de três partes: onde mexer, o que NÃO pode mudar, e como conferir que deu certo

Prompt frouxo:

corrige o erro de cálculo do frete, tá vindo valor errado

Prompt com raio delimitado:

O cálculo de frete em src/services/frete.js está retornando valor errado
quando o CEP é da região Norte.

Corrija apenas dentro de src/services/frete.js.
Não altere a assinatura de calcularFrete nem o formato do objeto de retorno,
porque src/checkout/resumo.js depende dele.
Siga o padrão de arredondamento já usado em calcularDesconto, no mesmo arquivo.

Depois rode npm test -- frete e me mostre o resultado antes de considerar pronto.

A diferença não é tamanho, é superfície

O segundo prompt diz o arquivo, fixa o contrato que não pode mudar, mostra o padrão de exemplo e ainda entrega uma verificação executável

E essa última parte é tratada como prática crítica na documentação: sempre fornecer verificação, dar ao Claude uma checagem que ele consiga rodar (teste, build, um screenshot pra comparar)

Aqui mora o motivo de pedidos abstratos darem tanto problema, é o mesmo buraco de quando você tenta pedir mais performance sem ter métrica: sem alvo mensurável, sobra interpretação, e interpretação vira reescrita

Prevenção:

Modo de planejamento, mas com critério

Você entra nele pressionando Shift+Tab, ou prefixando um único prompt com /plan, e sai sem aprovar o plano dando Shift+Tab de novo

A doc oficial diz quando isso vale: quando há incerteza sobre a abordagem, quando a mudança altera múltiplos arquivos ou quando o código é desconhecido

E dá a régua pro caso contrário: se dá pra descrever o diff em uma frase, pule o plano e peça direto

Typo, linha de log, renomear variável, isso não precisa de plano, precisa de pedido claro

Como revisar o diff procurando alterações que ninguém pediu

O sintoma:

O commit passa, o time aprova, e a regressão aparece três dias depois numa parte do sistema que ninguém associou àquela correção

A causa:

A revisão foi feita por quem já sabe o raciocínio da mudança

Você acompanhou o Claude pensando, entendeu a lógica, então seu olho lê o diff confirmando a história que já tá na tua cabeça

O que ninguém pediu passa batido justamente porque parece coerente

A solução, em camadas:

1. Rode /diff pra abrir o visualizador interativo das alterações não commitadas

Ele mostra o que mudou e também permite ver o que cada turno do Claude alterou, o que ajuda a separar "isso veio do pedido do bug" de "isso apareceu no meio do caminho"

O erro comum deste passo: olhar só o arquivo que você citou no prompt e nem rolar até os outros, que é exatamente onde a mudança não pedida costuma estar

2. Rode /code-review pra revisar o diff atual dentro do terminal

/code-review

Ele revisa em busca de bugs de correção e de limpezas (reuso, simplificação, eficiência), e não depende do GitHub App

O alias é /review, se você já tem esse na memória muscular

3. Escolha o nível de esforço conforme o risco da mudança

/code-review high

O erro comum deste passo: mandar sempre no nível mais alto e depois ignorar a lista inteira porque veio ruído

Correção pequena pede low ou medium, correção que encostou em vários arquivos pede de high pra cima

4. Se a mudança já virou pull request, passe o número

/code-review high 1234

5. Decida o que fazer com os achados

A flag --comment publica os achados como comentários inline no PR

A flag --fix aplica os achados na working tree depois da revisão

O erro comum deste passo: sair de --fix direto pro commit, sem passar de novo pelo /diff

Correção automática também é mudança, e mudança também tem raio 😀

E a camada que quase ninguém usa:

A documentação oficial recomenda que, antes de considerar a tarefa pronta, você peça a um subagente pra revisar o diff em contexto novo e reportar lacunas

O pulo do gato é esse: o revisor em contexto novo vê só o diff e os critérios que você deu, não vê o raciocínio que produziu a mudança

Então ele avalia o resultado por si só, sem a narrativa que te convenceu

Já quebrou: como voltar sem perder o que estava certo

O sintoma:

A correção entrou, levou outra parte junto, e agora você tá naquele impasse de desfazer tudo e perder as duas horas de conversa que chegaram até ali

A causa:

Aceitar o resultado sem ponto de retorno claro

A solução:

O Claude Code cria checkpoints automáticos

Cada prompt enviado cria um checkpoint, e ele tira um snapshot dos arquivos antes de cada alteração

Pra abrir o menu de rewind você roda /rewind, ou pressiona Esc duas vezes com o campo de input vazio

E aí vem a parte boa: o menu separa o que é restaurado

• restaurar só a conversa
• restaurar só o código
• restaurar os dois
• resumir a partir da mensagem selecionada

Ou seja, dá pra devolver os arquivos ao estado anterior e continuar a conversa do ponto onde ela ainda fazia sentido

Tome cuidado com uma pegadinha: as duas opções de restaurar código só aparecem quando o checkpoint selecionado tem alterações de arquivo rastreadas pra reverter

Prevenção:

Aqui vai a limitação dura, e ela importa MUITO se você trata checkpoint como rede de segurança

Checkpoints só rastreiam alterações feitas pelas ferramentas de edição de arquivo do Claude

Mudança feita via comandos Bash ou por processos externos não é capturada

Então script que reescreve arquivo, gerador rodado no terminal, os rm -rf da vida: nada disso volta pelo rewind

Pra esse tipo de coisa, o que te salva continua sendo commit pequeno e branch separada, do jeito tradicional mesmo

Quando vale planejar antes e quando isso é só atraso

Caso 1: correção de uma linha

Typo, mensagem de log, renomear variável

Aqui o plano é overhead puro, você gasta dois turnos aprovando um plano pra uma mudança que cabe numa frase

A regra da doc resolve: se dá pra descrever o diff em uma frase, peça direto

Caso 2: bug em código desconhecido ou espalhado

Código que você nunca abriu, ou correção que provavelmente encosta em múltiplos arquivos

Esse é exatamente o cenário em que a doc diz que planejar é mais útil: incerteza sobre a abordagem, mudança em vários arquivos, código desconhecido

O plano aqui não é burocracia, é onde você vê o raio ANTES de ele existir no disco e corta o que não devia estar ali

É a mesma lógica de quando o pedido é atualizar uma dependência sem quebrar o projeto: o risco não está no comando, está no que ele arrasta junto

Caso 3: base de código grande

Em base grande, a doc sugere planejar primeiro no modo de planejamento e pedir que o Claude escreva o plano em um arquivo

O plano em arquivo serve de checklist depois:

• todo requisito foi implementado?
• os casos de borda listados têm teste?
• nada fora do escopo da tarefa mudou?

Esse terceiro item é o antídoto direto contra regressão, porque ele te obriga a comparar o diff com um escopo escrito, não com a tua lembrança do que você pediu

E a investigação do bug em si:

A orientação oficial é delimitar investigações de forma estreita, ou usar subagentes, pra exploração não consumir o contexto principal

Cada subagente roda na própria janela de contexto e devolve apenas o resumo

Na prática isso mantém o contexto principal limpo pra hora que interessa, que é escrever a correção pequena e certa

O hábito que separa correção de regressão

O ciclo é curto e cabe em quatro movimentos

Pedir estreito, com arquivo nomeado e restrição declarada

Verificar com algo executável, teste, build ou screenshot pra comparar

Revisar o diff em contexto limpo, de preferência com quem (ou o quê) não viu o raciocínio

E ter rota de volta, sabendo que o checkpoint cobre a edição de arquivo do Claude e não cobre o que passou pelo Bash

Próximo passo bem prático: na tua próxima correção, escreve o prompt com arquivo e restrição, e antes de commitar roda /diff e depois /code-review

Só isso já muda a conversa de "quebrou de novo" pra "achei antes de subir"

E fecha com a frase da doc que vale ser colada no monitor: se não dá pra verificar, não faça o deploy

até o próximo post! =)