Como a Revisão de Código do Claude Realmente Funciona: Diffs, Hooks e o Que o Agente Detecta

Claude Code Review: O Guia Prático para Revisões de PR Agênticas

O Claude Code pode revisar um pull request ou um diff local da mesma forma que um engenheiro sênior experiente faria — lendo arquivos alterados, rastreando pontos de chamada, verificando testes e retornando descobertas classificadas por severidade com sugestões de correção. Este guia é especificamente sobre o uso do Claude Code (a ferramenta de CLI agêntica da Anthropic) para revisão de código: como acioná-lo, como fazer bons prompts, como automatizá-lo em cada commit ou PR e como integrá-lo a um pipeline de equipe.

O Que "Claude Code Review" Realmente Significa

Existem duas coisas muito diferentes que as pessoas chamam de "revisão de código com Claude". A primeira é pedir ao Claude em uma interface de chat para olhar um trecho de código que você cola. A segunda — e o assunto deste guia — é executar o Claude Code, a ferramenta de CLI agêntica da Anthropic, sobre um diff real ou pull request dentro do seu repositório real.

Essa distinção importa enormemente. Quando o Claude Code revisa um diff, ele não está raciocinando isoladamente sobre um trecho colado. É um agente autônomo que pode abrir arquivos, seguir imports, ler as instruções do seu projeto em CLAUDE.md, verificar testes adjacentes e entender o contexto completo de uma mudança antes de emitir uma única descoberta. É essa consciência entre arquivos que torna o resultado genuinamente útil, em vez de genérico.

O Claude Code está disponível como uma CLI que você instala localmente (npm install -g @anthropic-ai/claude-code), ou como um agente executando em um sandbox na nuvem — mais sobre ambas as abordagens adiante. A documentação oficial da Anthropic cobre a instalação e a configuração inicial.

O Fluxo de Trabalho do /review Passo a Passo

O Claude Code vem com um comando de barra /review projetado especificamente para essa tarefa. Aqui está o fluxo de trabalho completo, do diff ao resultado acionável.

Passo 1 — Aponte o Claude Code para o Diff

Existem várias maneiras de fornecer as mudanças que você quer revisar.

Mudanças em stage (o comando /review):

/review

Dentro da sessão do Claude Code, o comando de barra /review inicia uma revisão das suas mudanças. Este é o fluxo de trabalho local mais comum: faça o stage do seu trabalho, execute /review e veja as descobertas antes de commitar. (O comportamento exato do comando evolui — confira a documentação do Claude Code da Anthropic para a sintaxe atual.)

Um intervalo específico do git: Você também pode simplesmente pedir ao agente em linguagem natural — por exemplo, "Revise o diff entre main e este branch e sinalize quaisquer bugs ou regressões." Como o Claude Code pode executar comandos git por conta própria, ele produzirá o diff para o intervalo que você indicar e o revisará. Isso é útil ao revisar um branch de feature antes de abrir um PR, e evita depender de uma sintaxe exata de flags.

Uma URL de pull request do GitHub: Se o seu projeto tiver o GitHub CLI configurado, o Claude Code pode buscar o diff do PR diretamente. Você fornece a URL ou número do PR no seu prompt, e o agente usa o gh para obter o diff junto com a descrição do PR, o que lhe dá contexto de intenção além do código.

Passo 2 — Carregamento de Contexto

Antes de emitir as descobertas, o Claude Code lê o contexto necessário para avaliar o diff adequadamente:

• CLAUDE.md — o arquivo de instruções do seu projeto, que pode definir áreas de foco da revisão, padrões proibidos, regras de arquitetura ou convenções da equipe. Esta é sua principal alavanca para personalizar no que o agente presta atenção.
• Módulos importados e chamadores — se uma função alterada é chamada em dez lugares, o agente lê esses pontos de chamada para verificar se a mudança é retrocompatível.
• Testes existentes — ele lê arquivos de teste para entender o contrato pretendido do código alterado, e para notar quando uma nova lógica carece de cobertura.
• Arquivos de configuração — eslint, tsconfig, pyproject.toml e arquivos semelhantes ajudam o agente a entender quais regras de linting já são aplicadas no CI, para que não repita descobertas que suas ferramentas já detectam.

Passo 3 — Análise

As passagens de análise do Claude Code cobrem várias dimensões simultaneamente:

