Use Claude Code Review como uma barreira de pull request com CLAUDE.md e REVIEW.md

Anthropic lançou o Code Review para Claude Code em 9 de março de 2026, com um número que deveria fazer qualquer gerente de engenharia estremecer: dentro da Anthropic, a produção de código por engenheiro tinha crescido 200% em um ano, e a revisão virou o gargalo (Anthropic). Essa é a história de verdade. Programar com AI não eliminou o trabalho de revisão. Só mudou onde a pressão aperta.

A resposta útil não é “deixa o Claude aprovar a própria lição de casa”. É assim que você monta uma fábrica educada de bugs. A resposta útil é transformar o Claude Code Review em uma barreira repetível de PR, com regras nas quais o seu time realmente acredita.

A documentação de setup da Anthropic agora torna isso viável. Um revisor pode disparar uma revisão comentando @claude review, e o Code Review lê os arquivos CLAUDE.md do repositório mais um REVIEW.md na raiz. Violações de CLAUDE.md são tratadas como achados de nível nit, e o Claude pode até sinalizar um PR que deixa o CLAUDE.md desatualizado (Claude Help Center). REVIEW.md é onde você coloca regras só de revisão, incluindo o exemplo que a Anthropic dá: “qualquer nova rota de API precisa ter um teste de integração.”

Essa frase é a dobradiça. Pare de pedir para revisores de AI “tomarem cuidado”. Comece a dar a eles a lei do repositório.

O Problema: AI Deixou a Revisão de PR Mais Barulhenta

A discussão da comunidade é bagunçada porque os dois lados têm razão.

Na thread do Hacker News sobre o Claude Code Review, desenvolvedores questionaram o preço, o valor e o fato desconfortável de uma empresa de AI vender um revisor para código gerado por AI. Um comentarista apontou para os próprios números da Anthropic sobre PRs grandes e leu aquilo como um sinal de alerta sobre a qualidade do desenvolvimento agentic, enquanto outros argumentaram que um segundo par de olhos profundo é exatamente onde a ferramenta se paga (Hacker News).

O Reddit tem a versão mais prática do mesmo debate. Em uma thread, um desenvolvedor perguntou se as pessoas realmente confiam em código gerado pelo Claude a ponto de pular a revisão, porque às vezes o Claude escreve código que elas não entendem. As respostas foram diretas: revise, valide, mantenha as mudanças pequenas e não finja que delegar faz a responsabilidade desaparecer (Reddit). Em outra thread, pessoas discutiram usar agentes de AI separados para revisar a saída do Claude, ainda conferindo a própria revisão contra a base de código (Reddit).

Minha leitura: usar Claude para revisar código escrito pelo Claude é aceitável se você não tratar isso como julgamento independente. Trate como um revisor júnior muito rápido, muito literal, com contexto enorme e sem senso de dono. Ele deve pegar omissões chatas, inconsistências entre arquivos, testes faltando, armadilhas de segurança, docs desatualizadas e lugares onde um revisor humano provavelmente passaria batido.

Ele não deve ser o aprovador final.

A Anthropic diz isso diretamente. O Code Review não aprova PRs nem os bloqueia sozinho. Os fluxos de revisão existentes continuam intactos (Claude Help Center). Então a “barreira” é uma barreira do time: nada de aprovação humana até o Claude rodar, achados importantes serem resolvidos ou explicitamente dispensados, e o autor do PR lidar com as regras específicas do repositório.

Isso é chato. Ótimo. Barreiras chatas evitam incidentes.

O Setup: Dois Arquivos Markdown, Duas Funções

Claude Code Review tem duas superfícies de memória que importam.

CLAUDE.md é contexto compartilhado do projeto. Ele se aplica a sessões do Claude Code em geral, não só à revisão. A Anthropic recomenda usá-lo para comandos, convenções, notas curtas de arquitetura, restrições rígidas e pegadinhas conhecidas. Eles também recomendam mantê-lo denso em sinal, mais ou menos abaixo de 200 linhas, porque ele é carregado no contexto, mesmo que o cache de prompts reduza o custo repetido de tokens em sessões Enterprise (Claude Help Center).

