Como revisar um diff do Claude Code quando você não entende metade do que ele mudou

Fala aí, beleza? Sabe aquele momento em que o painel abre, lista 14 arquivos alterados e você reconhece uns três?

O resto é código que o agente escreveu num canto do projeto que você nunca abriu na vida

O gargalo do vibe coding mudou de lugar: não é mais escrever código, é revisar código que você não escreveu

E aceitar no escuro é barato agora e caro depois, porque é exatamente assim que nasce o bug silencioso, aquele que passa no review, passa no deploy e só aparece quando alguém reclama

Este post não é aula do trecho específico que o Claude mexeu (não tenho como saber qual é o seu projeto haha)

É um método de leitura de diff: por onde começar, que perguntas devolver pro agente e o que exigir antes de aceitar

O que você precisa antes de começar

Checklist curto, tudo verificável em dois minutos:

• Claude Code v2.1.260 ou posterior, que é a versão mínima pro painel de diff. Ele abre sozinho quando o Claude começa a editar arquivos, desde que o terminal tenha pelo menos 144 colunas
• Projeto sob git, porque parte do escopo de comparação e praticamente toda a sua rota de fuga dependem disso
• Conta claude.ai autenticada se você pretende usar o /code-review ultra: quem está logado só com API key precisa rodar /login e autenticar com claude.ai antes

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 este método NÃO exige: você não precisa dominar o trecho alterado

Sério

A leitura de diff é uma habilidade separada de conhecer a codebase, e é justamente por isso que dá pra atacar com roteiro em vez de com familiaridade

Método de leitura: por onde começar um diff que você não domina

1. Abra o painel e leia a LISTA antes de ler qualquer linha de código

/diff

O painel lista os arquivos alterados com a contagem de linhas adicionadas e removidas, e mostra o diff de cada arquivo abaixo da lista

Essa lista é um mapa de tamanho: ela te diz onde o agente realmente trabalhou e onde ele só passou raspando

O erro comum deste passo: começar a ler pelo primeiro arquivo da lista, que quase nunca é o mais importante, e chegar cansado no arquivo que concentrava a mudança de verdade

2. Fixe o escopo com Ctrl+X B antes de julgar o tamanho da mudança

Dentro do painel, Ctrl+X B cicla o escopo de comparação entre três visões: as mudanças desta sessão, as alterações não commitadas em uma lista só, e tudo desde que o branch se separou do branch padrão

O Claude Code lembra a escolha por projeto, então você configura uma vez e segue a vida

O erro comum deste passo: revisar só a sessão atual quando o branch já acumulou mudanças de sessões anteriores. Você aprova um diff pequeno e o que vai pro PR é outra coisa bem maior

3. Leia por camada de risco, não em ordem alfabética

Primeiro o que muda contrato público (assinatura de função, retorno, rota, schema), depois config e dependência, e só então a implementação interna

O porquê disso: erro em implementação interna normalmente quebra alto e rápido, dá pra ver no teste. Erro em contrato ou em config quebra baixinho, longe, em outro arquivo que você nem abriu

O erro comum deste passo: gastar toda a atenção lendo lógica linha a linha e passar batido numa linha de config que mudou comportamento em todo o projeto

4. Selecione com o mouse as linhas que você não entendeu

Dá pra selecionar linhas específicas dentro do painel de diff pra perguntar sobre elas: o Claude Code anexa a seleção ao próximo prompt e mostra a contagem de linhas ao lado do input até você enviar

Ou seja, sua pergunta fica ancorada no código EXATO, e não numa lembrança aproximada do que você viu

O erro comum deste passo: descrever o trecho de memória ("aquela parte que valida o token") e receber uma explicação impecável… sobre outro pedaço do código

5. Mantenha o painel aberto enquanto o Claude responde

O painel é atualizado automaticamente a cada vez que o Claude edita um arquivo ou roda um comando de shell, então ele funciona como monitor ao vivo do que está acontecendo

Quando terminar, rodar /diff de novo fecha o painel (ou clique no ✕ do cabeçalho)

Se o seu fluxo não é no terminal puro e sim dentro do editor, vale olhar como fica revisar o diff no Zed, porque a mecânica de não sobrescrever o que o agente está editando muda um pouco por lá

