5 padrões de prompt que sobem o sinal do code review com LLM de 12% pra 67%

O bot de code review da sua empresa virou meme. Em todo PR aberto cai o mesmo comentário: "considere adicionar testes para este método". Ninguém mais lê. O time aprendeu que ⅘ dos findings são poluição, então passou a tratar o ⅕ que importa como ruído também.

Esse é o caminho mais rápido pra matar uma ferramenta boa de code review. Não é problema do modelo. É problema do prompt — e da arquitetura ao redor do prompt.

A boa notícia é que dá pra subir a taxa de comentários úteis sem trocar de stack. Os labs que fazem isso bem (Anthropic, Cursor) convergiram em cinco padrões que funcionam em conjunto. Neste post a gente passa por cada um, com prompt real e um workflow Laravel pronto pra plugar no GitHub Actions.

TL;DR

• O que é: cinco padrões de prompt para code review com LLM que sobem o signal ratio de ~20% pra acima de 60%.
• Stack: Claude (Opus 4.7 ou Haiku 4.5), GitHub Actions, REVIEW.md no repositório.
• Custo/Acesso: funciona com qualquer chave da Anthropic; review managed da Anthropic custa entre US$ 15 e 25 por PR.
• Repositório/Link útil: docs oficiais do Code Review e Claude Code Action.

Por que bot de code review vira ruído tão rápido

Tem um número que explica tudo. Análise de 22 mil comentários de review em 178 repositórios mostra que comentários concisos têm 3x mais chance de serem aplicados que os longos. E que ferramenta tradicional de AI review está com signal ratio (findings críticos ou importantes / total) na casa dos 21%. Quase quatro em cada cinco comentários são style suggestion, micro-otimização ou opinião subjetiva.

O time aprende rápido. Depois de duas semanas vendo "considere extrair esse método em um helper" toda hora, o desenvolvedor passa o batch de comentários em scroll e clica "resolve all".

Quando isso acontece, o bug real que tava ali no meio também passa.

Os labs que medem isso direito chegaram em números bem melhores. A Anthropic publicou que o Code Review do Claude tem menos de 1% de findings marcados como incorretos, e que internamente subiu a fração de PRs com comentário substantivo de 16% pra 54%. O Cursor mostrou que o Bugbot foi de 52% pra quase 80% de bugs resolvidos entre julho de 2025 e agora — superando Greptile (63%) e CodeRabbit (49%).

A diferença entre os dois grupos não é o modelo. É o que está em volta do modelo: o prompt, a verificação, a calibração de severidade.

Pré-requisitos

• [ ] Chave de API da Anthropic (ou conta Team/Enterprise pra usar o managed Code Review).
• [ ] Um repositório onde você consiga adicionar REVIEW.md e .github/workflows/.
• [ ] PHP 8.3+ se for usar o exemplo Laravel.
• [ ] Conhecimento básico de GitHub Actions.

Os padrões abaixo funcionam com qualquer provider (OpenAI, Gemini, modelo local). Os exemplos usam Claude porque é o que tem hoje a melhor documentação pública sobre code review específico — mas o conceito não está preso à Anthropic.

Padrão 1: diff-anchored em vez de file-scoped

Esse é o erro mais comum. O time joga o arquivo inteiro no contexto e pede "revise este código". O modelo encontra dez problemas — nove dos quais já estavam ali antes do PR.

O padrão certo é o oposto. O contexto do prompt entrega o diff como entidade principal e o arquivo inteiro como referência. As âncoras de citação são linhas do diff, não linhas do arquivo final.

<diff>
diff --git a/app/Http/Controllers/OrderController.php
@@ -42,8 +42,15 @@ public function store(Request $request)
+    $order = Order::create([
+        'user_id' => $request->user_id,
+        'total' => $request->total,
+    ]);
</diff>

<file_context>
// arquivo completo apenas para entender o contexto
</file_context>

Revise apenas as linhas ADICIONADAS no <diff>. Linhas que já existiam
não devem gerar findings, mesmo que estejam ruins — elas são
pré-existentes e foram aprovadas em outros PRs.

