Checklist de Code Review con Claude Code para Equipos

Empieza por el riesgo, no por “review this”

Si le dices a Claude Code “revisa este PR”, normalmente recibirás comentarios útiles, pero demasiado genéricos.

En un equipo, la revisión debe empezar por preguntas más duras: qué puede romperse, qué datos toca el cambio, qué evidencia de pruebas existe y qué debe bloquearse antes del merge.

Esta guía reúne una checklist copiable, un prompt de revisión para Claude Code, una plantilla de pull request en GitHub y un guard de CI con GitHub Actions.

Claude Code no sustituye la responsabilidad humana. Sirve para reducir omisiones y hacer más consistente el criterio del equipo. Para los detalles oficiales, revisa la guía de Claude Code sobrecode review setup, la documentación deClaude Code GitHub Actions, GitHub sobreplantillas de PR, protected branches yActions workflows. Para seguridad, usa como referencia laOWASP Secure Code Review Cheat Sheet.

Qué significa revisar por riesgo

Revisar por riesgo significa no aplicar el mismo proceso a todos los PR. Un cambio de copy, un ajuste de CSS, un webhook de pagos y una migración destructiva no tienen el mismo impacto. Si todo se revisa con demasiada carga, los cambios pequeños se vuelven lentos. Si todo se revisa de forma ligera, los cambios peligrosos pasan sin suficiente atención.

Una clasificación simple funciona bien:

Riesgo	Ejemplos	Revisión requerida
Low	Copy, CSS simple, docs, texto de logs	Un reviewer, resumen claro, captura o explicación del diff
Medium	Formularios, estado de UI, búsqueda, forma de respuesta API, lecturas de datos	Un reviewer, evidencia de pruebas, revisión con Claude Code
High	Auth, autorización, billing, datos personales, migraciones, deletes, webhooks	Dos reviewers, plan de rollback, CI obligatorio, revisión de seguridad/privacidad

Una migration es un cambio en la estructura o forma de los datos. El código suele revertirse con un commit, pero una columna eliminada, registros reescritos o un backfill fallido no se recuperan tan fácil. Por eso, en migraciones la primera pregunta es “cómo volvemos atrás”, no “si el código está limpio”.

Cuando uses Claude Code, declara el nivel de riesgo. Un prompt vago suele producir comentarios de estilo. Un prompt como “High risk: billing webhook and customer email changed” enfoca la revisión en validación de firmas, idempotencia, reintentos, privacidad, logs y evidencia de tests.

En las notas de trabajo de Masa, el fallo más repetido era usar palabras abstractas como “calidad”, “seguridad” o “mantenibilidad” sin exigir evidencia. Son buenos títulos, pero malas preguntas. Una plantilla útil obliga a escribir archivos tocados, datos afectados, motivos de riesgo, pruebas y rollback.

Checklist copiable para review

Puedes guardar esto en .github/review-checklist.md, en la wiki del equipo o en la sección de review de CLAUDE.md. Está escrito de forma concreta para que humanos y Claude Code revisen hechos observables.

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

La clave es que cada punto sea verificable. “Se revisó seguridad” es débil. “Los logs no incluyen emails, tokens, direcciones, payment IDs ni contenido privado” sí se puede comprobar. “La accesibilidad está bien” es débil. “Funciona con teclado, el foco es visible y los errores tienen texto comprensible” es una pregunta real de review.

Prompt para Claude Code

El prompt debe dar rol, contexto, riesgo y una regla clara: primero findings, no reescritura. Así evitas mezclar revisión con implementación. Si Claude empieza a corregir antes de que el equipo acepte los hallazgos, el PR crece y se vuelve más difícil de revisar.

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.

Combina bien concodebase navigation y con una buenaestrategia de testing. Antes de pedir la revisión, puedes pedirle a Claude Code que explique en pocos minutos el dominio tocado por el PR. Esa orientación evita que la revisión se limite a nombres y formato.

Plantilla de pull request en GitHub

Con .github/pull_request_template.md, GitHub rellena el cuerpo del PR al crearlo. El objetivo no es burocracia, sino reunir en un sitio la evidencia que necesitan reviewers, Claude Code y 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.

Evita una plantilla que solo sea una pared de checkboxes. La gente aprende a marcarlas sin pensar. Campos como Risk reasons, Test evidence y Rollback plan piden evidencia y permiten automatizar controles básicos.

CI guard con GitHub Actions

Este workflow y script de Node revisan el cuerpo del PR y los archivos modificados. No demuestran que el código sea correcto, pero sí evitan que falten los datos mínimos antes de que un reviewer lea el diff.

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.");