As perguntas para devolver ao agente antes de aceitar

Ler é metade. A outra metade é interrogatório 😀

1. Peça explicação ancorada na seleção, não do diff inteiro

Selecione as linhas obscuras e pergunte em linguagem natural o que aquele bloco faz e por que ele foi escrito assim

Pergunta sobre 12 linhas vem específica. Pergunta sobre 14 arquivos vem genérica e te deixa igualzinho estava antes

O erro comum: pedir "me explica o diff" e receber um resumo bonito que não responde a sua dúvida real

2. Pergunte em plan mode enquanto você ainda está decidindo

Shift+Tab cicla pro plan mode, e prefixar o prompt com /plan aplica o modo a um prompt único

/plan me explica o que essas linhas selecionadas mudam no fluxo de autenticação

Nele o Claude lê arquivos e responde perguntas sem fazer alterações, que é exatamente o que você quer na fase de entender. Shift+Tab de novo sai do modo sem aprovar plano nenhum

O erro comum: perguntar no modo normal, o agente interpretar a pergunta como pedido de correção e começar a editar o diff que você estava no meio de revisar

3. Mande mapear o entorno com o subagente Explore

O Explore é um agente read-only otimizado pra buscar e analisar codebase, com níveis de profundidade quick, medium e very thorough, e mantém a saída da exploração numa janela de contexto separada da conversa principal

É o cara pra responder a pergunta que mais importa num diff que você não domina: quem mais chama isso que ele mudou?

O erro comum: revisar a mudança isolada e esquecer os chamadores. O trecho pode estar perfeito e ainda assim quebrar três lugares que dependiam do comportamento antigo

4. Exija evidência em vez de aceitar "funcionou"

A doc de boas práticas do Claude Code é direta nesse ponto: peça a saída do teste, o comando que foi rodado e o que ele retornou, ou um screenshot do resultado

"Está funcionando" não é evidência, é opinião do agente sobre o trabalho do próprio agente

O erro comum: aceitar o relato e descobrir depois que o teste citado não existe ou não cobre o caminho que mudou

5. Peça run, test, compare ou verify no mesmo prompt

A mesma doc orienta pedir essas ações explicitamente pro Claude iterar em vez de parar na primeira tentativa, e separar pesquisa e planejamento da implementação pra não resolver o problema errado

O erro comum: prompt só com "conserta", que devolve uma tentativa sem verificação e te transforma no controle de qualidade manual da coisa

Colocando uma segunda opinião no diff com /code-review

Camada extra, não substituto da sua leitura, beleza?

1. Rode o review no diff atual

/code-review

É uma skill embutida que revisa o diff atual em busca de bugs num subagente novo e devolve os achados pra sessão

2. Escolha o nível de esforço conforme o tamanho do diff

Os níveis são low, medium, high e xhigh

/code-review high

Sem nível informado, ele reaproveita o último nível usado e mostra um aviso do tipo "Reusing high effort"

O erro comum: achar que está rodando no padrão e estar rodando no nível que você escolheu ontem, pra outro tipo de mudança

3. Use –fix com consciência

A flag –fix aplica os achados em vez de só listar, o que é muito prático e muito perigoso se a sua árvore está suja

E tem um detalhe que pega gente experiente: as edições aplicadas por um review em background com –fix ficam fora dos checkpoints da sessão, então o /rewind não desfaz essas mudanças

Ou seja, sua rota de fuga ali é o git, não o rewind

O erro comum: rodar com –fix em cima de trabalho não commitado contando com o /rewind depois, e descobrir na pior hora possível que ele não alcança essas edições

4. Escale pro ultrareview quando o diff for crítico

/code-review ultra

Isso dispara o ultrareview, uma revisão multiagente que roda em sandbox remoto na infraestrutura do Claude Code na web, e que só roda quando você invoca explicitamente: o Claude não inicia isso sozinho

Quando o recurso está disponível pra conta, /ultrareview funciona como alias

5. Confira a base de comparação do ultrareview

Sem argumentos, ele revisa o diff entre o branch atual e o branch padrão, incluindo mudanças não commitadas e em staging. Passar um nome de branch muda a base de comparação

