Checklist de review com Claude Code: encontre risco antes de publicar

As primeiras três linhas definem a profundidade do review

Quando um review de Claude Code parece raso, o problema quase nunca é só o modelo. Normalmente faltam escopo, comportamento que não pode quebrar, verificações já executadas e a decisão que o responsável precisa tomar.

Neste artigo, workflow de review é uma sequência repetível: limitar o diff, nomear o risco, anexar evidências, pedir findings primeiro e manter a decisão final com uma pessoa. Para iniciantes, diff é o que mudou no PR, review gate é o controle antes de merge ou publicação, e verification receipt é o registro curto de comandos, resultados, prints, logs e risco restante.

As referências oficiais úteis são Claude Code overview, common workflows, GitHub pull request reviews e npm scripts. No site, combine com a checklist de code review do Claude Code e o verification receipt workflow.

O que preparar antes de entregar o diff

Claude Code encontra mais defeitos quando a entrada traz Scope, Risk, Evidence e Handoff. Sem isso, ele pode produzir um resumo razoável e ainda perder o ponto que deveria bloquear o release.

Entrada	Objetivo	Versão fraca	Versão forte
Scope	Limitar a mudança	Ajustei várias coisas	Só CTA do artigo, texto e espaçamento mobile
Risk	Nomear impacto	Deve estar ok	Produtos, consulta e links internos afetam receita
Evidence	Mostrar verificação	Testei local	npm run build passou e CTA foi testado em 360px
Handoff	Definir saída	Dá uma olhada	Findings P1/P2/P3, risco residual e próximos checks

flowchart LR
  A["Diff"] --> B["Scope and risk"]
  B --> C["Claude Code review"]
  C --> D["Human decision"]
  D --> E["Fix, verify, or ship"]
  E --> F["Review receipt"]

A fronteira principal é simples: Claude Code não aprova o PR. Ele reduz omissões, sugere testes e mostra pressupostos fracos. Corrigir, testar de novo ou publicar continua sendo decisão do dono do PR.

Checklist antes do review

Comece reunindo o estado do repositório e os comandos de verificação. O exemplo é para Node; em outros stacks troque as últimas linhas por pytest, go test ./..., bundle exec rspec ou o comando de CI da equipe.

git status --short
git diff --stat
git diff --name-only
npm run build
npm run test -- --runInBand

Depois coloque esta checklist na descrição do PR, em .github/review-checklist.md ou no wiki da equipe.

# Claude Code Review Checklist

## Scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] No unrelated formatting, dependency, or generated files are mixed in.

## Risk
- [ ] Risk level is marked as low, medium, or high.
- [ ] User-facing routes, forms, auth, billing, analytics, and CTA paths are named.
- [ ] Rollback or recovery steps are written for high-risk changes.

## Evidence
- [ ] Build, test, lint, or typecheck commands are listed with results.
- [ ] Manual checks include browser width, account state, and actual URL when relevant.
- [ ] Screenshots, logs, or console output are attached for UI and integration changes.

## Review output
- [ ] Findings come first, ordered by severity.
- [ ] Each finding has file reference, reproduction condition, and expected fix.
- [ ] Residual risk is written even when no blocker is found.

A checklist existe para procurar risco de publicação, não para pedir uma opinião genérica sobre estilo.

Prompt pronto para usar

O prompt pode ser curto se o contrato de saída for claro. Mantenha bug-finding mindset, findings first e do not rewrite code yet.

Review this diff with a bug-finding mindset.

Scope:
- Only review the files changed in this PR.
- Do not rewrite code yet.

Prioritize:
1. behavioral regressions
2. security, privacy, or permission mistakes
3. missing tests or weak verification
4. broken mobile layout, internal links, product CTA, or training CTA

Return:
- Findings first, ordered by P1/P2/P3 severity
- File and line references when possible
- Why each issue matters to users or revenue
- Checks I should run next
- Residual risk if no blocker is found

A primeira passada deve ser somente review. Se Claude Code começa a editar enquanto revisa, a equipe perde a lista de problemas e a prioridade de cada um.

Quatro usos práticos

