Checklist de Code Review com Claude Code para Times

Comece pelo risco, não por “review this”

Se você mandar um diff para o Claude Code e disser apenas “review this PR”, ele tende a devolver comentários úteis, mas genéricos.

Em um time, review precisa começar com perguntas mais objetivas: o que pode quebrar, quais dados foram tocados, qual evidência de teste existe e o que deve bloquear o merge.

Este guia traz uma checklist copiável, um prompt de review para Claude Code, um template de pull request no GitHub e um CI guard com GitHub Actions.

Claude Code não substitui a responsabilidade humana. Ele funciona como uma segunda leitura para reduzir esquecimentos e estabilizar o padrão do time. Para os detalhes oficiais, consulte o guia de Claude Code sobrecode review setup, a documentação deClaude Code GitHub Actions, os docs do GitHub sobrePR templates, protected branches eActions workflows. Para segurança, use aOWASP Secure Code Review Cheat Sheet.

O que é review baseado em risco

Review baseado em risco significa não tratar todo PR do mesmo jeito. Uma alteração de texto, um ajuste de CSS, um webhook de pagamento e uma migration destrutiva têm impactos diferentes. Se tudo for pesado, mudanças pequenas ficam lentas. Se tudo for leve, mudanças perigosas passam sem atenção.

Três níveis são suficientes para começar:

Risco	Exemplos	Review obrigatório
Low	Texto, CSS simples, docs, texto de log	Um reviewer, resumo claro, screenshot ou explicação do diff
Medium	Formulários, estado de UI, busca, formato de resposta API, leitura de dados	Um reviewer, evidência de teste, review com Claude Code
High	Auth, autorização, billing, dados pessoais, migration, delete, webhook	Dois reviewers, plano de rollback, CI obrigatório, review de segurança/privacidade

Migration é qualquer mudança na estrutura ou no formato dos dados. Código costuma ser revertido. Colunas removidas, registros reescritos e backfills quebrados são mais difíceis de recuperar. Por isso, em migration a primeira pergunta é “como voltamos atrás?”.

Ao usar Claude Code, declare o risco. Um prompt vago gera comentários de estilo. Um prompt como “High risk: billing webhook and customer email changed” direciona a revisão para validação de assinatura, idempotência, retries, privacidade, logs e evidência de testes.

Nas notas práticas de Masa, o erro repetido era usar só palavras abstratas como qualidade, segurança e manutenibilidade. Elas servem como títulos, mas não como perguntas. Um bom template de PR obriga a escrever arquivos tocados, tipos de dados, motivos de risco, testes e rollback.

Checklist copiável

Coloque esta checklist em .github/review-checklist.md, na wiki do time ou na seção de review do CLAUDE.md. Os itens são concretos para que humanos e Claude Code possam verificar fatos.

# Code Review Checklist

## 0. PR scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] Generated or AI-written files are marked in the PR description.
- [ ] No unrelated formatting, dependency, or config changes are mixed in.

## 1. Risk level
- [ ] Risk level is marked as low, medium, or high.
- [ ] High-risk PRs have two human reviewers.
- [ ] High-risk PRs include rollback or recovery steps.

## 2. Security and privacy
- [ ] User input is validated on the server side.
- [ ] Authorization is checked near the data access point.
- [ ] Secrets are not printed, committed, or sent to Claude prompts.
- [ ] Logs do not include email, tokens, addresses, payment IDs, or private content.
- [ ] OWASP-relevant risks such as injection, XSS, broken access control, and SSRF were considered.

## 3. Tests
- [ ] Unit or integration tests cover the changed behavior.
- [ ] Regression tests cover the bug that motivated the PR.
- [ ] Manual verification steps are written with actual result, not "works locally".
- [ ] Snapshot changes are explained.

## 4. Performance
- [ ] New loops, queries, and network calls are bounded.
- [ ] N+1 queries were checked.
- [ ] Large lists, images, and bundles have a budget.
- [ ] Metrics or before/after evidence are attached for performance-sensitive changes.

## 5. Accessibility
- [ ] Keyboard operation works for interactive UI.
- [ ] Focus order and visible focus state are preserved.
- [ ] Form fields have labels and errors that screen readers can understand.
- [ ] Color contrast and reduced-motion behavior are checked where relevant.

## 6. Migration and data risk
- [ ] Migration is backward compatible during rollout.
- [ ] Destructive changes have backup or recovery steps.
- [ ] Old and new app versions can run during deployment.
- [ ] Data cleanup jobs are idempotent.

## 7. AI-generated diff hygiene
- [ ] AI-generated code was read by a human before approval.
- [ ] The diff does not remove tests, monitoring, analytics, or CTA links by accident.
- [ ] New dependencies are justified.
- [ ] Comments do not claim verification that was not actually done.