O erro comum: assumir que o escopo é o mesmo do painel local e receber achados de coisa que você nem lembrava que estava no branch

6. Leia os achados como lista de conferência, não como selo de aprovado

No ultrareview, cada achado reportado passa por reprodução e verificação independentes antes de ser apresentado, o que filtra falso positivo e foca em bug real em vez de sugestão de estilo

Isso é ótimo, mas continua sendo insumo pra sua decisão

O erro comum deste passo (e o mais caro de todos): tratar o resultado como aprovação final e mergear sem ter lido nada com os próprios olhos

Três armadilhas de quem revisa um diff grande (e como prevenir)

"Aceitei, deu ruim e o /rewind não trouxe de volta":

Causa: as edições aplicadas por um review em background com –fix ficam fora dos checkpoints da sessão, então o /rewind não desfaz essas mudanças

Solução: reverter por git, é o único caminho aqui

Prevenção: rodar com –fix só com árvore limpa ou com commit feito antes. Leva cinco segundos e te salva de reescrever o que já estava certo 🙂

"O rewind rodou mas não restaurou tudo":

Causa: o checkpointing só rastreia arquivos editados dentro da sessão atual, então mudança manual feita fora do Claude Code e edição de outra sessão simultânea normalmente não são capturadas

Solução: conferir no git o que ficou fora e resolver ali

Prevenção: evitar mexer no mesmo arquivo em paralelo, seja você na mão ou outra sessão rodando junto. Já viu filme de duas pessoas editando o mesmo arquivo sem saber? Não termina bem

"Perdi o fio da conversa mas o código estava bom" (ou o inverso):

Causa: você precisava de uma restauração parcial e mandou tudo de volta

Solução: /rewind abre o menu de rewind (ou aperte Esc duas vezes com o campo de prompt vazio), que lista cada prompt enviado na sessão com três ações possíveis: restaurar código e conversa, restaurar só a conversa, ou restaurar só o código

Ao restaurar, o Claude Code apaga os arquivos que criou e restaura os arquivos que modificou pro conteúdo daquele ponto

Prevenção: saber que os checkpoints ficam salvos com a conversa, então continuam funcionando depois de retomar a sessão. Não precisa revisar tudo de madrugada com medo de perder o ponto de volta

Como ajustar o método ao tipo de diff que chegou

O roteiro é o mesmo, o peso de cada etapa muda

Refactor amplo:

Aqui o risco não é lógica nova, é inconsistência: um chamador que ficou pra trás, um import morto, um nome que mudou em nove lugares e ficou no décimo

Escopo em não commitado, leitura por camada de risco e peso maior no review automatizado, que é bom justamente em varrer repetição

Feature nova em área que você não conhece:

Inverta a ordem: entenda o terreno antes de julgar a construção

Plan mode pra perguntar, Explore pra mapear quem chama o quê, e só depois a leitura linha a linha

Se o diff mexe em interface e você nem tinha layout definido, o problema começou mais cedo, na hora de descrever a tela no prompt

Quando a revisão vai pro pull request:

O Code Review do Claude no GitHub analisa pull requests e posta os achados como comentários inline nas linhas onde encontrou problemas, com múltiplos agentes analisando o diff em paralelo na infraestrutura da Anthropic e uma etapa de verificação pra filtrar falso positivo

Comentar @claude review inicia uma revisão num PR, e os gatilhos configuráveis são abertura do PR, cada push ou pedido manual

Antes de contar com isso, se liga na disponibilidade: está em research preview, disponível pra assinaturas Team e Enterprise, indisponível para organizações com Zero Data Retention habilitado, e precisa ser habilitado por um Owner da organização

Conclusão

Entender cada linha não é pré-requisito pra revisar bem um diff

O que é pré-requisito: escopo definido, perguntas ancoradas no código exato, evidência de execução em vez de "funcionou", e um caminho de volta que você já sabe usar

No próximo diff que chegar maior do que a sua familiaridade com o trecho, faça nessa ordem: abre o /diff, fixa o escopo com Ctrl+X B, seleciona as três linhas mais obscuras e pergunta, e só então roda o /code-review antes de decidir

Diff grande deixa de ser parede quando vira roteiro

Até o próximo post! 😀