O primeiro uso é mudança de CTA ou caminho de receita. Se o rodapé do artigo, card de produto, preço ou link de consultoria mudou, verifique URL de destino, produto correto, ordem dos botões, layout mobile e evento analytics. Um erro comum é o botão dizer “templates” e ainda apontar para um produto Gumroad antigo. O fluxo deve levar de forma coerente a /pt/products/ e /pt/training/.

O segundo uso é autenticação, permissões e dados privados. Esconder botão na UI não é autorização no servidor. Claude Code deve revisar quem pode executar, quem deve ser recusado, se logs expõem email ou payment ID e se há teste para o usuário recusado.

O terceiro uso é publicação multilíngue. Um idioma pode soar natural enquanto outro tem updatedDate antigo, code fence aberto, link de produto ausente ou mojibake. Especifique exatamente quais arquivos locale podem ser tocados e quais metadados devem ser preservados.

O quarto uso é triage de build ou teste. Não cole um log gigante. Entregue comando que falhou, últimas linhas relevantes, diff recente e o que já foi tentado. O perigo é transformar um pequeno fix em atualização de dependências sem relação.

Falhas comuns

“Revise tudo” é amplo demais. Claude Code tende a responder com generalidades. Melhor listar arquivos, riscos e o que está fora do escopo.

Outra falha é falta de evidência. Se não está claro se npm run build, typecheck, fluxo no navegador ou mobile foram verificados, o review vira suposição. Se algo não foi executado, registre o motivo.

Caminhos de receita têm armadilhas próprias: olhar só desktop, não clicar links reais e não confirmar a ordem de /products/ e /training/. Um CTA quebrado nem sempre aparece claramente no diff.

Em segurança, não cole API keys, tokens, emails de clientes, payment IDs ou conteúdo privado no prompt. Reduza logs ao mínimo reproduzível antes de pedir ajuda.

Verificar o receipt com script

Este script Node confirma se o review receipt tem as seções obrigatórias e pelo menos um comando marcado como executado. Não substitui review humana, mas evita publicar sem evidência mínima.

{
  "requiredSections": ["Scope", "Risk", "Checks run", "Findings", "Residual risk"]
}

#!/usr/bin/env node
const fs = require("node:fs");

const receiptPath = process.argv[2] || "review-receipt.md";
const policyPath = process.argv[3] || "review-policy.json";
const receipt = fs.readFileSync(receiptPath, "utf8");
const policy = fs.existsSync(policyPath)
  ? JSON.parse(fs.readFileSync(policyPath, "utf8"))
  : { requiredSections: ["Scope", "Risk", "Checks run", "Findings", "Residual risk"] };

const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const missingSections = policy.requiredSections.filter((name) => {
  const heading = new RegExp(`^## ${escapeRegExp(name)}\\b`, "m");
  return !heading.test(receipt);
});

const hasCheckedCommand = /^- \[(x|X)\] `(npm|pnpm|yarn|node|pytest|go test|cargo test)/m.test(receipt);

if (missingSections.length || !hasCheckedCommand) {
  for (const section of missingSections) console.error(`Missing section: ${section}`);
  if (!hasCheckedCommand) console.error("Missing checked command evidence such as - [x] `npm run build`");
  process.exit(1);
}

console.log("Review receipt passed.");

# Review receipt

## Scope
Article CTA links and mobile layout only.

## Risk
Medium: product and training links affect revenue.

## Checks run
- [x] `npm run build` passed
- [x] mobile CTA path checked at 360px

## Findings
- P2: Product CTA text and destination mismatch on one locale.

## Residual risk
Analytics event names were not checked in production.

A mesma ideia pode virar template de PR, prompt do Claude Code ou check leve no CI.

Próximo passo

Para trabalhar sozinho, comece com o cheatsheet gratuito de Claude Code e estabilize comandos e prompts seguros. Se você reescreve sempre os mesmos prompts de review, debugging e triage, use Prompt Templates e /pt/products/.

Para equipes, o problema real não é um prompt inteligente. É combinar CLAUDE.md, permissões, review gates, verification receipts e responsabilidade de aprovação. Para adaptar o fluxo a um repositório real, use /pt/training/.