Isso resolve sozinho metade do problema. O modelo deixa de comentar sobre código legado que ninguém pediu pra ele tocar. É exatamente o que o Code Review da Anthropic faz internamente — separa findings em três severidades, e a classe "Pre-existing" sai marcada em cinza pra não competir com o que o PR trouxe.

A consequência prática: o desenvolvedor abre o PR e vê dois comentários, não quinze. Dois comentários ele lê.

Padrão 2: severity gate calibrado pro seu repositório

A definição default de "bug crítico" raramente bate com a do seu time. Pra um serviço de pagamento, query sem WHERE tenant_id é catastrófico. Pra um repositório de docs, isso nem aparece — mas typo em comando bash é P0.

A Anthropic resolve isso com um arquivo REVIEW.md na raiz do repositório, injetado verbatim no system prompt de cada agente do pipeline de review. Não importa o stack que você use — qualquer review com LLM melhora muito quando você define explicitamente os tiers.

Exemplo para uma API Laravel:

# Review instructions

## O que conta como Important

Reserve Important para findings que quebrariam comportamento,
vazariam dado ou impediriam rollback:

- Query Eloquent sem scope de tenant (`->where('tenant_id', ...)`)
- Log com PII (email, CPF, telefone, body de request)
- Migration que não é backward-compatible (drop de coluna,
  rename sem alias, alter type sem default)
- Job sem `tries`/`backoff` configurado
- Endpoint público sem rate limit

## O que é Nit no máximo

- Naming, estilo, refactor
- Extração de método ou trait
- Sugestão de teste sem evidência de bug

## Cap de nits

Reporte no máximo 3 nits por review. Se tiver mais, escreva
"+N nits similares" no resumo. Se TUDO que você achou é nit,
abra o resumo com "Sem problemas bloqueantes."

## Não reporte

- Lint, format, type errors (Pint, PHPStan, Larastan já cobrem)
- Arquivos sob `database/factories/` e `tests/Pest.php`
- Sugestão de teste sem apontar um cenário concreto que quebra

O detalhe que muita gente perde: o cap de nits importa tanto quanto a definição de Important. Um review que solta 20 sugestões de estilo afoga os 2 bugs reais que veio com o PR. Limitar nits a 3 ou 5 força o modelo a escolher.

Padrão 3: tool use antes do palpite

O modelo está olhando pra um diff de 30 linhas e quer comentar "essa função calculateTotal pode dar null pointer". Olhando pra esse trecho, parece razoável. Mas o calculateTotal real está em outro arquivo, foi atualizado mês passado pra retornar 0.0 em vez de null, e o "bug" não existe.

Esse é o cenário em que o modelo inventa bug. E ele inventa porque a única coisa que ele tem são 30 linhas.

A solução é dar tool use antes de pedir o veredicto. O agente abre o arquivo referenciado, faz grep da função, lê o teste relacionado, e só depois decide se o finding é real.

Esquema do prompt em pseudo-código:

Você é um code reviewer. Ferramentas disponíveis:

- read_file(path: str) -> str
- grep(pattern: str, path: str) -> list[match]
- run_tests(path: str) -> str

Antes de reportar QUALQUER finding sobre comportamento de função,
classe ou método que NÃO esteja inteiramente no diff, você DEVE:

1. read_file no arquivo da definição
2. grep pelos callers existentes
3. Validar que o cenário que você ia reportar realmente se
   manifesta — não que "poderia teoricamente se manifestar"

Se você não conseguir verificar, NÃO reporte. Anote em
"unverified_concerns" para o autor revisar manualmente.

É exatamente o "verification step" que a Anthropic descreve no Code Review: múltiplos agentes em paralelo geram candidatos, e um passo de verificação cruza cada candidato contra o comportamento real do código antes de virar comentário. É o que sustenta o "menos de 1% de findings marcados como incorretos".

O modelo certo pra essa etapa importa. Claude Opus 4.7 segue instrução de severidade muito melhor que versões anteriores — quando o prompt diz "só reporte high severity", ele investiga com a mesma profundidade mas filtra antes de postar. Em modelos mais fracos, a mesma instrução cai no buraco do "vou comentar tudo só pra garantir".

Padrão 4: citation obrigatória