• Correção — bugs de lógica, erros de contagem (off-by-one), desreferências nulas, suposições incorretas de algoritmo
• Segurança — riscos de injeção, credenciais expostas, desserialização insegura, verificações de autorização ausentes
• Confiabilidade — tratamento de erros ausente, rejeições de promises não tratadas, casos extremos não capturados
• Manutenibilidade — lógica duplicada, nomenclatura pouco clara, documentação ausente para comportamentos não óbvios
• Cobertura de testes — caminhos de código adicionados sem testes correspondentes

O agente não apenas sinaliza uma linha; ele explica por que a descoberta importa e qual seria o impacto se fosse lançada em produção.

Passo 4 — Descobertas Estruturadas

O resultado é uma lista de descobertas, cada uma com:

• Um rótulo de severidade (tipicamente: crítico / aviso / sugestão)
• A referência de arquivo e linha
• Uma explicação em linguagem simples do problema
• Uma sugestão de correção — frequentemente um trecho de código pronto para aplicar

Por padrão, as descobertas vão para o terminal. Para uso em equipe, você pode redirecioná-las: enviar para um arquivo, publicá-las como comentários de PR via gh pr comment, ou usar um hook para gravá-las em um registro de revisão compartilhado.

A revisão do Claude Code segue um pipeline estruturado — do input do diff, passando pelo carregamento de contexto e análise, até as descobertas classificadas e sugestões de correção, com hooks permitindo automação completa.

Um Exemplo Prático: Diff Real, Revisão Real

Para tornar isso concreto, aqui está um diff mínimo em Python e o que uma revisão do Claude Code revela.

O diff:

# Before
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    return result[0]

# After (in PR)
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    if result:
        return result[0]
    return None

O que o autor do PR pensou que havia corrigido: um KeyError quando nenhum usuário é encontrado.

O que o Claude Code revela na revisão:

1. Crítico — Injeção de SQL (linha 2): A f-string interpola user_id diretamente na consulta. Um valor como 1; DROP TABLE users;-- seria executado. Correção: use consultas parametrizadas — db.query("SELECT * FROM users WHERE id = ?", (user_id,)).

2. Aviso — Propagação implícita de retorno None: Chamadores de get_user que não verificam None agora falharão à distância. Revise três pontos de chamada (listados por arquivo) que assumem que um objeto de usuário é sempre retornado.

3. Sugestão — Anotação de tipo ausente: O tipo de retorno deveria ser Optional[User] para que IDEs e verificadores de tipo possam capturar o caso None automaticamente nos pontos de chamada.

4. Sugestão — Teste adicionado, mas incompleto: O novo teste test_get_user_not_found só verifica que None é retornado; não verifica o comportamento quando user_id é 0 ou não é um inteiro.

O autor original corrigiu o KeyError, mas introduziu um risco silencioso de propagação de None e não percebeu a injeção de SQL preexistente. O Claude Code capturou ambos — e os encontrou porque leu os pontos de chamada, não apenas o diff.

Fazendo Prompts para Melhores Revisões com o Claude Code

A qualidade de uma revisão é diretamente proporcional à qualidade do contexto que você dá ao agente. Estes prompts e técnicas produzem resultados consistentemente melhores.

Use o CLAUDE.md para Definir Instruções Permanentes

A maior alavanca está no arquivo CLAUDE.md do seu projeto. Adicione uma seção ## Review Guidelines:

## Review Guidelines
- We use parameterized queries everywhere. Flag any string interpolation in SQL.
- All public functions must have return-type annotations (Python) or JSDoc (JS).
- Security findings should always be severity: critical, not warning.
- We prefer explicit error returns over exceptions in the data layer.
- Do not flag import ordering — Black handles that automatically.

Isso instrui o agente uma vez, e toda revisão no projeto herda essas regras sem exigir que você faça o prompt novamente.

Forneça Intenção no Prompt

Ao invocar uma revisão de forma interativa, diga ao agente o que o PR está tentando realizar:

/review This PR migrates our auth flow from JWT to session cookies. Focus on
session fixation, secure cookie attributes, and any places we might be leaking
the old JWT validation logic.

O contexto de intenção permite que o Claude Code priorize descobertas relevantes em vez de gerar uma checklist uniforme em todas as dimensões.

Peça uma Passagem Apenas de Severidade Primeiro

Para diffs grandes, uma abordagem em duas passagens é eficiente:

/review Pass 1: list only critical and warning severity findings with file+line.
No suggestions yet.

Depois, uma vez que você tenha a lista crítica, peça detalhes de correção para descobertas específicas. Isso evita o problema de um resultado de revisão de 200 linhas em que o bug crítico fica enterrado entre sugestões de estilo.

Peça Confirmação de Entendimento

Para mudanças complexas:

