Code review com Claude Code para equipes

Claude Code ajuda mais no code review quando vira um fluxo repetível, não quando funciona como uma segunda opinião solta. O papel dele é organizar o PR, destacar áreas de risco, fazer perguntas melhores e deixar os revisores humanos focarem em arquitetura, intenção de produto e ownership.

Para uma equipe, o fluxo prático combina template de PR, regras em CLAUDE.md, gate de tamanho de diff, GitHub Actions, CODEOWNERS e um prompt que exige evidência. Consulte também as fontes oficiais: Claude Code common workflows, documentação de pull requests do GitHub, CODEOWNERS, GitHub Actions workflow syntax e OWASP Code Review Guide.

Sistema de review

Review baseado em risco significa não revisar todas as linhas com a mesma intensidade. Autenticação, autorização, pagamentos, migração de dados, performance e testes ausentes merecem mais atenção. Diff scope é o escopo realmente alterado pelo PR. CI gate é uma verificação automática que alerta ou bloqueia. Hallucinated finding é um apontamento de IA que parece plausível, mas não tem evidência no diff.

flowchart LR
  A["PR template"] --> B["Diff size gate"]
  B --> C["Claude Code review"]
  C --> D["Code owner review"]
  D --> E["CI tests and merge"]
  C --> F["Questions before fixes"]

A regra central é simples: Claude Code não deve reescrever código em silêncio durante o review. Se a intenção de negócio, o contrato de dados ou a regra de permissão não estão claros, ele deve perguntar.

Casos reais

Primeiro caso: autenticação e autorização. Em login, sessões, roles, admin e API keys, peça para Claude Code revisar autorização ausente, escalada de privilégio, vazamento de secrets e audit logs ausentes. A regra de negócio continua sendo decisão humana. Para aprofundar, veja auditoria de segurança com Claude Code.

Segundo caso: mudanças sensíveis a performance. Busca, listas, cache, imagens e jobs batch podem esconder consultas N+1, renders repetidos, chaves de cache erradas e payloads grandes. Um bom comentário diz qual tamanho de entrada importa e como medir.

Terceiro caso: testes e migrações. Schema, migrations, seeds, validação e backfills exigem rollback, dados existentes, campos nullable, unique constraints e comportamento após falha. Claude Code pode listar testes ausentes e riscos antes da revisão do responsável por dados.

Quarto caso: PRs grandes demais. Acima de 800 a 1000 linhas alteradas, a qualidade do review cai. O CI pode alertar ou bloquear, e Claude Code pode sugerir divisão por comportamento, migration, UI e testes.

Template de PR

Crie .github/pull_request_template.md.

## Change summary
- What changed:
- Why it changed:
- User-visible impact:

## Risk review
- [ ] Security impact checked
- [ ] Performance impact checked
- [ ] Test coverage added or explained
- [ ] Data migration or rollback plan checked
- [ ] No secrets, tokens, or personal data included

## Claude Code review request
Please review this PR by diff scope only.

Focus on:
- Security: auth, authorization, injection, secret leakage
- Performance: N+1 queries, cache keys, unnecessary work
- Tests: missing unit, integration, and migration tests
- Data: schema changes, rollback, backfill safety

For each finding, include:
- file and line
- why it matters
- evidence from the diff
- suggested fix or question for the author

diff scope only evita comentários genéricos sobre todo o repositório. O review precisa melhorar este PR.

Regras em CLAUDE.md

Coloque as regras de review em CLAUDE.md. Esse arquivo funciona como memória local do projeto para Claude Code. Para uma estrutura completa, leia boas práticas de CLAUDE.md.

## Code review rules

Review only the current diff unless the user asks for wider context.

Severity:
- Must fix: security bug, data loss, broken build, failed test, migration risk
- Should fix: likely production bug, missing important test, measurable performance issue
- Nice to have: naming, small cleanup, optional refactor

Evidence rule:
- Every finding must cite a file and line.
- If the evidence is uncertain, ask a question instead of asserting a bug.
- Do not invent dependencies, routes, database columns, or team policies.

Security checks:
- Authentication and authorization
- SQL or command injection
- XSS and unsafe HTML
- Secret leakage
- Missing audit log for privileged actions

Data checks:
- Migration rollback path
- Backfill failure behavior
- Existing nullable and unique constraints
- PII handling and retention

A regra de evidência é o que impede boa parte dos falsos positivos. Sem arquivo, linha e motivo, o item deve virar pergunta.

Script de diff gate

Salve como scripts/review-diff-gate.mjs.