Esse padrão é curtinho mas é o que mais corta hallucination.

Toda afirmação sobre comportamento de código tem que vir com file:line apontando pra evidência. Se o modelo escreve "essa função pode lançar exceção não tratada", ele precisa anexar onde no código essa exceção é levantada.

Regra no REVIEW.md:

## Verificação obrigatória

Todo finding que faz afirmação sobre comportamento (vai quebrar,
vai vazar, vai dar timeout) precisa incluir:

- file:line do código que sustenta a afirmação
- Citação literal do trecho (até 3 linhas)
- Cenário concreto: "se input for X, linha Y retorna Z, o que
  faz a linha W (no caller A) lançar exceção B"

Findings derivados de inferência por nome de função
("parece que `processPayment` não trata erro") sem citation
NÃO devem ser postados.

Isso muda o jogo. O modelo não consegue mais postar palpite educado. Ou ele tem evidência concreta, ou cala. O REVIEW.md da Anthropic dá exatamente esse exemplo: "behavior claims need a file:line citation in the source, not an inference from naming".

Efeito colateral bom: quando o finding vem com citation, o desenvolvedor não precisa decidir se confia no bot. Ele clica no link, lê as 3 linhas, decide em 10 segundos.

Padrão 5: self-grading com threshold

Os quatro padrões anteriores reduzem ruído na entrada. O quinto é o filtro de saída.

Antes de postar qualquer finding, um segundo passo (LLM-as-a-judge) dá score a cada um. Findings abaixo de um threshold de confiança são descartados, não enviados.

Para cada finding gerado, avalie em três dimensões (0.0 a 1.0):

- confidence: quão certo você está de que isso é um bug real,
  não inferência. Citation forte = alto. Inferência por nome = baixo.
- severity: impacto se o bug se manifestar em produção.
- actionability: o autor consegue agir nesse finding em até
  10 minutos sem pedir contexto?

Score final = média ponderada (0.5 * confidence + 0.3 * severity
+ 0.2 * actionability).

Poste apenas findings com score >= 0.7.

Findings entre 0.5 e 0.7 vão pra seção "unverified" do resumo
(sem inline comment). Abaixo de 0.5, descartar.

Threshold de 0.7 é onde a maioria dos times converge. Mais baixo, volta o ruído. Mais alto, perde bug genuíno. Vale rodar uma rodada calibrando no seu próprio repositório com 30–50 PRs antigos: aplica o pipeline em modo dry-run e compara com a decisão humana real (quem mergeou, quem rejeitou, quem pediu fix).

Esse é o padrão que o Cursor implementou em 40 experimentos pra descobrir o insight contra-intuitivo: ser mais agressivo na detecção e ao mesmo tempo mais rigoroso no filtro reduziu false positives. O segredo não é o modelo ver menos bugs. É ele postar menos.

Workflow Laravel pronto

Junta tudo num .github/workflows/claude-review.yml:

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Claude code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          model: claude-opus-4-7
          mode: review
          # arquivo lido como highest-priority instruction
          review_instructions_path: REVIEW.md
          # restringe ao diff
          diff_only: true
          # threshold de self-grading
          min_finding_score: 0.7
          # cap de comentarios por PR
          max_inline_comments: 8

E o REVIEW.md correspondente, juntando os cinco padrões pra um projeto Laravel:

# Review instructions

## Escopo

Revise APENAS linhas adicionadas no diff. Linhas pré-existentes
não geram findings.

## Severity

Important (bloqueia merge no resumo):
- Query Eloquent sem scope de tenant
- Log com PII (email, CPF, telefone, body)
- Migration nao-backward-compatible
- Endpoint publico sem throttle middleware
- Job sem `$tries` ou `$backoff`

Nit (ate 3 por review):
- Naming, refactor, extracao
- Type hint faltando em metodo publico

Pre-existing: nao reporte, mesmo que veja.

## Verificacao obrigatoria

Toda afirmacao sobre comportamento precisa de file:line +
citacao literal + cenario concreto. Sem citation, nao poste.

## Self-grading

Score cada finding em confidence/severity/actionability.
Threshold de post = 0.7. Abaixo disso, vai pro resumo
como "unverified".

## Nao reporte

