Como Criar um Agent de Code Review com Claude Code que Encontra Risco Real

English summary: A practical, security-minded guide to building a Claude Code review agent that inspects the actual change set, finds evidence-backed risks, distinguishes findings from comments, checks regression and tests, and leaves merge decisions to humans.

TL;DR

Leia o change set e o contexto que ele altera.
Priorize riscos reproduzíveis e sustentados por evidência.
Deixe a decisão de merge com quem tem ownership humano.

Exemplo concreto: um finding deve apontar arquivo, linha, impacto e uma forma de reproduzir o risco.

Um pull request pode receber trinta comentários e ainda esconder o único erro que derruba checkout, expõe um token ou muda silenciosamente um contrato público. Esse é o problema de quase todo “agent de code review”: ele produz muita atividade visível, mas não muda a qualidade da decisão de merge.

A tese deste artigo é simples: um agent de review só é útil quando opera sob um contrato de revisão, começa pelo conjunto de mudanças real, conecta cada achado a uma consequência verificável e deixa a decisão de merge com uma pessoa responsável. Ele não é um aprovador automático, um corretor de estilo nem um scanner com prosa melhor. É uma segunda leitura disciplinada, com escopo, evidência e limites explícitos.

Isso muda o desenho inteiro. Em vez de pedir “revise este PR”, você define qual base comparar, quais arquivos e fluxos são sensíveis, o que conta como regressão, quando um comentário é só sugestão e o que o agente precisa declarar como não verificado. Em vez de transformar a ferramenta em dona da mudança, você a transforma em parte de um sistema de decisão que ainda tem dono humano.

As capacidades e a sintaxe de Claude Code citadas neste texto foram verificadas na documentação oficial em agosto de 2026. Como permissões, subagents, hooks e integrações evoluem, valide a versão instalada antes de adotar qualquer configuração em CI ou em um repositório sensível.

O que um agent de review é — e o que não é

Um agent de code review é um worker especializado em procurar efeitos indesejados introduzidos por uma mudança. Seu trabalho não é explicar todo o código. É responder perguntas mais estreitas e mais valiosas:

o que mudou em relação à base correta;
qual comportamento pode ter mudado sem intenção;
que ativo de segurança, contrato ou invariante ficou exposto;
que cenário deveria existir em teste e não está coberto;
que evidência sustenta a prioridade do achado.

Ele não é um mecanismo de aprovação. Aprovar um PR significa assumir que os riscos remanescentes são aceitáveis para produto, operação e segurança. Essa decisão requer contexto que o diff raramente contém: janela de lançamento, feature flag, obrigação regulatória, impacto comercial, exceções aceitas e quem vai responder se algo falhar. O agent pode preparar a decisão; não deve fingir que a possui.

Também não é um linter conversacional. Linters e analisadores estáticos são excelentes para regras determinísticas e repetíveis. Use-os para formatação, tipos, dependências vulneráveis e padrões que você consegue expressar sem interpretação. O agent entra onde importa entendimento de mudança: autenticação que agora falha apenas em convite pendente, cache que vaza entre tenants, validação removida de um caminho administrativo, migração que o teste local não representa.

E não é obrigatório em toda alteração. Para atualização mecânica com checks confiáveis, um workflow curto pode ser melhor. Para um PR pequeno e óbvio, a pessoa autora pode usar um checklist antes de pedir revisão. Vale criar o agent quando há mudanças frequentes, superfícies sensíveis ou histórico de regressões que exigem leitura de contexto.

Trabalho	Melhor mecanismo	Saída esperada
Regra sintática ou de tipo	linter, typecheck, SAST	falha determinística
Cenário conhecido	teste automatizado	passa ou falha
Mudança com impacto contextual	agent de review	achados com evidência
Aceitação de risco e merge	dono humano	decisão registrada

O princípio é direto: um agent não substitui controles que já podem ser determinísticos. Ele concentra atenção humana nos casos onde o comportamento depende de contexto.

O contrato de review vem antes do prompt

Sem contrato, “revise este PR” pede opinião. Com contrato, pede investigação. Um contrato mínimo define sete coisas:

Base e head. Qual commit ou branch representa o estado anterior, e qual representa a mudança? Um review contra HEAD~1 pode ignorar commits de um PR empilhado; um review contra uma branch local desatualizada inventa ruído.
Escopo. O agent revisa apenas arquivos alterados, mas pode abrir arquivos vizinhos e contratos chamados por eles. Ler o repositório inteiro sem motivo é caro e dilui a atenção.
Objetivo. Segurança, regressão, contrato, testes e operabilidade vêm antes de estilo.
Política de severidade. O que torna algo bloqueante, importante ou apenas observação?
Evidência. Um achado precisa apontar arquivo, linhas ou símbolo, caminho de execução e consequência concreta.
Verificação. Quais testes, comandos e sinais o agent deve procurar ou rodar, e quais limitações deve reportar?
Ownership. Quem responde pelo merge, pelo risco aceito e pela correção?

