Como revisar o código que o Claude Code escreveu antes de commitar

Fala aí, beleza? O commit é seu, não do agente

Parece óbvio, mas é justamente isso que some quando o Claude Code cospe um diff gigante e o dedo já vai no git commit -m "feat: ..." sem ler nada

Aí o código entra na main, alguém pergunta "por que essa função virou isso?" e a resposta honesta seria "sei lá, a IA fez"

Esse post é sobre fechar essa brecha

O fluxo é o mesmo de sempre, só que aplicado a código que VOCÊ não digitou: ler o diff, entender a intenção de cada mudança, testar o caminho crítico e decidir o que volta pro agente

Bora ver na prática?

O que ter pronto antes de revisar

Antes de sair rodando comando, quatro coisas facilitam demais a vida:

• O Claude Code aberto na mesma sessão que gerou o código: é ali que os comandos de revisão enxergam o diff atual (se ainda não instalou, o guia de instalação do Claude Code resolve)
• Um CLAUDE.md no repositório: o Code Review lê os arquivos CLAUDE.md do repo e trata violação recém-introduzida como achado de nível nit. E se o PR deixa alguma afirmação do CLAUDE.md desatualizada, ele sinaliza que a documentação precisa ser atualizada
• Uma forma de verificar o resultado: nas boas práticas da Anthropic, dar ao Claude uma maneira de conferir o próprio trabalho é apontado como a dica de MAIOR impacto. Ele vai melhor quando tem um alvo claro pra iterar, tipo um teste ou um mock visual
• A noção de que modo de permissão não se pede no chat: quem define é o Shift+Tab, que cicla entre default, acceptEdits e plan

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Se liga nisso, porque é onde muita gente tropeça: pedir "não edita nada ainda" na conversa não é a mesma coisa que estar no plan mode

Os rótulos da interface mapeiam direto pros modos de permissão: Manual (default), Edit automatically (acceptEdits), Plan mode (plan), Auto mode (auto) e Bypass permissions (bypassPermissions)

Repara que a lista de rótulos é maior que o ciclo: o Shift+Tab passa por default, acceptEdits e plan, e o auto só entra nesse ciclo quando o Claude Code roda com a flag --enable-auto-mode

Como revisar o código do Claude Code passo a passo

A sequência abaixo é curta de propósito

O objetivo não é virar auditor de compliance, é sair do "aceitei porque tava bonito" pra "li, entendi e assumo"

1. Veja o que mudou com /diff

O /diff é slash command nativo e mostra o que mudou no código, comparando o trabalho atual com o estado anterior

   /diff

O erro comum deste passo: pular ele porque "o Claude já mostrou o que fez no chat"

O resumo do chat é a versão que o agente conta de si mesmo, o diff é o que realmente foi pro disco

2. Leia a intenção de cada mudança, não só a sintaxe

Pergunta simples por hunk: isso aqui é o que eu pedi? E se não é, é uma melhoria que eu quero ou um efeito colateral que ninguém encomendou?

Quando você quer a proposta ANTES da edição, o caminho é o plan mode: Shift+Tab até chegar nele, ou prefixar um único prompt com /plan

   /plan refatore o parser de datas sem trocar a assinatura pública

No plan mode o Claude pesquisa e propõe mudanças sem editar o código fonte, o que já é metade da revisão feita antes de existir diff (tem um post inteiro sobre planejar antes de executar mudanças se quiser aprofundar)

O erro comum deste passo: ficar no acceptEdits e aprovar edição em lote sem ler

O comportamento padrão do Claude Code é pausar e pedir aprovação quando ele quer editar arquivo, rodar comando de shell ou fazer requisição de rede. Os modos de permissão controlam a frequência dessa pausa, e afrouxar isso é uma decisão, não um detalhe

3. Rode /code-review no terminal

O /code-review revisa o diff atual direto no terminal e reporta bugs de correção mais limpezas de reuso, simplificação e eficiência, sem precisar instalar o GitHub App

   /code-review

Ele aceita níveis de esforço que trocam cobertura por confiança: em low e medium ele reporta só os achados de maior confiança (menos falso positivo), e de high até max ele abre o leque e pode incluir achados dos quais tem menos certeza

Tem também a flag --fix, que aplica os achados na working tree:

   /code-review --fix

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

Nível alto num diff pequeno é ótimo, nível alto em tudo vira barulho que você aprende a não ler

4. Rode /security-review quando o diff toca superfície sensível

   /security-review

Ele checa o diff em busca de vulnerabilidades: SQL injection, cross-site scripting (XSS), falhas de autenticação e autorização, tratamento inseguro de dados e vulnerabilidades de dependências

E dá pra usar de duas formas: sob demanda no terminal, antes de commitar, ou automaticamente em pull requests via GitHub Actions

O erro comum deste passo: tratar como opcional o diff que mexe em login, permissão ou query montada com string

5. Teste o caminho crítico na mão