- Lint/format/types (Pint + Larastan cobrem)
- Sugestao de teste sem cenario concreto
- Arquivos em `database/factories/`, `bootstrap/`, `vendor/`

A primeira semana com isso ligado vai parecer que o bot ficou preguiçoso. PRs que antes vinham com 12 comentários agora vêm com 2 ou 3. É o efeito esperado. O que muda é que esses 2 ou 3 são lidos — e os bugs neles, corrigidos antes do merge.

Limitações e cuidados

Esse pipeline não substitui code review humano. Ele filtra ruído pra que o humano possa focar em arquitetura, contexto de negócio e decisão de produto — coisas que o modelo ainda não tem como saber. Trate o bot como um primeiro filtro, não como o reviewer.

Cuidado com over-filtering. Se você calibra o threshold muito alto, o pipeline passa a perder bugs sutis que valeriam o comentário. Mantenha uma seção de "unverified" no resumo do review — assim os findings borderline ficam visíveis sem virar inline comment ruidoso.

Custo escala com tamanho de PR. O Code Review managed da Anthropic custa US$ 15 a 25 por PR em média, com PRs grandes (>1000 linhas) puxando o teto. Se você usa o action open-source com sua própria chave, o custo cai bastante mas você herda a complexidade de calibrar prompt, tool use e verificação. Vale a pena medir o ROI: 33 horas/dev/mês perdidas filtrando comentário ruim é um número que justifica o investimento em quase qualquer time acima de 5 devs.

Por último: o REVIEW.md envelhece. Toda vez que o time muda de stack ou aprende uma lição cara em produção, atualize o arquivo. Os padrões 2, 4 e 5 funcionam porque o conteúdo do REVIEW.md está atualizado — não pela ferramenta em si.

FAQ rápido

Por que o bot continua comentando "considere adicionar testes" mesmo com REVIEW.md proibindo? Provavelmente o REVIEW.md está em diretório errado ou o prompt do bot que você usa não injeta o arquivo. No Code Review managed da Anthropic, o REVIEW.md precisa estar na raiz do repositório. Em pipelines custom, confirme que o conteúdo está sendo concatenado ao system prompt antes de cada agente — não basta o arquivo existir, alguém precisa lê-lo.

Posso usar Haiku 4.5 em vez de Opus 4.7 pra economizar? Sim, especialmente em PRs pequenos. Haiku 4.5 é bom em seguir instrução de severidade e funciona bem com tool use simples. Em PRs grandes (>500 linhas) ou em código com muita lógica de domínio, Opus 4.7 ainda compensa pela qualidade dos findings.

Como sei se meu signal ratio está bom? Pega 20 PRs revisados na última semana, conta quantos findings o bot postou e quantos foram realmente aplicados (commit que segue, com mensagem fazendo referência ao comentário). Signal ratio = aplicados / total. Acima de 60% é saudável. Abaixo de 30%, recalibre REVIEW.md antes de continuar.

E se eu não usar Claude, o padrão vale? Vale. Os cinco padrões são arquitetura de prompt + verificação, não específicos da Anthropic. Funcionam com OpenAI, Gemini, modelo local (qualquer modelo com tool use decente). O que muda é a qualidade do filtro — modelos com tool use mais maduro entregam menos false positives.

Fechando

Code review com LLM não falha porque o modelo é ruim. Falha porque ninguém calibrou o que conta como bug, ninguém deu ferramenta pra verificar a hipótese, e ninguém filtrou a saída antes de postar. Os cinco padrões aqui são exatamente o que separa um pipeline que o time respeita de um bot que viraria meme em uma sprint.

Se você está começando, pega o REVIEW.md deste post, ajusta as regras pro seu stack, liga em um repositório novo. Mede o signal ratio em duas semanas. Calibra. O ganho mais difícil — fazer o time voltar a confiar no bot — vem rápido quando os comentários começam a fazer sentido.

E se você está construindo esse tipo de pipeline pra valer e quer trocar nota com gente que está debugando os mesmos prompts em produção, a conversa rola na Beer and Code, a melhor comunidade de AI engineering em português, com grupo no WhatsApp aberto pra quem está construindo IA em produção.