Before reviewing, summarize what this diff is trying to do in two sentences,
then proceed with the review.

Se o resumo estiver errado, você sabe que o agente interpretou mal o diff e pode corrigi-lo antes de perder tempo com descobertas equivocadas.

Automatizando Revisões com Hooks

Executar /review manualmente é útil, mas o verdadeiro ganho de produtividade está em tornar a revisão automática — para que cada commit ou cada PR aberto a acione sem que um humano precise se lembrar de fazê-lo. O sistema de hooks do Claude Code torna isso possível. (O sistema de hooks é abordado em profundidade no guia de hooks do Claude Code — esta seção foca especificamente no caso de uso de revisão.)

Revisão Automática em Cada Commit

No arquivo .claude/settings.json do seu projeto, adicione um hook Stop:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude -p 'Review the diff from the last commit (git diff HEAD~1 HEAD) and list any bugs, security issues, or regressions.'"
          }
        ]
      }
    ]
  }
}

Com isso configurado, toda vez que o Claude Code concluir uma tarefa (incluindo tarefas de codificação que terminam em um commit), o hook é acionado e revisa o diff resultante. As descobertas aparecem no seu terminal imediatamente após o commit ser efetivado.

Revisão Automática na Abertura de PR

Para integração com CI, execute o Claude Code em modo headless (claude -p "<prompt>") dentro de um job do GitHub Actions e publique o resultado como um comentário de PR. O padrão abaixo é ilustrativo — a Anthropic também publica uma GitHub Action oficial do Claude Code, então confira a documentação do Claude Code para a configuração de CI atual e recomendada, em vez de copiar as flags literalmente:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run review
        run: |
          claude -p "Review the diff between origin/${{ github.base_ref }} and HEAD. \
          List bugs, security issues, and regressions, ranked by severity." > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post review as PR comment
        run: gh pr comment ${{ github.event.number }} --body-file review.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Isso publica as descobertas do Claude Code como um comentário de PR automaticamente em cada push. Seus revisores humanos então concentram sua atenção nas descobertas que o agente já revelou, em vez de gastar tempo de revisão nos itens que o Claude Code detecta de forma confiável.

O Que a Revisão do Claude Code Detecta — e o Que Ela Deixa Passar

É importante ter clareza sobre os limites de capacidade. A revisão por IA é genuinamente poderosa para uma classe específica de descobertas, e comprovadamente insuficiente para outras.

O Claude Code se destaca em correção mecânica, padrões de segurança e consistência — enquanto julgamento de produto, ameaças inéditas e aprovação de conformidade permanecem responsabilidades humanas.

O Claude Code detecta de forma confiável:

• Erros de contagem (off-by-one), desreferências de nulo/indefinido e incompatibilidades de tipo visíveis no diff e em seu contexto imediato
• Padrões de segurança conhecidos: injeção de SQL, XSS, lacunas de CSRF, referências diretas a objetos inseguras, validação de entrada ausente, segredos no código
• Violações de estilo e convenção contra as regras definidas no seu CLAUDE.md e arquivos de configuração
• Lógica duplicada — a consciência entre arquivos do agente significa que ele percebe quando uma função que você acabou de adicionar já existe em um módulo utilitário dois diretórios abaixo
• Tratamento de erros ausente — rejeições de promises não tratadas, cláusulas except genéricas, funções que podem retornar None ou undefined sem que o chamador espere isso
• Lacunas de cobertura de teste para os caminhos de código específicos adicionados no diff

O Claude Code não substitui o julgamento humano em:

• Decisões de produto e requisitos. Se a funcionalidade deveria existir, se a UX faz sentido, se o contrato de API é a abstração correta — isso exige contexto de negócio que nenhum agente possui.
• Ameaças de segurança inéditas. O agente conhece classes de vulnerabilidade conhecidas; ele não inventa modelos de ameaça específicos para o ambiente de implantação ou a lógica de negócio da sua aplicação.
• Desempenho em escala. A análise estática não pode substituir a saída de um profiler, resultados de teste de carga, ou o entendimento dos padrões reais de tráfego.
• Conformidade regulatória. GDPR, HIPAA, PCI-DSS e requisitos semelhantes exigem aprovação humana e, frequentemente, revisão jurídica. A revisão por IA não pode substituir isso.
• Dinâmica de equipe e governança de arquitetura. "Isso pertence a este módulo?" ou "Devemos assumir essa dependência?" exigem contexto organizacional.

