Code review con Claude Code para equipos

Claude Code aporta más valor en code review cuando forma parte de un flujo repetible, no cuando se usa como una segunda opinión improvisada. Su papel es ordenar el PR, señalar zonas de riesgo, pedir aclaraciones y dejar que los revisores humanos se concentren en arquitectura, intención de producto y responsabilidad de ownership.

Para un equipo, el flujo práctico combina una plantilla de PR, reglas en CLAUDE.md, un gate de tamaño de diff, GitHub Actions, CODEOWNERS y un prompt que exige evidencia. Ten abiertas las referencias oficiales: Claude Code common workflows, documentación de pull requests de GitHub, CODEOWNERS, GitHub Actions workflow syntax y OWASP Code Review Guide.

Sistema de revisión

Una revisión basada en riesgo no mira todas las líneas con la misma intensidad. Autenticación, autorización, pagos, migraciones, rendimiento y cobertura de tests requieren más atención. Diff scope significa “lo que cambió en este PR”. Un CI gate es una verificación automática que puede bloquear o advertir. Un hallucinated finding es un hallazgo de IA que suena posible, pero no tiene evidencia en el 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"]

La regla central: Claude Code no debe reescribir código en silencio durante una revisión. Si la intención de negocio, el contrato de datos o la política de permisos no están claros, debe preguntar.

Casos reales

Primer caso: cambios de autenticación y autorización. En login, sesiones, roles, paneles admin y API keys, pide a Claude Code revisar falta de autorización, escalada de privilegios, filtración de secretos y ausencia de audit log. La decisión de negocio sigue siendo humana. Para profundizar, consulta auditorías de seguridad con Claude Code.

Segundo caso: cambios sensibles a rendimiento. Búsqueda, listados, cachés, imágenes y jobs batch pueden esconder consultas N+1, renders repetidos, claves de caché incorrectas y payloads grandes. Un buen comentario debe explicar con qué tamaño de entrada aparece el problema y cómo medirlo.

Tercer caso: tests y migraciones. Cambios de schema, migrations, seeds, validación y backfills necesitan revisar rollback, datos existentes, campos nullable, unique constraints y reintentos. Claude Code puede listar tests faltantes y casos límite antes de que el responsable de datos revise.

Cuarto caso: PR demasiado grandes. Cuando el diff supera 800 o 1000 líneas, la revisión pierde calidad. CI puede advertir o bloquear, y Claude Code puede proponer una división por comportamiento, migración, UI y tests.

Plantilla de PR

Crea .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

La frase diff scope only evita comentarios genéricos sobre todo el repositorio. El review debe mejorar este PR, no reabrir debates antiguos.

Reglas en CLAUDE.md

Añade reglas de revisión en CLAUDE.md. Es la memoria local que Claude Code usa para entender las normas del proyecto. Para un enfoque más amplio, revisa buenas prácticas 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

La regla de evidencia reduce muchos falsos positivos. Si no hay archivo, línea y motivo, el punto debe pasar a preguntas.

Script de gate de diff

Guárdalo 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.`);

Ejecución local:

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

GitHub Actions y CODEOWNERS

Añade .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

Luego enruta áreas críticas con .github/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

No hagas que la salida de IA sea el primer bloqueo fuerte de merge. Estabiliza lint, typecheck, tests y tamaño de diff. Para más contexto, revisa la guía de CI/CD y la guía de calidad de pull requests.

Prompt de revisión

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

Errores comunes y verificación

El primer error es pedir “revísalo y arréglalo todo”. Eso aumenta el diff antes de validar los hallazgos. Primero revisión, luego selección humana de fixes, después tests.

El segundo error es aceptar hallazgos sin evidencia. Si Claude Code no puede señalar archivo, línea y comportamiento modificado, debe formular una pregunta.

El tercer error es subestimar migrations. Tests verdes no garantizan datos de producción seguros. Revisa NULL existentes, duplicados, locks, backfills y límites de rollback.

Probé estos ejemplos como flujo mínimo de repositorio: el script necesita Git y Node 22, la Action ejecuta el mismo script, y la plantilla mantiene a Claude Code dentro del diff. En un equipo real, empezaría una semana en modo warning, ajustaría umbrales y luego haría obligatorios solo los checks confiables. Como siguiente paso, usa la checklist de review gate antes de commit.