Como Funciona Realmente a Revisão de Código com Claude Code: Diffs, Hooks e o que o Agente Deteta

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

O Claude Code consegue rever um pull request ou um diff local da forma como um engenheiro sénior meticuloso o faria — lendo ficheiros alterados, seguindo pontos de chamada, verificando testes e devolvendo resultados classificados por gravidade com correções sugeridas. Este guia é especificamente sobre o uso do Claude Code (a ferramenta CLI agêntica da Anthropic) para revisão de código: como o acionar, como lhe dar boas instruções, como o automatizar em cada commit ou PR, e como o integrar num pipeline de equipa.

O Que "Revisão de Código do Claude" Realmente Significa

Há duas coisas muito diferentes a que as pessoas chamam "revisão de código do Claude". A primeira é pedir ao Claude, numa interface de chat, que analise um excerto de código que colamos. A segunda — e o tema deste guia — é executar o Claude Code, a CLI agêntica da Anthropic, sobre um diff real ou um pull request dentro do nosso próprio repositório.

A distinção é enormemente importante. Quando o Claude Code revê um diff, não está a raciocinar isoladamente sobre um excerto colado. É um agente autónomo que pode abrir ficheiros, seguir importações, ler as instruções do projeto no CLAUDE.md, verificar testes adjacentes e compreender o contexto completo de uma alteração antes de emitir uma única observação. Essa consciência entre ficheiros é o que torna o resultado genuinamente útil, em vez de genérico.

O Claude Code está disponível como CLI instalável localmente (npm install -g @anthropic-ai/claude-code), ou como um agente a correr numa sandbox na cloud — 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 inclui um comando de barra /review concebido especificamente para esta tarefa. Segue-se o fluxo completo, do diff aos resultados acionáveis.

Passo 1 — Apontar o Claude Code para o Diff

Há várias formas de lhe fornecer as alterações que se pretendem rever.

Alterações staged (o comando /review):

/review

Dentro da sessão do Claude Code, o comando de barra /review inicia uma revisão das nossas alterações. Este é o fluxo local mais comum: fazer stage do trabalho, correr /review, e ver os resultados antes de fazer commit. (O comportamento exato do comando evolui — verificar a documentação do Claude Code da Anthropic para a sintaxe atual.)

Um intervalo específico do git: Também é possível simplesmente pedir ao agente em linguagem natural — por exemplo, "Revê o diff entre main e este branch e assinala quaisquer bugs ou regressões." Como o Claude Code consegue executar comandos git por si próprio, irá produzir o diff para o intervalo indicado e revê-lo. Isto é útil ao rever um branch de funcionalidade antes de abrir um PR, e evita depender de uma sintaxe de flags exata.

Um URL de pull request do GitHub: Se o projeto tiver o GitHub CLI configurado, o Claude Code consegue obter o diff do PR diretamente. Fornecemos o URL ou número do PR no prompt, e o agente usa o gh para obter o diff juntamente 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 observações, o Claude Code lê o contexto de que precisa para avaliar o diff corretamente:

• CLAUDE.md — o ficheiro de instruções do projeto, que pode definir áreas de foco da revisão, padrões proibidos, regras de arquitetura ou convenções de equipa. Esta é a nossa principal alavanca para personalizar aquilo a que o agente presta atenção.
• Módulos importados e chamadores — se uma função alterada for chamada a partir de dez sítios, o agente lê esses pontos de chamada para verificar se a alteração é retrocompatível.
• Testes existentes — lê ficheiros de teste para compreender o contrato pretendido do código alterado, e para reparar quando lógica nova não tem cobertura.
• Ficheiros de configuração — eslint, tsconfig, pyproject.toml e ficheiros semelhantes ajudam o agente a compreender quais as regras de linting já aplicadas na CI, para não repetir observações que as nossas ferramentas já detetam.

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 off-by-one, desreferenciações nulas, pressupostos de algoritmo incorretos
• Segurança — riscos de injeção, credenciais expostas, desserialização insegura, verificações de autorização em falta
• Fiabilidade — tratamento de erros em falta, rejeições de promises não tratadas, casos-limite não capturados
• Manutenibilidade — lógica duplicada, nomenclatura pouco clara, documentação em falta para comportamento não óbvio
• Cobertura de testes — caminhos de código adicionados sem testes correspondentes

