Checklist de review con Claude Code: detectar riesgo antes de publicar

Las primeras tres líneas definen la profundidad del review

Cuando una review de Claude Code parece superficial, el problema no suele ser solo el modelo. Casi siempre falta contexto: qué cambió, qué no puede romperse, qué pruebas se ejecutaron y qué decisión debe tomar la persona responsable.

En este artículo, workflow de review significa una secuencia repetible: limitar el diff, nombrar el riesgo, adjuntar evidencia, pedir findings primero y dejar la decisión final en manos humanas. Para principiantes: diff es lo que cambió en el PR, review gate es el control antes de merge o publicación, y verification receipt es el registro breve de comandos, capturas, logs y riesgo restante.

Para la base oficial, revisa Claude Code overview, common workflows, GitHub pull request reviews y npm scripts. Dentro del sitio, combínalo con Claude Code code review checklist y verification receipt workflow.

Qué preparar antes de dar el diff a Claude Code

Claude Code funciona mejor cuando recibe cuatro piezas: Scope, Risk, Evidence y Handoff. Sin ellas, puede escribir una síntesis razonable y aun así saltarse el problema que bloquea el release.

Entrada	Objetivo	Versión débil	Versión fuerte
Scope	Limitar el cambio	Arreglé varias cosas	Solo CTA del artículo, copy y espaciado móvil
Risk	Nombrar impacto	Debería estar bien	Productos, consulta e internos afectan ingresos
Evidence	Mostrar verificación	Funciona local	npm run build pasó y el CTA se probó a 360px
Handoff	Definir salida	Revisa por favor	Devuelve findings P1/P2/P3, riesgo residual y 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"]

La frontera importante es que Claude Code no aprueba el PR. Ayuda a reducir omisiones, sugiere pruebas y detecta supuestos débiles. La decisión de corregir, verificar de nuevo o publicar sigue siendo del owner.

Checklist antes del review

Empieza reuniendo el estado del árbol de trabajo y los comandos de verificación. Este ejemplo es para un proyecto Node; en otros stacks cambia las últimas líneas por pytest, go test ./... o el comando real de CI.

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

Después pega esta checklist en la descripción del PR, .github/review-checklist.md o una wiki del equipo.

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

La checklist existe para buscar riesgo de publicación, no para pedir una opinión estética sobre el código.

Prompt listo para usar

El prompt puede ser corto si el contrato de salida es estricto. Mantén bug-finding mindset, findings first y 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

Separar review y corrección evita perder el razonamiento. Primero acepta o descarta los findings; después abre una tarea de fix.

Cuatro casos de uso prácticos

El primer caso es un cambio de CTA o ruta de ingresos. Si cambia el footer del artículo, un bloque de productos, precios o consulta, revisa URL destino, producto asociado, orden de botones, layout móvil y evento analytics. Un fallo típico es que el botón diga “templates” pero siga apuntando a un producto viejo. La ruta debería llevar de forma coherente a /es/products/ y /es/training/.

El segundo caso es autenticación, permisos o datos privados. Ocultar un botón en UI no equivale a autorización en servidor. Claude Code debe revisar quién puede ejecutar la acción, quién debe ser rechazado, si logs exponen email o payment ID y si hay pruebas del caso denegado.

El tercer caso es publicación multilingüe. Un idioma puede sonar natural mientras otro conserva updatedDate antiguo, un code fence abierto, un enlace de producto faltante o mojibake. Indica exactamente qué archivos locale se pueden tocar y qué metadata debe conservarse.

El cuarto caso es triage de build o tests. No pegues un log enorme. Entrega comando fallido, últimas líneas relevantes, diff previo y lo que ya probaste. El riesgo común es convertir un fix pequeño en actualización de dependencias o refactor sin relación.

Fallos frecuentes

“Revisa todo” es una mala petición. El alcance amplio empuja a Claude Code hacia generalidades. Es mejor listar archivos, riesgos y exclusiones.

Otro fallo es no aportar evidencia. Si no se sabe si pasaron npm run build, typecheck, navegador o móvil, el review adivina. Si no ejecutaste algo, dilo con la razón.

Las rutas de ingresos tienen trampas propias: comprobar solo desktop, no hacer clic en enlaces reales y no validar el orden de /products/ y /training/. Un CTA roto no siempre aparece en el diff.

En seguridad, no pegues API keys, tokens, emails de clientes, payment IDs ni contenido privado. Reduce el log al mínimo reproducible antes de pedir ayuda.

Verificar el receipt con un script

Este script Node comprueba que el review receipt tenga secciones mínimas y al menos un comando marcado como ejecutado. No sustituye a una review humana, pero evita publicar sin evidencia.

{
  "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.

Puedes llevar la misma idea a una plantilla de PR, a un prompt de Claude Code o a un check ligero de CI.

Siguiente paso

Si trabajas solo, empieza con el cheatsheet gratuito de Claude Code para fijar comandos y prompts seguros. Si reescribes siempre los mismos prompts de review, debugging y triage, usa Prompt Templates y la página /es/products/.

En equipos, el reto no es un prompt brillante, sino acordar CLAUDE.md, permisos, review gates, verification receipts y responsabilidad de aprobación. Para adaptarlo a un repositorio real, usa /es/training/.