O ponto central é que cada item precisa ser verificável. “Segurança considerada” é fraco. “Logs não incluem email, tokens, endereços, payment IDs ou conteúdo privado” dá para checar. “Acessibilidade ok” é fraco; “teclado, foco visível, labels e mensagens de erro funcionam” é uma pergunta real.

Prompt de review para Claude Code

O prompt deve declarar papel, contexto, risco e limite: findings primeiro, sem alterar código. Se Claude Code começar a corrigir antes da decisão do time, o diff cresce e fica difícil separar review de implementação.

You are reviewing a pull request for a production team.

Goal:
- Find concrete risks before merge.
- Prioritize correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
- Do not rewrite code yet. Produce review findings first.

Context:
- Risk level: <low | medium | high>
- Business area: <auth | billing | content | search | admin | analytics | other>
- Sensitive data touched: <none | email | payment | address | health | private content | other>
- Rollout plan: <flag | migration | immediate deploy | other>

Review method:
1. Read the PR summary and changed files.
2. List the top risks by severity.
3. For each finding, include file, line or function, why it matters, and a minimal fix.
4. Separate "must fix before merge" from "follow-up".
5. Check whether tests prove the changed behavior.
6. Check whether any AI-generated code, dependency, config, or formatting change is unrelated to the PR goal.

Output format:
- Findings first, ordered by severity.
- Then missing evidence.
- Then questions for the author.
- Then a short merge recommendation: block, approve with fixes, or approve.

Ele combina bem comnavegação de codebase eestratégias de teste. Antes da revisão, peça para Claude Code explicar rapidamente o domínio que o PR toca. Isso evita uma revisão limitada a nomes e formatação.

Template de pull request no GitHub

Com .github/pull_request_template.md, o GitHub preenche o corpo do PR. O objetivo não é burocracia, mas reunir evidência para reviewers, Claude Code e branch protection.

## Summary
- TODO

## Risk
Risk level: low | medium | high

Risk reasons:
- Data touched:
- Users affected:
- Rollout:

## Review focus
- [ ] Correctness
- [ ] Security/privacy
- [ ] Tests
- [ ] Performance
- [ ] Accessibility
- [ ] Migration/data risk
- [ ] AI-generated diff hygiene

## Test evidence
- Automated:
- Manual:
- Not tested because:

## Security and privacy notes
- Secrets changed: no | yes
- Personal data in logs: no | yes
- Authorization boundary changed: no | yes

## Migration / rollback
- Migration included: no | yes
- Backward compatible: no | yes | not applicable
- Rollback plan:

## Claude Code review prompt
Paste this into Claude Code after the PR is ready:

Review this PR as risk level "<low|medium|high>".
Focus on correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
Return findings first with file/function references and minimal fixes.

Evite um template só com checkboxes. O time rapidamente passa a marcar tudo de forma automática. Campos como Risk reasons, Test evidence e Rollback plan exigem evidência e permitem automação simples.

CI guard com GitHub Actions

O workflow e o script abaixo olham o corpo do PR e os arquivos alterados. Eles não provam que o código está correto, mas impedem review sem contexto mínimo.

name: PR review guard

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

permissions:
  contents: read
  pull-requests: read

jobs:
  review-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Check PR review evidence
        run: node scripts/pr-review-guard.mjs
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";

const eventPath = process.env.GITHUB_EVENT_PATH;
if (!eventPath) throw new Error("GITHUB_EVENT_PATH is missing.");

const event = JSON.parse(readFileSync(eventPath, "utf8"));
const pr = event.pull_request;
const body = pr?.body ?? "";
const base = process.env.BASE_SHA ?? pr?.base?.sha;
const head = process.env.HEAD_SHA ?? pr?.head?.sha;

function safeRef(value, name) {
  if (!value || !/^[a-f0-9]{40}$/i.test(value)) throw new Error(`${name} must be a full git SHA.`);
  return value;
}

const changedFiles = execSync(`git diff --name-only ${safeRef(base, "BASE_SHA")} ${safeRef(head, "HEAD_SHA")}`, {
  encoding: "utf8",
}).split(/\r?\n/).filter(Boolean);

const hasRisk = /Risk level:\s*(low|medium|high)/i.test(body);
const hasTests = /## Test evidence[\s\S]*(Automated|Manual):\s*\S/i.test(body);
const hasRollback = /Rollback plan:\s*\S/i.test(body);
const highRisk = /Risk level:\s*high/i.test(body);
const migrationChanged = changedFiles.some((file) => /migrations?|schema|prisma|drizzle/i.test(file));
const sensitiveChanged = changedFiles.some((file) => /auth|session|permission|billing|payment|webhook/i.test(file));
const failures = [];