Revisão por leitura pega intenção errada, teste pega comportamento errado. São coisas diferentes e você quer as duas

Se for pedir TDD, seja explícito ao declarar que é TDD, pra o Claude não criar implementações mock

As boas práticas ainda citam um padrão bem massa: um Claude escreve os testes, outro escreve o código que passa neles

   estamos fazendo TDD: escreva os testes do fluxo de checkout primeiro,
   sem implementar nada ainda

O erro comum deste passo: aceitar um teste que passa sem nunca ter visto ele falhar

6. Decida o que volta pro agente

Aqui tem duas saídas boas

A primeira é revisar em sessão NOVA do Claude Code: um contexto limpo melhora a revisão porque o Claude não fica enviesado a favor do código que ele mesmo acabou de escrever. É o padrão escritor/revisor, com quem escreve e quem revisa em sessões separadas

A segunda é desfazer. O Claude Code captura automaticamente o estado do código antes de cada prompt seu (checkpointing), e o menu de rewind abre com /rewind ou apertando Esc duas vezes com o campo de prompt vazio

   /rewind

O menu lista cada prompt enviado na sessão e oferece quatro ações: Restore code and conversation (volta código e conversa), Restore conversation (volta só a conversa mantendo o código), Restore code (volta os arquivos mantendo a conversa) e Summarize from here (resume a conversa dali pra frente)

Tome cuidado com duas armadilhas aqui

O checkpointing NÃO reverte arquivos que são symlink ou hard link: o Claude Code pula esses caminhos e mostra o aviso Restored the code, but skipped N files, que mantêm o conteúdo atual

E o histórico não é infinito: são snapshots de arquivos dos 100 checkpoints mais recentes de uma sessão

7. Commite

Só agora, e com a cabeça de quem consegue explicar cada hunk se perguntarem

Revisar no terminal ou no pull request: qual usar

As duas vias existem e resolvem momentos diferentes

Pelo terminal ainda dá pra apontar pra um PR específico, pela sintaxe /code-review <nível> <pr#>, e a flag --comment posta os achados como comentários inline no PR

/code-review high 128
/code-review --comment

E se os achados existem mas os comentários inline não aparecem no PR? Não sumiram

Clica em Details ao lado do check Claude Code Review, na aba Checks: a tabela de severidade lista cada achado com arquivo, linha e resumo

Na aba Files changed eles aparecem como anotações presas às linhas do diff

Quando apertar a revisão (e quando dá pra afrouxar)

Revisar tudo no talo é insustentável, e revisar nada é como a gente chegou aqui

Então vale mapear por situação:

• Mudança tocando autenticação, autorização ou banco: /security-review obrigatório e nível de esforço alto no /code-review, aceitando que vem achado menos certo junto. Falso positivo aqui é barato, falso negativo não é
• Refactor grande: revisa em sessão separada, com contexto limpo, pra o revisor não ser o mesmo cara torcendo pelo próprio código
• Exploração descartável: plan mode antes de qualquer edição. Se a proposta não presta, você jogou fora um plano, não um diff
• Regra que você NUNCA quer ver quebrada: isso não é papel de revisão, é papel de hook. Um hook PreToolUse que termina com exit code 2 bloqueia a chamada da ferramenta, e o texto escrito em stderr volta pro Claude como motivo do bloqueio

Detalhe importante do hook: o Claude Code só processa JSON do hook quando o exit code é 0

Com exit 2 qualquer JSON é ignorado e o stderr é usado como motivo do bloqueio

Já sobre afrouxar: rodar em bypassPermissions tira justamente a pausa que te dá chance de olhar antes

O modo auto nem entra no ciclo do Shift+Tab por padrão, ele só aparece quando o Claude Code roda com a flag --enable-auto-mode, virando default → acceptEdits → plan → auto

Ou seja: é uma escolha consciente sua, e o preço dela é revisar depois, no diff inteiro, em vez de acompanhar no caminho

Conclusão

Recapitulando o fluxo pra revisar código do Claude Code antes do commit:

1. /diff pra ver o que mudou de verdade
2. Ler a intenção de cada mudança (e usar plan mode quando quiser a proposta antes da edição)
3. /code-review, escolhendo o nível de esforço pelo tipo de diff
4. /security-review quando o código toca superfície sensível
5. Testar o caminho crítico na mão, com TDD declarado quando for o caso
6. Devolver pro agente numa sessão nova, ou desfazer com /rewind
7. Commitar assumindo o que entrou

O agente escreve, sugere, refatora e até revisa. Mas quem assina o commit é você, e a revisão é exatamente o momento em que essa responsabilidade se exerce, não uma formalidade

Próximo passo prático, pra hoje: no próximo diff, roda /diff e /code-review antes de commitar

E escreve no CLAUDE.md aquela uma regra que você não quer ver violada nunca, porque o Code Review lê esses arquivos e vai bater na sua porta quando ela for quebrada 😀

até o próximo post!