REVIEW.md é diferente. Ele fica na raiz do repositório e serve só para revisão. A documentação do Code Review da Anthropic diz que seu conteúdo é injetado em todos os agentes de revisão como instruções de alta prioridade, e que ele é o lugar para controlar severidade, volume de nits, regras de pular, checagens específicas do repositório, padrões de verificação e comportamento de nova revisão (Claude Code Docs).

Esta é a divisão que eu uso:

Coloque contexto estável em CLAUDE.md. Coloque pressão de revisão em REVIEW.md. Coloque qualquer coisa determinística no CI.

Uma Barreira Real para Rotas de API

Imagine que um time de backend vive entregando rotas com testes unitários de caminho feliz, mas sem cobertura de integração. Revisores humanos pegam isso às vezes. PRs gerados pelo Claude pioram o problema porque o agente é bom em produzir código de handler plausível e ruim em lembrar cicatrizes específicas de revisão do time.

Comece com CLAUDE.md:

# Project conventions

- API routes live in `src/routes`.
- Integration tests live in `tests/integration`.
- Use `requireAuth()` on non-public routes.
- Validate request bodies with Zod schemas from `src/schemas`.
- Run `pnpm test:integration` before marking API work complete.

Depois adicione um REVIEW.md na raiz:

# Code Review Rules

Treat these as Important unless stated otherwise.

## API routes

If a PR adds or changes a file under `src/routes/**`:
- Flag missing integration test coverage in `tests/integration/**`.
- Flag routes without explicit auth, unless the route is listed as public.
- Flag request bodies that are not validated with a Zod schema.

Do not accept unit tests as a substitute for route-level integration tests.

## Evidence bar

For every Important finding, cite the changed file and the missing or conflicting evidence.
If the claim depends on a convention, cite this REVIEW.md rule.

Essa última seção importa. Revisores LLM conseguem produzir bobagem com confiança. Exigir evidência força a revisão a amarrar um achado a um arquivo, uma linha ou uma política explícita. Isso não elimina falsos positivos, mas muda o formato da revisão de “vibes” para “me mostra”.

Agora um PR adiciona:

// src/routes/billing.ts
router.post("/billing/plan", async (req, res) => {
  const result = await updatePlan(req.body.planId);
  res.json(result);
});

Um bom comentário do Claude Code Review deveria dizer algo como:

• Importante: src/routes/billing.ts adiciona uma nova rota POST sem auth visível.
• Importante: o corpo da request lê req.body.planId sem validação por schema.
• Importante: nenhum teste de integração correspondente foi adicionado em tests/integration/**.

O revisor humano ainda decide. Talvez o router tenha middleware de auth aplicado em um nível acima. Talvez o teste de integração viva em uma suíte de contrato gerada. Tudo bem. A barreira fez seu trabalho se forçou essa conversa antes do merge.

Como Disparar Sem Queimar Dinheiro

A Anthropic oferece três modos de gatilho por repositório: uma vez após a criação do PR, depois de cada push, ou manual. Manual significa sem custo até alguém comentar @claude review; depois disso, pushes adicionais disparam revisões automaticamente para aquele PR (Claude Help Center).

Para a maioria dos times, eu não começaria com “depois de cada push”. A Anthropic diz que o Code Review leva em média cerca de 20 minutos e geralmente custa de US$15 a US$25 por revisão, escalando com o tamanho e a complexidade do PR (Anthropic). Isso é barato comparado a um incidente em produção. É caro comparado a rodar ESLint.

Use uma barreira em camadas:

1. Todo PR roda o CI normal.
2. PRs arriscados recebem @claude review.
3. PRs grandes, mudanças de auth, mudanças em pagamentos, migrações e mudanças em API pública exigem revisão do Claude antes da aprovação humana.
4. Repita a revisão do Claude depois de mudanças grandes, não depois de cada correção de typo.
5. Humanos são donos da aprovação final.

Um checklist leve de PR no GitHub deixa a barreira explícita:

## AI Review Gate

- [ ] CI is green.
- [ ] `@claude review` has run, or this PR is exempt.
- [ ] Important findings are fixed or explained.
- [ ] If this PR changes conventions, `CLAUDE.md` is updated.
- [ ] If this PR changes review policy, `REVIEW.md` is updated.

Se você prefere rodar o Claude dentro do seu próprio workflow, a documentação de GitHub Actions da Anthropic mostra anthropics/claude-code-action@v1 e uma configuração de plugin de code review, com o aviso de sempre para usar GitHub Secrets para chaves de API (Claude Code Docs). Esse caminho dá mais controle de CI. A rota gerenciada do Code Review dá o revisor multiagente mais profundo que a Anthropic descreve.

Não confunda os dois. Um é automação programável. O outro é um revisor pago, em profundidade.

O Truque: Faça o Claude Revisar o Contrato, Não o Estilo

Arquivos REVIEW.md ruins parecem frases de biscoito da sorte:

Please ensure the code is clean, maintainable, secure, and well tested.

Isso vai gerar mingau.

Bons arquivos REVIEW.md codificam cicatrizes:

## Database migrations

Flag as Important if:
- A migration adds a non-null column without a default on an existing table.
- A migration backfills data without batching.
- Application code starts reading a new column before the migration is deployed.

Skip:
- Formatting comments in generated Prisma client files.

É aqui que revisão por AI fica útil. Ela não substitui o gosto do seu engenheiro sênior. Ela reproduz a memória institucional do time em todo PR.

Algumas regras que funcionam bem:

## Re-review behavior

On the first review, report Important and Nit findings.
On later reviews of the same PR, suppress new Nits unless they are directly caused by the latest push.

## Test policy

Flag missing tests only when the changed behavior is observable through a stable public interface.
Do not request snapshot tests for purely visual copy changes.

## Security policy

Flag any new endpoint that:
- Accepts user input without validation.
- Performs authorization by trusting a user-provided account ID.
- Logs tokens, session IDs, API keys, or full request bodies.

Perceba o que está ausente: “deixe o código elegante.” Humanos podem discutir elegância na revisão. O Claude deve checar contratos.

O Que as Threads Estão Deixando Passar

Os debates no HN e no Reddit ficam girando em torno de uma pergunta: AI deve revisar código de AI?

Pergunta errada.

A pergunta certa é: quais partes da revisão você está disposto a tornar explícitas?

Se a sua cultura de revisão vive na cabeça dos engenheiros sêniores, Claude Code Review vai parecer barulhento e arbitrário. Se a sua cultura de revisão está escrita como regras do repositório, ela vira um multiplicador. CLAUDE.md diz ao Claude como o projeto funciona. REVIEW.md diz ao Claude o que o seu time se recusa a mergear.

Isso também responde à reclamação de “documentar para o Claude”. Sim, desenvolvedores agora estão escrevendo docs para um agente. Parece bobo até você perceber que essas docs também são material de onboarding, política de revisão e prevenção de incidentes. Um bom CLAUDE.md também é um arquivo melhor de “como este repositório funciona” para humanos.

A ponta afiada é a responsabilidade. Se o Claude não vê o bug, ainda foi você que mergeou. Se o Claude inventa um bug, ainda cabe a você rejeitar. Se o Claude revisa a própria saída, você ainda precisa de sinais independentes: testes, sistemas de tipos, análise estática, observabilidade e um humano que entenda a mudança.

Use Claude Code Review como uma barreira, não como um juiz. Faça ele perguntar as coisas irritantes toda vez:

• Onde está o teste de integração?
• Onde a auth é aplicada?
• Este PR tornou o CLAUDE.md falso?
• Vale a pena comentar neste arquivo gerado?
• Este achado é sustentado por código, ou é só um palpite?

Isso basta para se pagar nos PRs certos.

Teste o mesmo setup com Claude Fable 5 na OneHop, drop-in, e comece com US$10 grátis.

Leitura complementar: Começando com Claude Fable 5.