#!/usr/bin/env node
import { execSync } from "node:child_process";

const baseRef = process.env.BASE_REF || "origin/main";
const maxFiles = Number(process.env.MAX_REVIEW_FILES || 25);
const maxLines = Number(process.env.MAX_REVIEW_LINES || 800);

function git(command) {
  return execSync(command, { encoding: "utf8" }).trim();
}

const files = git(`git diff --name-only ${baseRef}...HEAD`)
  .split(/\r?\n/)
  .filter(Boolean);

const numstat = git(`git diff --numstat ${baseRef}...HEAD`);
const changedLines = numstat
  .split(/\r?\n/)
  .filter(Boolean)
  .reduce((total, line) => {
    const [added, deleted] = line.split(/\s+/);
    return total + (Number(added) || 0) + (Number(deleted) || 0);
  }, 0);

const riskyPatterns = [
  /^src\/auth\//,
  /^src\/billing\//,
  /^db\/migrations\//,
  /^infra\//,
  /^\.github\/workflows\//,
];

const riskyFiles = files.filter((file) =>
  riskyPatterns.some((pattern) => pattern.test(file))
);

let failed = false;

if (files.length > maxFiles) {
  console.error(`Too many files changed: ${files.length} > ${maxFiles}`);
  failed = true;
}

if (changedLines > maxLines) {
  console.error(`Too many changed lines: ${changedLines} > ${maxLines}`);
  failed = true;
}

if (riskyFiles.length > 0) {
  console.log("Risk-sensitive files changed:");
  for (const file of riskyFiles) console.log(`- ${file}`);
}

if (failed) {
  console.error("Split the PR or add a reviewer-approved exception.");
  process.exit(1);
}

console.log(`Review gate passed: ${files.length} files, ${changedLines} lines.`);

Execute localmente:

BASE_REF=origin/main MAX_REVIEW_FILES=25 MAX_REVIEW_LINES=800 node scripts/review-diff-gate.mjs

GitHub Actions e CODEOWNERS

Adicione .github/workflows/review-gate.yml.

name: review-gate

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

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

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

      - name: Run diff size gate
        env:
          BASE_REF: origin/${{ github.base_ref }}
          MAX_REVIEW_FILES: "25"
          MAX_REVIEW_LINES: "800"
        run: node scripts/review-diff-gate.mjs

Depois, encaminhe áreas críticas com CODEOWNERS.

# .github/CODEOWNERS
/src/auth/ @example-org/security
/src/billing/ @example-org/payments
/db/migrations/ @example-org/backend-leads
/.github/workflows/ @example-org/platform
/infra/ @example-org/platform

Não coloque a saída da IA como o primeiro bloqueio rígido de merge. Estabilize lint, typecheck, testes e tamanho de diff. Para evoluir, leia o guia de CI/CD e qualidade de pull requests.

Prompt de review

Review the current PR diff against main.

Rules:
1. Stay inside the diff scope unless a referenced file is required.
2. Do not rewrite code silently.
3. For each finding, include file, line, severity, evidence, and suggested action.
4. If business intent or data contract is unclear, ask a question instead of guessing.
5. Ignore style-only preferences unless they break CLAUDE.md or project conventions.

Focus areas:
- Security: auth, authorization, injection, XSS, secrets, audit logs
- Performance: N+1 queries, cache invalidation, repeated rendering, large payloads
- Tests: missing coverage for changed behavior, migrations, and edge cases
- Data migration: rollback, backfill, nullable fields, unique constraints
- CI and ownership: required checks, CODEOWNERS, risky paths

Output:
## Must fix
## Should fix
## Questions
## No issue found in

Armadilhas e verificação

A primeira armadilha é pedir para Claude Code revisar e corrigir tudo de uma vez. Isso aumenta o diff antes de validar os achados. Primeiro revise, depois escolha os fixes, por fim rode os testes.

A segunda é aceitar achados sem evidência. Se Claude Code não cita arquivo, linha e comportamento alterado, trate como pergunta.

A terceira é subestimar migrations. Testes verdes não provam que dados de produção estão seguros. Verifique NULLs existentes, duplicados, locks, rollback e reexecução de backfill.

Eu validei os exemplos como fluxo mínimo: o script depende de Git e Node 22, a Action executa o mesmo script, e os templates mantêm Claude Code preso ao diff. Em uma equipe real, começaria uma semana em modo warning, ajustaria limites e só depois tornaria obrigatórios os checks confiáveis. Próximo passo: use a checklist de review gate antes do commit.