O agente não se limita a assinalar uma linha; explica porque é que a observação é importante e qual seria o impacto se fosse posta em produção.

Passo 4 — Resultados Estruturados

O resultado é uma lista de observações, cada uma com:

• Uma etiqueta de gravidade (tipicamente: crítico / aviso / sugestão)
• A referência ao ficheiro e linha
• Uma explicação em linguagem simples do problema
• Uma correção sugerida — frequentemente um excerto de código pronto a aplicar

Por predefinição, os resultados vão para o terminal. Para uso em equipa, podemos redirecioná-los: canalizar para um ficheiro, publicá-los como comentários de PR via gh pr comment, ou usar um hook para os escrever num registo de revisão partilhado.

A revisão do Claude Code segue um pipeline estruturado — desde a entrada do diff, passando pelo carregamento de contexto e análise, até aos resultados classificados e sugestões de correção, com hooks a permitir automação total.

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

Para tornar isto concreto, eis 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 ter corrigido: um KeyError quando nenhum utilizador é 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 query. Um valor como 1; DROP TABLE users;-- seria executado. Correção: usar queries parametrizadas — db.query("SELECT * FROM users WHERE id = ?", (user_id,)).

2. Aviso — Propagação implícita de None: Os chamadores de get_user que não verificam None irão agora falhar à distância. Rever três pontos de chamada (listados por ficheiro) que assumem que um objeto de utilizador é sempre devolvido.

3. Sugestão — Anotação de tipo em falta: O tipo de retorno deveria ser Optional[User], para que os IDEs e verificadores de tipos consigam detetar automaticamente o caso None nos pontos de chamada.

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

O autor original corrigiu o KeyError, mas introduziu um risco silencioso de propagação de None e não reparou na injeção de SQL pré-existente. O Claude Code detetou ambos — e encontrou-os porque leu os pontos de chamada, não apenas o diff.

Como Dar Melhores Instruções ao Claude Code para Revisões

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

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

A maior alavanca está no ficheiro CLAUDE.md do projeto. Adicionar uma secçã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.

Isto instrui o agente uma única vez, e todas as revisões futuras no projeto herdam estas regras sem ser necessário repetir o prompt.

Fornecer Intenção no Prompt

Ao invocar uma revisão interativamente, dizer ao agente o que o PR pretende alcançar:

/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 ao Claude Code priorizar as observações relevantes, em vez de gerar uma lista de verificação uniforme em todas as dimensões.

Pedir Primeiro uma Passagem Só de Gravidade

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 obtida a lista crítica, pedir detalhes de correção para observações específicas. Isto evita o problema de um resultado de revisão com 200 linhas em que o bug crítico fica soterrado entre sugestões de estilo.

Pedir Confirmação de Compreensão

Para alterações complexas:

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

Se o resumo estiver errado, sabemos que o agente interpretou mal o diff e podemos corrigir isso antes de perder tempo com observações mal orientadas.

Automatizar Revisões com Hooks

Executar o /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 ninguém se tenha de lembrar de o fazer. O sistema de hooks do Claude Code torna isto possível. (O sistema de hooks é abordado em profundidade no guia de hooks do Claude Code — esta secção foca-se especificamente no caso de uso de revisão.)

Revisão Automática em Cada Commit

No .claude/settings.json do projeto, adicionar 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 isto configurado, sempre que o Claude Code conclui uma tarefa (incluindo tarefas de programação que terminam num commit), o hook dispara-se e revê o diff resultante. Os resultados aparecem no terminal imediatamente após o commit.

Revisão Automática na Abertura de PR

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

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 }}

Isto publica automaticamente os resultados do Claude Code como comentário de PR em cada push. Os nossos revisores humanos concentram então a sua atenção nas observações que o agente já assinalou, em vez de gastarem tempo de revisão nos itens que o Claude Code deteta de forma fiável.

O Que a Revisão do Claude Code Deteta — e O Que Lhe Escapa

É importante ter uma visão clara sobre a capacidade envolvida. A revisão por IA é genuinamente poderosa para uma classe específica de observações, e de forma fiável insuficiente para outras.

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

