Agentic code review con Claude Code: fin al review inconsistente
DominicodeHace unos meses revisé el historial de PRs de un proyecto que llevaba tres años en producción. Había 600 pull requests cerrados. De esos, el 40% tenían el mismo comentario de review: "Falta manejo de errores".
El mismo comentario. 600 veces. Durante tres años.
Nadie había creado una regla. Nadie había automatizado la revisión. El code review dependía de que alguien con criterio tuviera tiempo y energía ese día. Y cuando no lo tenía, el PR se aprobaba igual.
Ese patrón tiene nombre: es el problema que el agentic code review viene a eliminar. Y hoy, con Claude Code, puedes tenerlo funcionando en tu proyecto en minutos.
Qué es el agentic code review (y qué no es)
Un agentic code review no es pedirle a un LLM que "revise este archivo". Eso es un chat con contexto limitado.
Un agentic code review es un proceso donde un agente de IA recorre el diff de tu PR de forma autónoma, lanza subagentes especializados en paralelo, analiza el historial de git para entender el contexto, y filtra los resultados por nivel de confianza antes de reportar.
La diferencia es estructural. En lugar de una respuesta de texto libre, tienes un pipeline que:
- Lee el PR completo con todos sus cambios
- Lanza múltiples agentes en paralelo con roles distintos
- Puntúa cada hallazgo con un nivel de confianza configurable
- Solo reporta los problemas que superan un umbral concreto
- Entrega los resultados con enlaces directos a las líneas de código
Con Claude Code, este pipeline puedes crearlo hoy y activarlo en segundos.
Cómo funciona /code-review en Claude Code
Claude Code te permite crear el comando /code-review como un slash command personalizado en .claude/commands/review.md. No es un built-in nativo de Claude Code — es un skill que configuras una vez y luego ejecutas en cualquier repositorio.
Prerequisito: Necesitas crear el archivo
.claude/commands/review.mdcon la definición del comando. Si ya tienes Claude Code con skills personalizados instalados (como los de Dominicode), este paso lo tienes cubierto. Puedes ver más artículos sobre cómo configurar Claude Code en el blog de Dominicode.
Una vez configurado, cuando lo ejecutas sobre un PR abierto, lanza cuatro agentes en paralelo:
- Agentes #1 y #2: Auditan el cumplimiento de las reglas definidas en tu
CLAUDE.md(con redundancia para reducir falsos negativos) - Agente #3: Escanea los cambios del PR en busca de bugs evidentes — no el codebase completo, solo el diff
- Agente #4: Analiza el
git blamee historial del repo para detectar problemas que solo tienen sentido con contexto histórico
El skill de review define un sistema de puntuación de confianza — un ejemplo habitual que puedes copiar y adaptar:
0 → Falso positivo probable
25 → Podría ser real
50 → Real, pero menor
75 → Real e importante
100 → Absolutamente seguro
El threshold por defecto en la mayoría de implementaciones es 80. Cualquier hallazgo por debajo no se reporta. Esto no es arbitrario: es lo que separa el ruido del signal en una revisión útil.
El comando en la práctica
# Revisión en terminal (mientras trabajas en local)
/code-review
# Publicar la revisión como comentario en el PR de GitHub
/code-review --comment
Nota: El flag
--commentforma parte de la implementación del skill personalizado. Para que funcione, tu archivo.claude/commands/review.mddebe incluir la lógica para detectar el PR activo del branch y postear el comentario en GitHub viaghCLI. El comportamiento no es nativo de Claude Code — lo defines tú en el skill.
El flag --comment es el que convierte la herramienta en algo que vive dentro de tu flujo de trabajo real. El agente no solo te dice qué está mal — lo posta directamente en el PR con los links exactos a las líneas.
Un output real tiene este aspecto (output de ejemplo):
## Code review
Found 3 issues:
1. Missing error handling for OAuth callback
(CLAUDE.md says "Always handle OAuth errors")
https://github.com/owner/repo/blob/abc123/src/auth.ts#L67-L72
2. Memory leak: OAuth state not cleaned up after failed login
(missing cleanup in finally block — bug, not pre-existing)
https://github.com/owner/repo/blob/abc123/src/auth.ts#L88-L95
3. Inconsistent naming: function uses snake_case
(conventions/CLAUDE.md says "Use camelCase for functions")
https://github.com/owner/repo/blob/abc123/src/utils.ts#L23-L28
Tres problemas. Tres links directos. Sin ruido.
Por qué el code review manual falla en producción
No es una cuestión de habilidad. Es una cuestión de sistema.
El code review manual tiene tres fallos estructurales que ningún proceso de equipo ha conseguido eliminar completamente:
Inconsistencia por contexto. El mismo developer revisa de forma diferente un lunes a las 9 de la mañana y un viernes a las 6 de la tarde. Las reglas que aplica dependen de su estado mental, no del código.
Punto ciego de los cambios recientes. Cuando tienes el código en la cabeza porque acabas de escribirlo, tu cerebro autocompleta lo que falta. El reviewer que eres tú mismo a los 5 minutos de terminar no ve los bugs que sí vería dentro de 3 horas.
Reglas no escritas que no se comprueban. Tu equipo puede tener convenciones de arquitectura claras en la mente de los seniors, pero si no están en un archivo que el proceso de review comprueba activamente, son invisibles para el proceso.
El agentic code review resuelve los tres. No se cansa. No autocompleta. Y si defines tus reglas en CLAUDE.md, las comprueba en cada PR sin excepción.
Cómo integrarlo en tu workflow real
El punto de entrada más simple es a nivel local, en tu flujo individual:
# 1. Terminas de implementar un feature
git add .
git commit -m "feat: add OAuth flow"
# 2. Abres el PR en GitHub
gh pr create --title "Add OAuth flow" --body "..."
# 3. Ejecutas el agentic review antes de pedir revisión humana
/code-review --comment
El agente revisa el PR y posta el comentario. Tú ves los issues, los corriges en una nueva commit, y solo entonces pides revisión humana. Tu reviewer llega a un PR que ya ha pasado por un filtro.
El segundo nivel es definir qué reglas quieres que el agente compruebe en cada review. Eso va en tu CLAUDE.md:
## Code Review Standards
- Always handle async errors with try/catch — no unhandled promises
- Use camelCase for functions, PascalCase for classes
- No direct DOM manipulation in Angular components
- Every public method must have JSDoc if it's part of a service API
- No hardcoded strings — use i18n keys or constants
A partir de ese momento, el agente comprueba estas reglas en cada PR de forma automática. Cada regla que documentas elimina una categoría entera de errores que antes dependían de que alguien se acordara de revisarlos.
Puedes encontrar más recursos sobre cómo estructurar CLAUDE.md para workflows de IA en el canal de YouTube de Dominicode, donde cubrimos este tipo de setups en profundidad. Y la documentación oficial del sistema está en docs de Claude Code de Anthropic.
Agentic vs. manual: la comparativa real
| Code review manual | Agentic code review | |
|---|---|---|
| Consistencia | Varía por persona y momento | Idéntica en cada PR |
| Velocidad | Minutos u horas | Segundos |
| Contexto histórico | Solo si el reviewer conoce el historial | Analiza git blame automáticamente |
| Reglas del equipo | Depende de la memoria | Lee CLAUDE.md siempre |
| Falsos positivos | Bajos (humano con criterio) | Filtrados por threshold de confianza |
| Escala | Limitada por tiempo humano | Ilimitada |
La conclusión no es "reemplaza el code review humano". Es "llega al code review humano con el trabajo sucio ya hecho".
El reviewer humano aporta lo que el agente no puede: criterio de producto, contexto de negocio, decisiones de arquitectura que van más allá del diff. Pero no necesita gastar ese criterio en detectar que falta un try/catch. Para eso está el agente.
El skill personalizado: más allá del comando base
El /code-review base es el punto de partida. Pero el sistema de skills de Claude Code te permite ir más lejos: crear un skill de revisión de código adaptado exactamente a tu stack y tus estándares.
Un skill personalizado vive en .claude/skills/review.md y puede definir categorías de severidad propias:
## Review Categories
### Critical (must fix before merge)
- Security vulnerabilities (SQL injection, XSS, exposed secrets)
- Data loss risks
- Breaking changes sin deprecation notice
### Important (should fix)
- Missing error handling in async operations
- N+1 queries en loops
- Estado mutable compartido sin sincronización
### Suggestions (nice to have)
- Naming improvements
- Refactoring opportunities
- Test coverage gaps
Esto no es documentación para humanos. Es el contrato que el agente respeta en cada revisión.
Si quieres explorar este nivel de customización con casos reales de producción, en el curso Construye con IA vemos exactamente cómo construir este tipo de workflows: desde el skill de review hasta la integración completa en el ciclo de desarrollo.
Lo que el agentic code review no puede hacer (todavía)
Hay que ser honestos sobre los límites.
El agente revisa el diff, no el sistema. Si tu PR introduce un cambio correcto en aislamiento pero que rompe un contrato implícito con otro módulo que no está en el diff, el agente no lo va a ver. Para eso necesitas tests de integración, no un reviewer.
Tampoco detecta problemas de producto. Un endpoint que técnicamente funciona pero que resuelve mal el problema del usuario es invisible para el agente. Ese criterio es humano, siempre.
Y los falsos negativos existen. Un confidence threshold de 80 elimina el ruido, pero también puede silenciar algún hallazgo real que el agente no puntúa con suficiente confianza. No es el 100% de los problemas. Es el 80% de los problemas que más tiempo consumen en reviews manuales.
Con esos límites claros, el agentic code review es una de las adiciones más baratas y de mayor impacto que puedes añadir a tu workflow hoy.
Empieza con esto
Si tienes Claude Code instalado, el punto de entrada es inmediato:
# En un repo con un PR abierto
/code-review
Si quieres que el agente comprenda las reglas de tu proyecto, el segundo paso es crear o mejorar tu CLAUDE.md con las convenciones que quieres que compruebe.
Y si quieres ver esto aplicado a un proyecto real — con las decisiones de qué documentar, cómo estructurar el skill y cómo encajarlo en un pipeline de CI — en Dominicode Labs tienes el proyecto de referencia con el setup completo que usamos en producción.
FAQ — Preguntas frecuentes sobre agentic code review
¿El agentic code review reemplaza completamente al code review humano?
No, y no debería. El agente es muy eficaz detectando problemas técnicos concretos: errores de manejo de excepciones, violaciones de convenciones, memory leaks en el diff. El reviewer humano aporta criterio de producto, arquitectura y contexto de negocio. La combinación de ambos es más potente que cualquiera de los dos solos.
¿Necesito una configuración especial de GitHub o CI para usar /code-review --comment?
El flag --comment requiere que tu implementación del skill incluya la lógica para postear via gh CLI con acceso al repo. Si ya tienes Claude Code configurado con acceso al repositorio de GitHub, el skill puede activar el comentario sin pasos adicionales. El agente detecta el PR activo del branch actual.
¿Qué pasa si el agente no tiene acceso a mi CLAUDE.md?
Sin un CLAUDE.md, el agente solo puede revisar bugs genéricos y problemas obvios del diff. Las reglas específicas de tu equipo — convenciones de naming, patrones de arquitectura, estándares de seguridad — no se comprueban. El CLAUDE.md es lo que convierte el agentic code review de "útil" a "imprescindible".
¿Puedo ajustar el threshold de confianza para que reporte más o menos problemas?
Sí. El threshold lo defines tú en la implementación del skill. El valor 80 es el habitual en setups de referencia, pero puedes bajarlo (por ejemplo, a 60) para ver más hallazgos con posibles falsos positivos, o subirlo (a 90+) para ver solo los problemas con certeza casi absoluta. Para proyectos maduros con buenas convenciones documentadas, un threshold alto es lo más productivo.
¿El agente revisa el codebase completo o solo los cambios del PR?
Solo los cambios del PR — el diff. Esto es una decisión de diseño deliberada: el agente no está ahí para auditar toda la deuda técnica del proyecto, sino para asegurarse de que los cambios nuevos no introducen problemas. La deuda existente es otra conversación.
¿Funciona con cualquier lenguaje o framework?
El /code-review base analiza el código con el modelo de Claude, que entiende prácticamente cualquier lenguaje. Para revisiones especializadas en un framework concreto (Angular, React, NestJS), un skill personalizado en .claude/skills/review.md con reglas específicas de ese stack da resultados significativamente mejores.
El code review manual no va a desaparecer. Pero el 70% del trabajo que hoy consume ese proceso puede delegarse a un agente que lo hace mejor, más rápido y sin quejarse de que el PR llegó el viernes por la tarde.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.