if (!hasRisk) failures.push("Add Risk level.");
if (!hasTests) failures.push("Add automated or manual test evidence.");
if ((highRisk || migrationChanged) && !hasRollback) failures.push("Add rollback plan.");
if (sensitiveChanged && !/Security and privacy notes/i.test(body)) failures.push("Add security/privacy notes.");

if (failures.length) {
  console.error("PR review guard failed:");
  for (const failure of failures) console.error(`- ${failure}`);
  process.exit(1);
}

console.log("PR review guard passed.");

Comece em modo informativo. Depois, torne obrigatório em branches protegidas para high risk e migrations. PRs low risk devem continuar rápidos para que o processo seja respeitado.

Segurança, privacidade, testes, performance e acessibilidade

Para segurança, divida a revisão em entrada, autorização, saída, logs e chamadas externas. A validação ocorre no servidor? A autorização fica perto do acesso aos dados? A saída pode gerar XSS? Logs têm dados privados? Um webhook ou URL externa pode virar SSRF ou bypass de assinatura?

Privacidade vai além de secrets. Email, payment ID, endereço, mensagem de contato, analytics ID e conteúdo privado também importam. Não cole API keys reais, emails de clientes, contratos ou IDs de pagamento em prompts. Mascare valores e passe apenas a estrutura.

Em testes, peça evidência. “Works locally” não basta. Um bom PR diz qual teste automático rodou, qual fluxo manual foi verificado e qual foi o resultado. Se não há teste, a justificativa precisa estar no PR.

Em performance, procure loops sem limite, N+1 queries, chamadas repetidas, crescimento de bundle, imagens pesadas e renderização cara no cliente. Um número antes/depois, mesmo simples, melhora a revisão.

Em acessibilidade, não pare em screenshots. Verifique teclado, ordem de foco, foco visível, labels, mensagens de erro, focus trap em modais e reduced motion. UI gerada por Claude Code pode parecer boa e ainda falhar nesses pontos.

Casos de uso práticos

O primeiro caso é auth e telas administrativas. Lista de usuários, mudanças de role e audit logs devem ser protegidos na API ou data layer. Revise autorização, logs com dados pessoais, trilha de auditoria e testes de acesso não autorizado.

O segundo é billing e webhooks. Webhook de pagamento precisa de validação de assinatura, idempotência, retries, segurança contra eventos duplicados, tratamento de cancelamento e logs com privacidade.

O terceiro é database migration. Uma nova coluna pode quebrar produção se versões antigas e novas da aplicação rodarem juntas durante o deploy. Revise defaults, not null, index, backfill, rollback e sequência expand-contract.

O quarto é um diff grande gerado por IA. Quando Claude Code gera páginas, forms, modais ou tabelas, revise remoção acidental de CTA, mudança de analytics event, falhas de acessibilidade, snapshots sem explicação e novas dependências.

O quinto é site de conteúdo com receita. Review de artigo, produto ou lead form também precisa proteger conversão. Se quebrar link paraprodutos, formulário de PDF grátis ou tracking de consulta, é bug de negócio mesmo com a página renderizando.

Armadilhas e CTA

A primeira armadilha é aceitar findings do Claude Code sem verificar. IA pode soar convincente. Compare cada finding com diff, testes, docs oficiais ou reprodução.

A segunda é misturar review e implementação. Peça findings primeiro, aprove must-fix e só então altere. O PR continua legível.

A terceira é deixar passar limpeza não relacionada gerada por IA. Formatação, dependências, config e testes removidos podem se esconder em um diff grande. Peça explicitamente a lista de unrelated changes.

A quarta é tratar rollback de dados como revert de código. Revert não restaura dados apagados. High-risk migration precisa de backup, SQL de recuperação, feature flag ou plano por fases.

Review também protege receita: billing, páginas de produto, PDF grátis, Gumroad, analytics e CTAs de consultoria fazem parte do sistema. Para praticar, comece pelachecklist grátis. Para prompts, templates, CLAUDE.md e CI guard reutilizáveis, vejaprodutos e templates. Para aplicar em repo real, usetreinamento e consultoria.

Testei este formato em três cenários pequenos: mudança UI em Next.js, database migration e diff UI gerado por Claude Code. O maior ganho veio de obrigar Risk level e Rollback plan. Mais checkboxes ajudaram menos do que evidência curta e concreta.

Resumo

Uma checklist de code review com Claude Code não é só um prompt. É um workflow que conecta classificação de risco, evidência no PR, review humano, CI e protected branches.

Comece pequeno: adicione o PR template, rode o guard como aviso e depois torne obrigatório para high-risk. Combine comAI pair programming eCLAUDE.md best practices para deixar o padrão dentro do repositório.