Anderson LimaSoftware Engineer & Architect
4 de outubro de 2026
17 min de leitura
55 visualizações
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.
Published: August 2026
Reading time: 21 min
Keywords: Claude Code, code review, review agent, pull request, security, regression, tests, human ownership
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.
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:
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.
Sem contrato, “revise este PR” pede opinião. Com contrato, pede investigação. Um contrato mínimo define sete coisas:
HEAD~1 pode ignorar commits de um PR empilhado; um review contra uma branch local desatualizada inventa ruído.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.
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.
“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:
P0 a P3 ou equivalente);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 é.
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.
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.
Produtos gratuitos e pagos para transformar ideias em uma base que você consegue executar.
13 produtos disponíveis
nextjs · boilerplate
Boilerplate de API em Python com FastAPI, organizado em Clean Architecture (router, service, repository e adapters por módulo). Inclui autenticação JWT com hashing bcrypt, MongoDB, testes com pytest e cobertura, Dockerfile e docker-compose para subir localmente, e documentação Swagger/OpenAPI automática. Repositório de origem privado; snapshot técnico verificado antes da publicação.
Ver produto
react · boilerplate
Base React Native para apps iOS e Android com Expo, Clean Architecture, MVVM, Firebase e módulos nativos. Referência técnica do VaiDeFut, com distribuição pública no Google Play e fluxo de publicação para iOS documentado.
Ver produto
nextjs · boilerplate
Kit gratuito e open source para começar com agentes de código em Claude Code, Codex, Gemini, Copilot e OpenCode. A licença MIT está confirmada no repositório público.
Ver produto
nextjs · boilerplate
Fundação AI-first white-label para lançar produtos SaaS com Next.js, chat, RAG, memória, tenants e documentação. O snapshot verificado documenta Supabase, não MongoDB; essa limitação está explícita. MongoDB, Redis e RabbitMQ exigem integração/configuração compatível.
Ver produto
nextjs · boilerplate
Edição avançada da base white-label e multi-tenant AI-first para acelerar produtos com Next.js, chat, RAG, memória e documentação. O snapshot verificado ainda não comprova uma camada Ultra distinta; a oferta mantém essa limitação transparente e explicita as trocas de provider, cache e filas.
Ver produto
nextjs · boilerplate
Base white-label e multi-tenant para transformar uma ideia em um SaaS AI-first com Next.js, chat, RAG, memória e segurança documentados. O snapshot verificado usa Supabase; o nome identifica o repositório de origem. Provider, cache e filas ficam explícitos; Redis e RabbitMQ são integrações configuráveis.
Ver produto
react · portfolio
Uma contribuição única para apoiar conteúdo técnico gratuito, pesquisa e a continuidade de projetos relevantes publicados por Anderson Lima. Você escolhe o valor; não é uma assinatura.
Ver produto
react · boilerplate
Starter React gratuito para criar uma suíte de testes confiável desde o primeiro commit, com Vitest, Testing Library, Playwright, Vite, TypeScript, Zustand, React Query, MirageJS e PWA. O repositório não declara uma licença SPDX; revise os termos antes de uso comercial.
Ver produto
react · portfolio
Monorepo público em React, TypeScript e Vite para explorar uma biblioteca de componentes com linguagem visual inspirada em interfaces nativas. O README atual é enxuto e não declara uma licença SPDX; trate como preview gratuito.
Ver produto
nextjs · saas
Boilerplate SaaS AI-first com Next.js, Supabase, Stripe e provider routing para começar do primeiro prompt e acelerar o caminho até um deploy real. As adaptações de IA, banco, e-mail, cache e filas ficam explícitas; Redis e RabbitMQ são integrações configuráveis.
Ver produto
react · saas
Starter kit React + TypeScript para SaaS multi-tenant com Firebase, Atomic Design, temas, PWA, telas de produto, MirageJS e chat com Gemini extensível a outros providers. Valide requisitos de produção, custos e integrações antes de publicar.
Ver produto
react · boilerplate
Starter React público com TypeScript, Zustand, React Query, Tailwind CSS, PWA e integrações de IA documentadas. O repositório não declara uma licença SPDX; revise os termos antes de uso comercial.
Ver produto
nextjs · saas
Landing page SaaS para Next.js, TypeScript e Tailwind CSS com SEO, temas, i18n, PWA e pontos de integração para auth, Stripe e IA. Uma base clara para sair da tela vazia e adaptar sua proposta.
Ver produtoContinue explorando tópicos similares
# Subagents ou Agent Teams no Claude Code: como paralelizar sem criar caos English summary: A practical guide to choosing Claude Code subagents or experimental agent teams, defin
# Permissões do Claude Code: como desenhar autonomia sem abrir a produção English summary: A practical framework for using Claude Code permissions, settings, allow/deny rules, ho
# Observabilidade de Agents no Claude Code: prove o que o loop realmente fez English summary: A practical guide to observing Claude Code agents with events, traces, costs, latenc
Checklist prático para validar segurança, custos, avaliações e observabilidade antes de colocar seu app com IA em produção.
Templates testados em produção, usados por desenvolvedores. Economize semanas de setup no seu próximo projeto.
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.
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.
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.
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.
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.
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.
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.
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.
O agent pode recomendar, mas quatro decisões continuam humanas:
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.
O melhor agent de code review não escreve mais comentários. Ele reduz o tempo entre uma mudança perigosa e uma pergunta precisa: “em qual condição isso quebra, quem é afetado e o que prova que corrigimos?”. Para chegar lá, comece pela base correta, observe os arquivos mudados, siga comportamento até suas fronteiras e exija evidência. Depois limite as tools, separe finding de comentário e faça a ausência de verificação aparecer no relatório.
Claude Code pode tornar essa disciplina repetível com contexto de projeto, subagents, permissions e hooks. A responsabilidade por merge, risco aceito e operação continua onde deve estar: com pessoas que têm contexto e ownership. Essa é a combinação que encontra risco real sem transformar automação em autoridade falsa.