O enquadramento saudável: a revisão do Claude Code elimina a parte entediante da revisão de código — capturar erros mecânicos, impor convenções, sinalizar padrões conhecidamente ruins — para que seus revisores humanos possam dedicar sua atenção limitada a decisões de julgamento que realmente precisam de julgamento humano.

Integrando a Revisão do Claude Code em um Pipeline de Equipe

Fazer com que uma equipe realmente use a revisão agêntica de forma consistente exige tratá-la como parte de primeira classe do seu fluxo de trabalho, não como um extra opcional.

O Modelo de Três Camadas

Um pipeline de equipe bem-funcional tem três camadas:

1. Pré-commit local — O desenvolvedor executa /review antes de fazer push. A configuração de hook descrita acima automatiza isso. As descobertas nesta camada são as mais baratas de corrigir.
2. Portão de CI — O fluxo de trabalho do GitHub Actions publica as descobertas do Claude Code como um comentário de PR antes que qualquer revisor humano seja designado. Revisores humanos são designados apenas após a revisão de CI passar (sem descobertas críticas).
3. Foco da revisão humana — Os revisores humanos usam o comentário do Claude Code como guia de triagem. Seu trabalho é avaliar itens de julgamento — adequação de arquitetura, correção de produto, trade-offs de desempenho — não reler cada linha em busca de erros de digitação.

Compartilhando Convenções do CLAUDE.md

Seu CLAUDE.md é a camada de configuração para o comportamento de revisão do agente. Trate-o como código: commite-o, versione-o, revise mudanças nele em PRs. Quando a equipe concorda que o Claude Code deve parar de sinalizar um determinado padrão (porque vocês têm um linter para isso), atualize o CLAUDE.md e a mudança se aplica a cada revisão futura.

Calibrando Limiares de Severidade

As equipes frequentemente acham a calibração de severidade padrão barulhenta demais no início. Adicione instruções explícitas ao CLAUDE.md para controlar isso:

## Review Severity Rules
- Only flag console.log as a warning if it is in a non-test, non-debug file.
- Import ordering is never a finding; Prettier handles it.
- Treat any hardcoded credential as critical regardless of context.
- Performance suggestions are informational only unless they affect O(n²) loops.

Após algumas semanas de uso, a maioria das equipes percebe que o nível de ruído cai significativamente assim que a atenção do agente é ajustada para os padrões que realmente importam em sua base de código.

Lidando com Falsos Positivos

O Claude Code ocasionalmente sinalizará algo incorretamente. A resposta correta não é descartar a revisão por completo — é adicionar uma instrução específica do projeto ao CLAUDE.md que trate o padrão. Com o tempo, isso cria uma configuração de revisão cada vez mais precisa e específica do projeto, que reflete os padrões reais da sua equipe.

Executando a Revisão do Claude Code Sem Instalação Local

Tudo o que foi descrito até agora pressupõe que você tenha o Claude Code instalado e em execução no seu terminal. Para muitas equipes — especialmente aquelas em máquinas corporativas bloqueadas, ambientes Windows sem WSL, ou desenvolvedores que querem revisar a partir de uma aba do navegador — a instalação local é um ponto de atrito.

A Happycapy executa o Claude Code em um sandbox seguro na nuvem, diretamente no seu navegador. Você obtém a capacidade completa de revisão agêntica — incluindo carregamento de contexto entre arquivos, suporte a CLAUDE.md e o comando /review — sem instalar nada. Isso é particularmente útil para:

• Revisão de código em pull requests a partir de um navegador, sem puxar o branch localmente
• Equipes iniciando com a revisão do Claude Code que querem um ambiente compartilhado e consistente antes de implantar instalações locais
• Máquinas bloqueadas, onde instalar pacotes npm globais exige aprovação de TI
• Revisão de repositórios desconhecidos, onde você quer o carregamento de contexto do agente sem clonar o repositório inteiro

Se você tem curiosidade sobre como o Claude Code se compara a alternativas em termos de capacidade agêntica, veja Claude Code vs. GitHub Copilot e Claude Code vs. Cursor. E se você quiser entender como a Happycapy executa o Claude Code em um contexto de navegador, Claude Code na Web aborda a arquitetura.

Comece grátis em happycapy.ai

Perguntas Frequentes

P: A revisão do Claude Code funciona em qualquer linguagem?

Sim. O Claude Code não é específico de linguagem — ele lê qualquer diff baseado em texto e aplica raciocínio sobre o código que contém. Ele tende a ser mais preciso em Python, TypeScript, JavaScript, Go e Rust (linguagens com grande representação no treinamento), mas produz descobertas úteis em Ruby, Java, C# e na maioria das outras linguagens populares. Para linguagens específicas de domínio ou frameworks incomuns, adicionar contexto no CLAUDE.md melhora significativamente o resultado.