O Claude Code deteta de forma fiável:

• Erros de off-by-one, desreferenciações nulas/indefinidas, e incompatibilidades de tipo visíveis no diff e no 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 em falta, segredos no código
• Violações de estilo e convenção contra as regras definidas no CLAUDE.md e ficheiros de configuração
• Lógica duplicada — a consciência do agente entre ficheiros faz com que repare quando uma função que acabámos de adicionar já existe num módulo utilitário duas pastas mais abaixo
• Tratamento de erros em falta — rejeições de promises não tratadas, cláusulas except genéricas, funções que podem devolver None ou undefined sem o chamador estar à espera disso
• Lacunas de cobertura de testes 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 deve existir, se a UX faz sentido, se o contrato de API é a abstração certa — estas questões exigem contexto de negócio que nenhum agente possui.
• Ameaças de segurança inéditas. O agente conhece classes de vulnerabilidade conhecidas; não inventa modelos de ameaça específicos do ambiente de implementação ou da lógica de negócio da nossa aplicação.
• Desempenho à escala. A análise estática não substitui resultados de profiler, testes de carga, ou compreensão dos padrões reais de tráfego.
• Conformidade regulamentar. RGPD, HIPAA, PCI-DSS e regras semelhantes exigem aprovação humana e, frequentemente, revisão jurídica. A revisão por IA não pode substituir isso.
• Dinâmica de equipa e governação de arquitetura. "Isto deveria estar neste módulo?" ou "Devemos adotar esta dependência?" exigem contexto organizacional.

O enquadramento saudável: a revisão do Claude Code elimina a parte aborrecida da revisão de código — detetar erros mecânicos, impor convenções, assinalar padrões conhecidos como maus — para que os revisores humanos possam gastar a sua atenção limitada em decisões de julgamento que realmente precisam de julgamento humano.

Integrar a Revisão do Claude Code num Pipeline de Equipa

Conseguir que uma equipa use a revisão agêntica de forma consistente exige tratá-la como parte de primeira classe do fluxo de trabalho, e não como um extra opcional.

O Modelo de Três Camadas

Um pipeline de equipa que funciona bem tem três camadas:

1. Pré-commit local — O programador executa /review antes de fazer push. A configuração de hooks descrita acima automatiza isto. As observações nesta camada são as mais baratas de corrigir.
2. Portão de CI — O workflow do GitHub Actions publica os resultados do Claude Code como comentário de PR antes de qualquer revisor humano ser atribuído. Os revisores humanos só são atribuídos depois de a revisão de CI passar (sem observações críticas).
3. Foco da revisão humana — Os revisores humanos usam o comentário do Claude Code como guia de triagem. O seu trabalho é avaliar itens de julgamento — adequação arquitetural, correção de produto, compromissos de desempenho — e não reler cada linha à procura de erros de digitação.

Partilhar Convenções do CLAUDE.md

O nosso CLAUDE.md é a camada de configuração para o comportamento de revisão do agente. Deve ser tratado como código: fazer commit, versionar, e rever alterações em PRs. Quando a equipa concorda que o Claude Code deve deixar de assinalar um determinado padrão (porque já existe um linter para isso), atualizar o CLAUDE.md e a alteração aplica-se a todas as revisões futuras.

Calibrar Limiares de Gravidade

As equipas frequentemente consideram a calibração de gravidade predefinida demasiado ruidosa no início. Adicionar instruções explícitas ao CLAUDE.md para a controlar:

## 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 equipas verifica que o nível de ruído diminui significativamente assim que a atenção do agente é ajustada aos padrões que realmente importam na sua base de código.

Lidar com Falsos Positivos

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

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

Tudo o que foi descrito até agora pressupõe que temos o Claude Code instalado e a correr no terminal. Para muitas equipas — especialmente as que trabalham em máquinas corporativas restritas, ambientes Windows sem WSL, ou programadores que querem rever a partir de uma aba do browser — a instalação local é um ponto de fricção.

O Happycapy executa o Claude Code numa sandbox segura na cloud diretamente no browser. Obtemos toda a capacidade de revisão agêntica — incluindo o carregamento de contexto entre ficheiros, suporte para CLAUDE.md, e o comando /review — sem instalar nada. Isto é particularmente útil para:

• Rever código em pull requests a partir de um browser sem obter o branch localmente
• Equipas a adotar a revisão do Claude Code que querem um ambiente partilhado e consistente antes de implementar instalações locais
• Máquinas restritas onde instalar pacotes npm globais exige aprovação de TI
• Rever repositórios pouco familiares onde queremos o carregamento de contexto do agente sem clonar todo o repositório

Se estiver curioso sobre como o Claude Code se compara a alternativas em termos de capacidade agêntica, consulte Claude Code vs. GitHub Copilot e Claude Code vs. Cursor. E se quiser perceber como o Happycapy executa o Claude Code num contexto de browser, Claude Code na Web aborda a arquitetura.

Começar gratuitamente 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 uma linguagem — lê qualquer diff em formato de texto e aplica raciocínio sobre o código que contém. Tende a ser mais preciso em Python, TypeScript, JavaScript, Go e Rust (linguagens com grande representação nos dados de treino), mas produz observações úteis em Ruby, Java, C# e na maioria das outras linguagens comuns. Para linguagens específicas de domínio ou frameworks pouco comuns, adicionar contexto no CLAUDE.md melhora significativamente o resultado.

P: Em que é que o /review difere de simplesmente pedir ao Claude, num chat, para ver o meu diff?

A diferença fundamental está no uso agêntico de ferramentas e no contexto do repositório. Num chat, o Claude só vê aquilo que colamos. O comando /review do Claude Code permite ao agente abrir ficheiros, seguir importações, verificar testes e ler as convenções do nosso projeto — produzindo observações fundamentadas na base de código real, e não apenas no excerto. Para alterações grandes ou interligadas, esta diferença é substancial.

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

Deteta de forma fiável classes de vulnerabilidade bem conhecidas: injeção de SQL, XSS, lacunas de CSRF, referências diretas a objetos inseguras, segredos codificados, sanitização de entrada em falta. É menos fiável em vetores de ataque inéditos e específicos da aplicação, ou vulnerabilidades que exigem compreender o nosso ambiente de implementação. Deve ser tratada como uma primeira análise de segurança meticulosa, não como um teste de penetração.

P: Como faço para impedir que a revisão assinale coisas que o meu linter já trata?

Adicionar exclusões explícitas ao CLAUDE.md: "Não assinalar a ordenação de imports — o isort trata disso." ou "Não assinalar espaços em branco no final — o Prettier impõe isso." A maioria das equipas constrói esta lista ao longo de duas a três semanas de uso e verifica que a relação sinal-ruído melhora drasticamente.

P: Posso usar a revisão do Claude Code num monorepo com várias linguagens?

Sim. Podemos delimitar a revisão com um argumento de caminho ou um intervalo de diff do git que cubra apenas a subpasta alterada. Também podemos manter secções de revisão específicas por linguagem no nosso 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 3000 linhas?

Para diffs muito grandes, considerar uma abordagem em duas passagens: primeiro pedir apenas observações críticas e de aviso (sem sugestões), fazer a triagem, e depois pedir análise completa para ficheiros ou subsistemas específicos. Para refatorizações extremamente grandes, dividir o PR é a melhor correção — tanto para revisão humana como por IA.

P: O resultado da revisão é determinístico? Obterei as mesmas observações duas vezes?

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

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

Complementa-os, não os substitui. Os nossos linters detetam regras de estilo impostas de forma mecânica e rápida; o Claude Code acrescenta compreensão semântica — consegue 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ápidos, determinísticos), revisão do Claude Code em CI (mais lenta, semântica). O comando /review tem conhecimento da configuração do nosso linter e evita duplicar observações que as nossas ferramentas já produzem.

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

Sim. Podemos instruir o agente a apresentar os resultados num formato específico — JSON, markdown, ou um modelo que corresponda ao estilo de comentários de PR da nossa equipa. Combinando isto com o sistema de hooks e um pequeno script de shell, temos um pipeline de revisão totalmente automatizado que publica resultados estruturados onde quer que a nossa equipa acompanhe o trabalho.

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

Guias relacionados

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)