Usa Claude Code Review como control de pull requests con CLAUDE.md y REVIEW.md

Anthropic lanzó Code Review para Claude Code el 9 de marzo de 2026, con una cifra que debería hacer torcer el gesto a cualquier responsable de ingeniería: dentro de Anthropic, la producción de código por ingeniero había crecido un 200% en un año, y la revisión se convirtió en el cuello de botella (Anthropic). Esa es la historia de verdad. La programación con AI no eliminó el trabajo de revisión. Cambió el punto de presión.

La respuesta útil no es “dejemos que Claude apruebe sus propios deberes”. Así es como acabas con una fábrica de bugs muy educada. La respuesta útil es convertir Claude Code Review en un control de PR repetible, con reglas en las que tu equipo realmente crea.

La documentación de configuración de Anthropic ya hace que esto sea práctico. Un reviewer puede disparar una revisión comentando @claude review, y Code Review lee los archivos CLAUDE.md del repositorio además de un REVIEW.md en la raíz. Las infracciones de CLAUDE.md se tratan como hallazgos de nivel nit, y Claude incluso puede señalar un PR que deje CLAUDE.md obsoleto (Claude Help Center). REVIEW.md es donde pones reglas solo para revisión, incluido el ejemplo que da Anthropic: “toda nueva ruta API debe tener una prueba de integración”.

Esa frase es la bisagra. Deja de pedir a los reviewers de AI que “tengan cuidado”. Empieza a darles la ley del repo.

Un boceto de flujo que muestra un diff de pull request entrando en Claude Code Review, dividiéndose en agentes de revisión paralelos, comprobando C

El problema: la AI hizo más ruidosa la revisión de PRs

La discusión en la comunidad es confusa porque ambos lados tienen razón.

En el hilo de Hacker News sobre Claude Code Review, los desarrolladores cuestionaron el precio, el valor y el hecho incómodo de que un proveedor de AI venda un reviewer para código generado por AI. Un comentarista señaló las propias cifras de Anthropic sobre PRs grandes y las leyó como una señal de alarma sobre la calidad del desarrollo agentic, mientras otros defendían que un segundo par de ojos profundo es justo donde la herramienta se gana el sueldo (Hacker News).

Reddit tiene la versión más práctica del mismo debate. En un hilo, un desarrollador preguntó si la gente realmente confía lo suficiente en el código generado por Claude como para saltarse la revisión, porque Claude a veces escribe código que no entienden. Las respuestas fueron directas: revísalo, valídalo, mantén los cambios pequeños y no finjas que delegar hace desaparecer la responsabilidad (Reddit). En otro hilo, la gente debatió usar agentes de AI separados para revisar la salida de Claude, pero aun así contrastando la propia revisión contra el codebase (Reddit).

Mi postura: usar Claude para revisar código escrito por Claude está bien si no lo tratas como juicio independiente. Trátalo como un reviewer junior muy rápido, muy literal, con muchísimo contexto y cero ownership. Debería pillar omisiones aburridas, inconsistencias entre archivos, tests que faltan, meteduras de pata de seguridad, docs obsoletas y sitios donde un reviewer humano probablemente pasaría por encima.

No debería ser quien dé la aprobación final.

Anthropic lo dice directamente. Code Review no aprueba PRs ni los bloquea por sí solo. Los flujos de revisión existentes se mantienen intactos (Claude Help Center). Así que el “control” es un control del equipo: no hay aprobación humana hasta que Claude haya corrido, los hallazgos Important estén resueltos o eximidos explícitamente, y el autor del PR haya abordado las reglas específicas del repo.

Eso es aburrido. Bien. Los controles aburridos evitan incidentes.

La configuración: dos archivos Markdown, dos trabajos

Claude Code Review tiene dos superficies de memoria que importan.

CLAUDE.md es contexto compartido del proyecto. Aplica a las sesiones de Claude Code en general, no solo a la revisión. Anthropic recomienda usarlo para comandos, convenciones, notas breves de arquitectura, restricciones duras y trampas conocidas. También recomiendan mantenerlo denso en señal, aproximadamente por debajo de 200 líneas, porque se carga en el contexto, aunque el prompt caching reduzca el coste repetido de tokens en sesiones Enterprise (Claude Help Center).