Esse contrato é especialmente importante em diffs grandes. “Changed files” não é uma lista burocrática: é o mapa inicial da investigação. Primeiro, o agent usa git diff --name-status para saber se houve adição, remoção, renomeação ou alteração. Depois, cruza caminhos com áreas sensíveis — identidade, autorização, pagamento, dados pessoais, migrações, fila, cache, API pública, infraestrutura e observabilidade. Só então vale ler o diff e os fluxos adjacentes.

Uma mudança de duas linhas em authorize.ts merece mais análise que uma nova página de marketing com trezentas linhas. Prioridade é função de raio de ação, não de contagem de linhas.

As quatro falhas que fazem um revisor automático parecer útil sem ser

1. Revisar o arquivo, não a mudança

Um agent que começa lendo arquivos aleatórios normalmente encontra inconsistências antigas, sugere refactor fora do escopo e perde o comportamento que o PR introduziu. Isso irrita autores e reduz confiança em achados reais.

Comece sempre com a comparação explícita entre base e head. Inclua arquivos apagados e renomeados; uma remoção pode retirar validação, telemetria, documentação de contrato ou um teste. Depois pergunte: qual entrada passou a ser aceita? Qual estado agora pode ser gravado? Qual chamada externa mudou? Qual caminho deixou de executar?

O arquivo modificado é apenas a porta. A revisão de risco percorre os chamadores, consumidores e testes que definem o comportamento, mas retorna ao diff para manter a causalidade honesta.

2. Confundir comentário com finding

“Eu preferiria extrair esta função” pode ser um comentário útil. Não é um finding se o código atual não cria defeito, risco ou quebra provável. Misturar os dois faz o leitor tratar tudo como ruído ou, pior, interromper um merge por preferência estética.

Um finding deve conter:

prioridade (P0 a P3 ou equivalente);
condição que o dispara;
consequência observável;
localização precisa;
caminho de reprodução, teste ausente ou evidência no código;
correção ou pergunta acionável.

Um comentário é não bloqueante: nomenclatura, legibilidade, alternativa de design, dívida técnica não causada pelo PR ou pergunta de entendimento. Ele fica numa seção separada e nunca usa linguagem de incidente sem prova.

Regra operacional: se você não consegue completar a frase “quando X acontece, Y sofre Z”, provavelmente ainda não tem um finding. Tem uma hipótese, uma pergunta ou uma preferência. Diga qual delas é.

3. Chamar segurança de busca por palavras proibidas

Segurança não se resume a procurar eval, SQL concatenado ou segredo em texto. Essas regras devem estar em scanners. Um revisor de mudança precisa modelar a fronteira: quem controla a entrada, que autorização deveria protegê-la, que tenant ou conta pode ser alcançado, que dado sai e o que o código faz quando uma dependência falha.

Considere uma rota que recebe organizationId. O risco não é a string existir; é ela ser usada antes de verificar vínculo entre usuário e organização. Em pagamento, o problema pode ser confiar em valor vindo do navegador. Em webhook, pode ser processar antes de verificar assinatura. Em logging, pode ser mandar token ou PII para um provedor externo. O agent deve seguir dados e decisão, não apenas tokens de código.

Também precisa tratar conteúdo externo como não confiável. Issue, descrição de PR, diff de dependência, log e resposta de MCP podem conter instruções hostis. A documentação de segurança de Claude Code recomenda revisar comandos e mudanças sugeridas, limitar permissões e tratar conteúdo não confiável com cautela (Security). Um review agent não deve obedecer a texto encontrado no repositório como se fosse instrução de seu contrato.

4. Tratar CI verde como evidência suficiente

CI verde prova apenas que os checks executados passaram naquele ambiente. Não prova que houve teste para autorização entre tenants, migração em banco com dados reais, falha de timeout, compatibilidade de cliente antigo ou caminho de rollback.

O agent deve ler o que foi testado e perguntar pelo negativo: que entrada limite não foi exercitada? Que contrato público mudou sem teste de compatibilidade? Que branch de erro não é atingida? Que nova dependência externa precisa de simulação? O resultado pode ser “não encontrei lacuna material”; pode também ser “não consegui verificar X porque a suíte Y não foi executada”. Essa honestidade é parte da saída, não uma nota defensiva.