Primero ejecútalo en modo informativo. Después, conviértelo en required check para ramas protegidas y cambios de alto riesgo. Si lo haces demasiado estricto desde el primer día, el equipo acabará escribiendo evidencia falsa para desbloquear PRs pequeños.

Seguridad, privacidad, pruebas, rendimiento y accesibilidad

Para seguridad, divide la revisión en entrada, autorización, salida, logs y llamadas externas. ¿La validación ocurre en servidor? ¿La autorización está cerca del acceso a datos y no solo en la UI? ¿La salida puede generar XSS? ¿Los logs contienen datos privados? ¿Un webhook o URL externa puede convertirse en SSRF o bypass de firma?

Privacidad no significa solo secrets. Emails, payment IDs, direcciones, mensajes de contacto, identificadores de analytics y contenido privado también importan. No pegues API keys reales, emails de clientes, contratos o IDs de pago en prompts. Enmascara valores y da a Claude Code la estructura.

En pruebas, exige evidencia. “Works locally” no basta. Un PR útil dice qué test automático corrió, qué flujo manual se verificó y cuál fue el resultado. Si no hay test, debe explicar por qué.

En rendimiento, pide revisar bucles sin límite, N+1 queries, llamadas repetidas, tamaño de bundle, imágenes pesadas y renderizado caro en cliente. Un número antes/después, aunque sea simple, mejora mucho la revisión.

En accesibilidad, no te quedes en screenshots. Revisa teclado, orden de foco, foco visible, labels, mensajes de error, focus trap en diálogos y reduced motion. La UI generada por Claude Code puede verse bien y aun así fallar ahí.

Casos de uso reales

El primer caso es auth y pantallas de administración. Listas de usuarios, cambios de roles y audit logs deben protegerse en API o data layer. Revisa autorización, logs con datos personales, evidencia de auditoría y tests de acceso no autorizado.

El segundo caso es billing y webhooks. Un webhook de pago necesita validación de firma, idempotencia, manejo de reintentos, seguridad ante eventos duplicados, estados de cancelación y logs sin datos privados.

El tercer caso es database migration. Una columna nueva puede romper producción si versiones antiguas y nuevas de la app conviven durante el despliegue. Revisa defaults, not null, índices, backfill, rollback y estrategia expand-contract.

El cuarto caso es un diff grande generado por IA. Cuando Claude Code genera páginas, formularios, modales o tablas, revisa eliminación accidental de CTAs, cambios en eventos de analytics, gaps de accesibilidad, snapshots sin explicación y dependencias nuevas.

El quinto caso es un sitio de contenido con ingresos. Un review de página de artículo, producto o lead form también debe proteger la conversión. Si se rompe el enlace aproductos, el formulario de PDF gratis o el tracking de consulta, es un bug de negocio aunque la página cargue.

Trampas comunes y CTA

La primera trampa es aceptar findings de Claude Code sin verificar. La IA puede sonar convincente. Contrasta cada finding con el diff, tests, docs oficiales o una reproducción.

La segunda es mezclar review e implementación. Pide findings primero, acepta los must-fix y solo entonces corrige. Mantiene el PR entendible.

La tercera es permitir limpieza no relacionada generada por IA. Formato, dependencias, config y tests borrados pueden ocultarse en un diff grande. Pide explícitamente una lista de cambios no relacionados.

La cuarta es confundir rollback de base de datos con revert de código. Un revert no recupera datos eliminados. Un high-risk migration necesita backup, SQL de recuperación, feature flag o plan por fases.

La revisión también protege ingresos: billing, páginas de producto, PDF gratis, Gumroad, analytics y CTAs de consulta son parte del sistema. Para practicar, empieza con lachecklist gratis. Para plantillas, prompts, CLAUDE.md y CI guard reutilizables, revisaproductos y templates. Para rollout en un repo real, usaformación y consultoría.

Probé esta estructura con tres escenarios pequeños: cambio UI en Next.js, migration de base de datos y diff UI generado por Claude Code. Lo que más ayudó fue obligar Risk level y Rollback plan en el PR. Más checkboxes no mejoraron la revisión; evidencia breve y concreta sí.

Resumen

Una checklist de code review con Claude Code no es solo un prompt. Es un flujo de equipo que conecta clasificación de riesgo, evidencia en PR, revisión humana, CI y protected branches.

Empieza pequeño: añade la plantilla de PR, ejecuta el guard como aviso y luego hazlo obligatorio para cambios high-risk. Combínalo conAI pair programming yCLAUDE.md best practices para que el estándar viva en el repositorio.