REVIEW.md es distinto. Vive en la raíz del repositorio y es solo para revisión. La documentación de Code Review de Anthropic dice que su contenido se inyecta en cada agente de revisión como instrucciones de alta prioridad, y que es el lugar para controlar severidad, volumen de nits, reglas de exclusión, comprobaciones específicas del repo, estándares de verificación y comportamiento de rerevisión (Claude Code Docs).

Este es el reparto que uso:

Archivo	Propósito	Buenas reglas	Malas reglas
`CLAUDE.md`	Memoria del proyecto para todo el trabajo con Claude	Comandos de build, arquitectura, “usa Zod para validar requests”	Historias largas, preferencias vagas, documentación API duplicada
`REVIEW.md`	Política de revisión de PRs	“Las nuevas rutas API requieren tests de integración”	Consejos genéricos tipo “escribe código limpio”
Config de CI	Enforcement determinista	Typecheck, tests unitarios, lint, comprobaciones de migraciones	Comprobaciones solo con LLM para cosas que un compilador puede demostrar

Pon el contexto estable en CLAUDE.md. Pon la presión de revisión en REVIEW.md. Pon cualquier cosa determinista en CI.

Una tabla comparativa compacta con tres columnas etiquetadas CLAUDE.md, REVIEW.md y CI, que muestra reglas de contexto, revisión

Un control real para rutas API

Supón que un equipo de backend sigue enviando rutas con tests unitarios del camino feliz, pero sin cobertura de integración. Los reviewers humanos lo pillan a veces. Los PRs generados por Claude lo empeoran porque el agente es bueno produciendo código de handlers plausible y malo recordando cicatrices de revisión específicas del equipo.

Empieza con CLAUDE.md:

# Project conventions

- API routes live in `src/routes`.
- Integration tests live in `tests/integration`.
- Use `requireAuth()` on non-public routes.
- Validate request bodies with Zod schemas from `src/schemas`.
- Run `pnpm test:integration` before marking API work complete.

Luego añade un REVIEW.md en la raíz:

# Code Review Rules

Treat these as Important unless stated otherwise.

## API routes

If a PR adds or changes a file under `src/routes/**`:
- Flag missing integration test coverage in `tests/integration/**`.
- Flag routes without explicit auth, unless the route is listed as public.
- Flag request bodies that are not validated with a Zod schema.

Do not accept unit tests as a substitute for route-level integration tests.

## Evidence bar

For every Important finding, cite the changed file and the missing or conflicting evidence.
If the claim depends on a convention, cite this REVIEW.md rule.

Esa última sección importa. Los reviewers LLM pueden producir tonterías con mucha seguridad. Exigir evidencia fuerza a que la revisión ate un hallazgo a un archivo, una línea o una política explícita. No eliminará los falsos positivos, pero cambia la forma de la revisión de “vibras” a “enséñamelo”.

Ahora un PR añade:

// src/routes/billing.ts
router.post("/billing/plan", async (req, res) => {
  const result = await updatePlan(req.body.planId);
  res.json(result);
});

Un buen comentario de Claude Code Review debería decir algo así:

Important: src/routes/billing.ts adds a new POST route without visible auth.
Important: request body reads req.body.planId without schema validation.
Important: no matching integration test was added under tests/integration/**.

El reviewer humano sigue decidiendo. Quizá el router tenga middleware de auth aplicado más arriba. Quizá el test de integración viva en una suite de contratos generada. Perfecto. El control hizo su trabajo si forzó esa conversación antes del merge.

Cómo dispararlo sin quemar dinero

Anthropic ofrece tres modos de disparo para repositorios: una vez tras crear el PR, después de cada push o manual. Manual significa que no hay coste hasta que alguien comenta @claude review; después de eso, los pushes adicionales disparan revisiones automáticamente para ese PR (Claude Help Center).

Para la mayoría de equipos, yo no empezaría con “después de cada push”. Anthropic dice que Code Review tarda de media unos 20 minutos y suele costar entre 15 y 25 dólares por revisión, escalando con el tamaño y la complejidad del PR (Anthropic). Eso es barato comparado con un incidente en producción. Es caro comparado con ejecutar ESLint.

Usa un control por niveles:

Todo PR ejecuta la CI normal.
Los PRs arriesgados reciben @claude review.
Los PRs grandes, cambios de auth, cambios de pagos, migraciones y cambios en API públicas requieren revisión de Claude antes de la aprobación humana.
Repite la revisión de Claude tras cambios importantes, no después de cada corrección tipográfica.
Los humanos son dueños de la aprobación final.

Una checklist ligera de PR en GitHub hace explícito el control:

## AI Review Gate

- [ ] CI is green.
- [ ] `@claude review` has run, or this PR is exempt.
- [ ] Important findings are fixed or explained.
- [ ] If this PR changes conventions, `CLAUDE.md` is updated.
- [ ] If this PR changes review policy, `REVIEW.md` is updated.

Si prefieres ejecutar Claude dentro de tu propio workflow, la documentación de GitHub Actions de Anthropic muestra anthropics/claude-code-action@v1 y una configuración de plugin de code-review, con la advertencia habitual de usar GitHub Secrets para claves API (Claude Code Docs). Esa vía te da más control de CI. La ruta gestionada de Code Review te da el reviewer multiagente más profundo que describe Anthropic.

No las confundas. Una es automatización programable. La otra es un reviewer de pago, depth-first.

Un diagrama de árbol de decisión para disparadores de revisión con ramas para PR pequeño, PR arriesgado, PR grande y pushes repetidos, terminando

El truco: haz que Claude revise el contrato, no el estilo

Los malos archivos REVIEW.md parecen galletas de la fortuna:

Please ensure the code is clean, maintainable, secure, and well tested.

Eso producirá papilla.

Los buenos archivos REVIEW.md codifican cicatrices:

## Database migrations

Flag as Important if:
- A migration adds a non-null column without a default on an existing table.
- A migration backfills data without batching.
- Application code starts reading a new column before the migration is deployed.

Skip:
- Formatting comments in generated Prisma client files.

Aquí es donde la revisión con AI se vuelve útil. No está reemplazando el criterio de tu ingeniero senior. Está reproduciendo la memoria institucional del equipo en cada PR.

Algunas reglas que funcionan bien:

## Re-review behavior

On the first review, report Important and Nit findings.
On later reviews of the same PR, suppress new Nits unless they are directly caused by the latest push.

## Test policy

Flag missing tests only when the changed behavior is observable through a stable public interface.
Do not request snapshot tests for purely visual copy changes.

## Security policy

Flag any new endpoint that:
- Accepts user input without validation.
- Performs authorization by trusting a user-provided account ID.
- Logs tokens, session IDs, API keys, or full request bodies.

Fíjate en lo que falta: “haz que el código sea elegante”. Los humanos pueden discutir elegancia en una revisión. Claude debería comprobar contratos.

Lo que se están perdiendo los hilos

Los debates de HN y Reddit siguen dando vueltas a una pregunta: ¿debería la AI revisar código de AI?

Pregunta equivocada.

La pregunta correcta es: ¿qué partes de la revisión estás dispuesto a hacer explícitas?

Si tu cultura de revisión vive en la cabeza de los ingenieros senior, Claude Code Review se sentirá ruidoso y arbitrario. Si tu cultura de revisión está escrita como reglas del repo, se convierte en un multiplicador. CLAUDE.md le dice a Claude cómo funciona el proyecto. REVIEW.md le dice a Claude qué se niega a mergear tu equipo.

Esto también responde a la queja de “documentar para Claude”. Sí, los desarrolladores ahora escriben documentación para un agente. Suena ridículo hasta que te das cuenta de que esos docs también son material de onboarding, política de revisión y prevención de incidentes. Un buen CLAUDE.md también es un mejor archivo de “cómo funciona este repo” para humanos.

El filo cortante es la responsabilidad. Si Claude se pierde el bug, aun así tú lo mergeaste. Si Claude se inventa un bug, aun así tienes que rechazarlo. Si Claude revisa su propia salida, aun así necesitas señales independientes: tests, sistemas de tipos, análisis estático, observabilidad y un humano que entienda el cambio.

Usa Claude Code Review como control, no como juez. Haz que formule las preguntas molestas cada vez:

¿Dónde está el test de integración?
¿Dónde se aplica auth?
¿Este PR volvió falso CLAUDE.md?
¿Merece la pena comentar sobre este archivo generado?
¿Este hallazgo está respaldado por código, o es solo una corazonada?

Eso basta para amortizarse en los PRs adecuados.

Prueba la misma configuración con Claude Fable 5 en OneHop, drop-in, y empieza con $10 gratis.

Lecturas recomendadas: Primeros pasos con Claude Fable 5.