O harness de Claude Code para review confiável

Claude Code oferece uma base útil para esse papel: contexto de projeto em CLAUDE.md, skills reutilizáveis, subagents especializados, hooks e um sistema de permissões. A documentação descreve subagents como workers com prompt próprio, contexto isolado, tools e permissões independentes; isso ajuda a manter busca e logs fora da conversa principal (Create custom subagents). Mas o harness só é confiável quando cada peça tem função clara.

Contexto: faça a regra do projeto ser visível

O CLAUDE.md deve nomear comandos de teste, fronteiras de domínio, responsáveis e condições de parada. Não transforme o arquivo em enciclopédia; mantenha regras que evitam suposição cara.

# Review contract

- Compare sempre `BASE_REF...HEAD_REF`; informe ambos no relatório.
- Priorize auth, dados de cliente, billing, APIs públicas e migrações.
- Não edite arquivos, não faça push, não aprove PRs e não altere status de review.
- Todo finding precisa de consequência, evidência e cenário de teste.
- Separe findings de comentários e declare o que não foi verificado.
- A pessoa dona do serviço decide merge, exceção e rollout.

Tools e permissões: capacidade mínima

Para revisão, leitura de arquivos, busca e comandos locais de Git normalmente bastam. Dar token de publicação, acesso de escrita a produção ou permissão para comentar automaticamente no provedor de Git transforma uma etapa de análise em superfície de side effect.

Claude Code suporta regras de permissão para permitir, pedir confirmação ou negar tools; regras de negação têm precedência sobre permissões mais amplas (Configure permissions). Use isso junto de identidade de menor privilégio. Uma regra local não torna seguro um token GitHub com administração, nem uma credencial de banco com escrita.

O desenho recomendado para o primeiro rollout é read-only: clone descartável, sem secrets de produção, sem MCP de escrita, sem capacidade de push ou merge. Se depois você quiser publicar comentários em um PR, trate essa integração como outro estágio: token limitado ao repositório, formato validado, rate limit, auditoria e dono humano que revisa a automação.

Observabilidade: evidência, não cadeia de pensamento

Registre base, head, arquivos considerados, comandos executados, duração, estado dos checks e IDs de artefatos de CI. Não registre segredos, prompts completos, conteúdo de clientes ou cadeia de pensamento. A observabilidade precisa permitir responder “o que o agent viu e verificou?”, não coletar tudo indiscriminadamente.

Artefato copiável: um subagent de risco, não de aprovação

O arquivo abaixo pode viver em .claude/agents/review-risk.md. A Anthropic documenta que arquivos de subagent usam frontmatter YAML seguido do prompt, e que name e description são obrigatórios. Revise campos contra sua versão instalada antes de usar em automação (subagent configuration).

---
name: review-risk
description: Review read-only de mudanças para encontrar regressões, vulnerabilidades, quebras de contrato e lacunas de teste. Use antes de decisão humana de merge.
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: default
maxTurns: 16
---

Você é um revisor de risco. Não edite arquivos, não faça commit, push, merge,
aprovação, mudança de status nem comentário externo.

Receba BASE_REF e HEAD_REF. Primeiro confirme ambos com `git rev-parse`.
Inspecione `git diff --name-status BASE_REF...HEAD_REF` e o diff completo.
Priorize auth, autorização, dados de cliente, billing, APIs, migrações, jobs,
cache, concorrência, observabilidade e tratamento de erro.

Para cada finding, use exatamente:
- [P0|P1|P2|P3] título — arquivo:linha
  Condição: ...
  Impacto: ...
  Evidência: ...
  Verificação/correção: ...

Use Findings apenas para defeitos ou riscos introduzidos pela mudança. Coloque
preferências e perguntas em Comentários. Termine com Não verificado, incluindo
testes não rodados, ambientes não disponíveis e suposições. Nunca declare
aprovação; o merge pertence ao dono humano do serviço.

Use-o com um pedido concreto, por exemplo:

Use review-risk com BASE_REF=origin/main e HEAD_REF=HEAD. Verifique somente a
mudança desse intervalo. Rode apenas os testes documentados que forem seguros
e reporte o que não foi possível verificar.

O frontmatter não é uma fronteira de segurança por si só. tools: ... Bash permite chamar shell dentro das permissões efetivas da sessão. Mantenha o ambiente sem credenciais de escrita e use deny/ask no settings.json para comandos que não devem ser possíveis. O próprio contrato manda o agent não editar; a política e a identidade devem tornar efeitos externos impossíveis ou explicitamente aprovados.