P: Como o /review difere de simplesmente pedir ao Claude em um chat para olhar meu diff?

A diferença fundamental é o uso agêntico de ferramentas e o contexto do repositório. Em um chat, o Claude vê apenas o que você cola. O comando /review do Claude Code permite que o agente abra arquivos, siga imports, verifique testes e leia as convenções do seu projeto — produzindo descobertas fundamentadas na base de código real, e não apenas no trecho. Para mudanças grandes ou interconectadas, essa diferença é substancial.

P: A revisão do Claude Code vai capturar vulnerabilidades de segurança?

Ela captura de forma confiável classes de vulnerabilidade bem conhecidas: injeção de SQL, XSS, lacunas de CSRF, referências diretas a objetos inseguras, segredos codificados no código, sanitização de entrada ausente. É menos confiável em vetores de ataque inéditos e específicos da aplicação, ou vulnerabilidades que exigem entender seu ambiente de implantação. Trate-a como uma varredura de segurança minuciosa de primeira passagem, não como um teste de penetração.

P: Como eu impeço que a revisão sinalize coisas que meu linter já trata?

Adicione exclusões explícitas ao seu CLAUDE.md: "Não sinalize a ordenação de imports — o isort cuida disso." ou "Não sinalize espaços em branco no final da linha — o Prettier aplica isso." A maioria das equipes constrói essa lista ao longo de duas a três semanas de uso e percebe que a relação sinal-ruído melhora drasticamente.

P: Posso usar a revisão do Claude Code em um monorepo com múltiplas linguagens?

Sim. Você pode delimitar a revisão com um argumento de caminho ou um intervalo de diff do git que cubra apenas o subdiretório que você alterou. Você também pode manter seções de revisão específicas por linguagem no seu CLAUDE.md, que o agente lê como parte do seu carregamento de contexto.

P: O que acontece se o diff for muito grande — digamos, um PR de 3.000 linhas?

Para diffs muito grandes, considere uma abordagem em duas passagens: primeiro peça apenas descobertas críticas e de aviso (sem sugestões), faça a triagem delas, depois peça a análise completa em arquivos ou subsistemas específicos. Para refatorações extremamente grandes, dividir o PR é a melhor correção — tanto para a capacidade de revisão humana quanto de IA.

P: O resultado da revisão é determinístico? Vou obter as mesmas descobertas duas vezes?

Não — como todas as saídas de modelos de linguagem grandes, há variação entre as execuções. Para revisões de alto risco, executar o comando duas vezes e comparar as descobertas é uma prática razoável. A maioria das descobertas críticas aparece de forma consistente; sugestões menores variam mais. Usar uma temperatura mais baixa (se configurável para o seu fluxo de trabalho) ou prompts mais prescritivos reduz a variância.

P: Como a revisão do Claude Code interage com linters e ferramentas de análise estática existentes?

Ela os complementa, não os substitui. Seus linters capturam regras de estilo impostas de forma mecânica e rápida; o Claude Code adiciona compreensão semântica — ele pode avaliar se uma função faz a coisa certa, o que nenhum linter consegue. O pipeline ideal executa ambos: linters em hooks de pré-commit (rápido, determinístico), revisão do Claude Code no CI (mais lento, semântico). O comando /review está ciente da configuração do seu linter e evita duplicar descobertas que suas ferramentas já produzem.

P: Posso personalizar o formato do resultado da revisão para publicar no Slack ou em um ticket?

Sim. Você pode fazer um prompt ao agente para produzir as descobertas em um formato específico — JSON, markdown, ou um template que corresponda ao estilo de comentário de PR da sua equipe. Combine isso com o sistema de hooks e um pequeno script shell, e você terá um pipeline de revisão totalmente automatizado que publica descobertas estruturadas onde quer que sua equipe faça o acompanhamento.

Relacionado: Aprofundamento nos hooks do Claude Code — automatize verificações de pré-commit, linting e fluxos de trabalho personalizados além da revisão.

Guias relacionados

• Claude Code Hooks: O Guia para Usuários Avançados de Automação do Seu Agente
• Construa Agentes Autônomos com o Claude Code SDK: Um Guia Prático para Desenvolvedores
• Claude Code vs GitHub Copilot: Agente Autônomo ou Assistente no Editor?
• Claude Code Web: Como Executar o Claude Code no Seu Navegador (Sem Instalação)