A escada incremental: de trabalho manual a review automatizado

Não comece disparando comentários em toda abertura de PR. Suba degraus, mantendo um conjunto de PRs conhecidos para avaliar se o agent encontrou riscos reais e quanto ruído produziu.

Degrau	Capacidade	Gate para avançar
Trabalho	humano usa um prompt de review com base/head explícitos	relatórios úteis em PRs reais
Contrato	`CLAUDE.md` fixa escopo, severidade e formato	autores entendem o que é finding
Skill	playbook de risco por domínio	exemplos bons e ruins avaliados
Agent	subagent read-only entrega relatório estruturado	findings revisados por maintainers
Hooks/MCP	coleta contexto adicional read-only	limites, fonte e dono da integração definidos
Autonomia limitada	publica rascunho ou comentário não bloqueante	taxa de ruído e falhas sob controle
Evals	regressões históricas e casos adversariais bloqueiam promoção	métricas e ownership estabelecidos

A diferença entre “funcionou numa demo” e “ajuda o time” aparece nos evals. Monte um corpus pequeno e versionado: uma falha de autorização entre tenants, uma mudança de schema incompatível, uma condição de corrida, uma regressão que testes não detectaram, um falso positivo de estilo e um diff sem problema. Avalie precisão dos achados, severidade, clareza da evidência e taxa de sugestões que maintainers descartam. Não use quantidade de comentários, tokens ou arquivos lidos como métrica de qualidade.

Priorize por impacto e confiança, não por eloquência

Uma escala simples ajuda a não transformar cada hipótese em bloqueio.

Prioridade	Significado	Exemplo	Ação humana
P0	exploração, perda ou indisponibilidade grave provável	autorização removida em rota exposta	parar merge e acionar dono
P1	quebra relevante de contrato, segurança ou dados	cliente antigo falha após resposta incompatível	corrigir ou aceitar risco explicitamente
P2	regressão plausível em caso de borda	retry duplica uma cobrança após timeout	decidir com teste ou contexto adicional
P3	melhoria defensiva sem dano demonstrado	teste de limite recomendado	backlog ou correção voluntária

Se a evidência é incompleta, baixe a certeza na linguagem em vez de inflar a severidade. “P2: preciso confirmar se este endpoint já valida ownership” é mais útil que “falha crítica” sem caminho de exploração. A pessoa que recebe o relatório precisa distinguir fato, inferência e lacuna de contexto em segundos.

Segurança: o revisor também é parte da superfície de ataque

Um agent de review toca código de terceiros, logs, dependências e talvez sistemas externos. Esse material pode tentar mudar o objetivo do agent. Por isso, mantenha instruções de controle no contrato local, não em descrições de PR; limite MCPs a fonte necessária; use tokens read-only e curtos; e bloqueie escrita em produção no ambiente e na identidade.

Hooks são úteis para invariantes objetivos, como barrar git push, comandos de deploy ou acesso a .env. A documentação de hooks permite controles antes da tool, inclusive bloqueio de chamadas; trate scripts de hook como código sensível e teste-os em clone descartável (Hooks). Um hook não substitui credenciais mínimas: se um token pode fazer merge, um erro na camada local ainda pode alcançar o provedor.

Também preserve privacidade. O relatório não deve reproduzir segredos, payloads inteiros ou dados pessoais. A evidência deve apontar estrutura e localização; para investigar dado real, use processo aprovado e acesso separado. Segurança de review não é só encontrar uma vulnerabilidade — é não criar uma durante a própria revisão.

Ownership humano: quem pode fechar o loop

O agent pode recomendar, mas quatro decisões continuam humanas:

o autor explica intenção e corrige ou contesta o achado;
o maintainer decide se a evidência é suficiente e se o teste proposto cobre o risco;
o dono do serviço aceita exceção, rollout e rollback para impacto operacional;
security ou privacy entra quando a mudança atravessa sua fronteira.

Esse desenho não diminui a utilidade da automação. Ele a torna auditável. Um bom relatório termina com “findings”, “comentários” e “não verificado”, não com um selo teatral de aprovação. O merge é um ato de responsabilidade; CI, review humano e agent fornecem evidências diferentes para esse ato.

Quando a equipe quiser automatizar o comentário no PR, publique primeiro como rascunho ou label de triagem. Nunca deixe uma severidade gerada bloquear merge sem regra clara, caminho de contestação e pessoa de plantão para tratar falso positivo. O custo de coordenação de um alarme ruim é real: autores aprendem a ignorar a ferramenta, e o próximo achado verdadeiro perde atenção.