Cómo funciona realmente Claude Code Review: diffs, hooks y lo que el agente detecta

Claude Code Review: La guía práctica para revisiones de PR con agentes

Claude Code puede revisar un pull request o un diff local de la misma manera que lo haría un ingeniero senior meticuloso: leyendo los archivos modificados, rastreando los sitios donde se llaman las funciones, revisando las pruebas y devolviendo hallazgos clasificados por severidad con soluciones sugeridas. Esta guía trata específicamente sobre el uso de Claude Code (la herramienta CLI agéntica de Anthropic) para revisión de código: cómo activarlo, cómo darle buenas instrucciones, cómo automatizarlo en cada commit o PR, y cómo integrarlo en el pipeline de un equipo.

Qué significa realmente "Claude Code Review"

Hay dos cosas muy distintas a las que la gente llama "revisión de código con Claude". La primera es pedirle a Claude, en una interfaz de chat, que revise un fragmento de código que pegas. La segunda —y el tema de esta guía— es ejecutar Claude Code, el CLI agéntico de Anthropic, contra un diff real o un pull request dentro de tu repositorio real.

La distinción importa enormemente. Cuando Claude Code revisa un diff, no está razonando de forma aislada sobre un fragmento pegado. Es un agente autónomo que puede abrir archivos, seguir imports, leer las instrucciones de tu proyecto en CLAUDE.md, revisar pruebas adyacentes y comprender el contexto completo de un cambio antes de emitir un solo hallazgo. Esa conciencia entre archivos es lo que hace que el resultado sea genuinamente útil en lugar de genérico.

Claude Code está disponible como un CLI que instalas localmente (npm install -g @anthropic-ai/claude-code), o como un agente que se ejecuta en un sandbox en la nube —más sobre ambos enfoques más adelante—. La documentación oficial de Anthropic cubre la instalación y la configuración inicial.

El flujo de trabajo /review paso a paso

Claude Code viene con un comando de barra /review diseñado específicamente para esta tarea. Aquí está el flujo completo, desde el diff hasta un resultado accionable.

Paso 1 — Dirige a Claude Code hacia el diff

Tienes varias formas de proporcionarle los cambios que quieres que revise.

Cambios en staging (el comando /review):

/review

Dentro de la sesión de Claude Code, el comando de barra /review inicia una revisión de tus cambios. Este es el flujo de trabajo local más común: pones tus cambios en staging, ejecutas /review, y ves los hallazgos antes de hacer commit. (El comportamiento exacto del comando evoluciona; consulta la documentación de Claude Code de Anthropic para la sintaxis actual).

Un rango específico de git: También puedes simplemente pedírselo al agente en lenguaje natural; por ejemplo, "Revisa el diff entre main y esta rama y señala cualquier bug o regresión." Como Claude Code puede ejecutar comandos de git por sí mismo, generará el diff para el rango que le indiques y lo revisará. Esto es útil cuando revisas una rama de funcionalidad antes de abrir un PR, y evita depender de una sintaxis de flags exacta.

Una URL de pull request de GitHub: Si tu proyecto tiene configurado GitHub CLI, Claude Code puede obtener el diff del PR directamente. Proporcionas la URL o el número del PR en tu prompt, y el agente usa gh para obtener el diff junto con la descripción del PR, lo que le da contexto de intención además del código.

Paso 2 — Carga de contexto

Antes de emitir hallazgos, Claude Code lee el contexto que necesita para evaluar el diff correctamente:

• CLAUDE.md — el archivo de instrucciones de tu proyecto, que puede definir áreas de enfoque de la revisión, patrones prohibidos, reglas de arquitectura o convenciones del equipo. Esta es tu principal palanca para personalizar en qué presta atención el agente.
• Módulos importados y llamadores — si una función modificada se llama desde diez lugares, el agente lee esos sitios de llamada para verificar si el cambio es retrocompatible.
• Pruebas existentes — lee los archivos de prueba para entender el contrato previsto del código modificado, y para notar cuándo a la lógica nueva le falta cobertura.
• Archivos de configuración — eslint, tsconfig, pyproject.toml y archivos similares ayudan al agente a entender qué reglas de linting ya se aplican en CI, para no repetir hallazgos que tus herramientas ya detectan.

Paso 3 — Análisis

Los pases de análisis de Claude Code cubren varias dimensiones simultáneamente:

• Corrección — bugs de lógica, errores de conteo, desreferencias de null, suposiciones incorrectas de algoritmos
• Seguridad — riesgos de inyección, credenciales expuestas, deserialización insegura, verificaciones de autorización faltantes
• Confiabilidad — manejo de errores faltante, rechazos de promesas no manejados, casos límite no capturados
• Mantenibilidad — lógica duplicada, nombres poco claros, documentación faltante para comportamiento no obvio
• Cobertura de pruebas — rutas de código añadidas sin las pruebas correspondientes

El agente no solo señala una línea; explica por qué el hallazgo importa y cuál sería el impacto si se enviara a producción.

Paso 4 — Hallazgos estructurados

El resultado es una lista de hallazgos, cada uno con:

• Una etiqueta de severidad (típicamente: crítico / advertencia / sugerencia)
• La referencia de archivo y línea
• Una explicación en lenguaje sencillo del problema
• Una solución sugerida — a menudo un fragmento de código listo para aplicar

Por defecto, los hallazgos se muestran en la terminal. Para uso en equipo puedes redirigirlos: canalizarlos a un archivo, publicarlos como comentarios de PR mediante gh pr comment, o usar un hook para escribirlos en un registro de revisión compartido.

La revisión de Claude Code sigue un pipeline estructurado: desde la entrada del diff, pasando por la carga de contexto y el análisis, hasta los hallazgos clasificados y las sugerencias de corrección, con hooks que permiten la automatización completa.

Un ejemplo desarrollado: diff real, revisión real

Para hacerlo concreto, aquí hay un diff mínimo en Python y lo que revela una revisión de Claude Code.

El diff:

# Before
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    return result[0]

# After (in PR)
def get_user(user_id):
    result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
    if result:
        return result[0]
    return None

Lo que el autor del PR pensó haber arreglado: un KeyError cuando no se encuentra ningún usuario.

Lo que Claude Code revela en la revisión:

1. Crítico — Inyección SQL (línea 2): El f-string interpola user_id directamente en la consulta. Un valor como 1; DROP TABLE users;-- se ejecutaría. Solución: usar consultas parametrizadas — db.query("SELECT * FROM users WHERE id = ?", (user_id,)).

2. Advertencia — Propagación implícita de None: Los llamadores de get_user que no verifican None ahora fallarán a distancia. Revisa tres sitios de llamada (listados por archivo) que asumen que siempre se devuelve un objeto de usuario.

3. Sugerencia — Falta anotación de tipos: El tipo de retorno debería ser Optional[User] para que los IDE y los verificadores de tipos puedan detectar automáticamente el caso None en los sitios de llamada.

4. Sugerencia — Prueba añadida pero incompleta: La nueva prueba test_get_user_not_found solo verifica que se devuelva None; no verifica el comportamiento cuando user_id es 0 o no es un entero.

El autor original corrigió el KeyError pero introdujo un riesgo silencioso de propagación de None y no notó la inyección SQL preexistente. Claude Code detectó ambos, y los encontró porque leyó los sitios de llamada, no solo el diff.

Cómo darle mejores instrucciones a Claude Code para mejores revisiones

La calidad de una revisión es directamente proporcional a la calidad del contexto que le das al agente. Estos prompts y técnicas producen resultados consistentemente mejores.

Usa CLAUDE.md para establecer instrucciones permanentes

El mayor apalancamiento está en el archivo CLAUDE.md de tu proyecto. Añade una sección ## Review Guidelines:

## Review Guidelines
- We use parameterized queries everywhere. Flag any string interpolation in SQL.
- All public functions must have return-type annotations (Python) or JSDoc (JS).
- Security findings should always be severity: critical, not warning.
- We prefer explicit error returns over exceptions in the data layer.
- Do not flag import ordering — Black handles that automatically.

Esto instruye al agente una sola vez, y cada revisión en el proyecto hereda estas reglas sin que tengas que volver a indicarlas.

Proporciona la intención en el prompt

Al invocar una revisión de forma interactiva, dile al agente qué está tratando de lograr el PR:

/review This PR migrates our auth flow from JWT to session cookies. Focus on
session fixation, secure cookie attributes, and any places we might be leaking
the old JWT validation logic.

El contexto de intención le permite a Claude Code priorizar los hallazgos relevantes en lugar de generar una lista de verificación uniforme en todas las dimensiones.

Pide primero un pase solo de severidad

Para diffs grandes, un enfoque de dos pases es eficiente:

/review Pass 1: list only critical and warning severity findings with file+line.
No suggestions yet.

Luego, una vez que tengas la lista crítica, pide detalles de solución para hallazgos específicos. Esto evita el problema de un resultado de revisión de 200 líneas donde el bug crítico queda enterrado entre sugerencias de estilo.

Pide confirmación de comprensión

Para cambios complejos:

Before reviewing, summarize what this diff is trying to do in two sentences,
then proceed with the review.

Si el resumen es incorrecto, sabes que el agente malinterpretó el diff y puedes corregirlo antes de perder tiempo en hallazgos equivocados.

Automatizar revisiones con hooks

Ejecutar /review manualmente es útil, pero la verdadera ganancia de productividad está en hacer que la revisión sea automática, de modo que cada commit o cada PR abierto la active sin que un humano tenga que recordarlo. El sistema de hooks de Claude Code hace esto posible. (El sistema de hooks se cubre en profundidad en la guía de hooks de Claude Code; esta sección se enfoca específicamente en el caso de uso de revisión).

Revisión automática en cada commit

En el archivo .claude/settings.json de tu proyecto, añade un hook Stop:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude -p 'Review the diff from the last commit (git diff HEAD~1 HEAD) and list any bugs, security issues, or regressions.'"
          }
        ]
      }
    ]
  }
}

Con esto configurado, cada vez que Claude Code completa una tarea (incluidas las tareas de codificación que terminan en un commit), el hook se activa y revisa el diff resultante. Los hallazgos aparecen en tu terminal inmediatamente después de que se registra el commit.

Revisión automática al abrir un PR

Para la integración con CI, ejecuta Claude Code en modo headless (claude -p "<prompt>") dentro de un job de GitHub Actions y publica el resultado como un comentario de PR. El siguiente patrón es ilustrativo; Anthropic también publica una Acción oficial de GitHub para Claude Code, así que consulta la documentación de Claude Code para la configuración de CI actual y recomendada, en lugar de copiar los flags textualmente:

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
      - name: Run review
        run: |
          claude -p "Review the diff between origin/${{ github.base_ref }} and HEAD. \
          List bugs, security issues, and regressions, ranked by severity." > review.md
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - name: Post review as PR comment
        run: gh pr comment ${{ github.event.number }} --body-file review.md
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Esto publica los hallazgos de Claude Code como un comentario de PR automáticamente en cada push. Tus revisores humanos enfocan entonces su atención en los hallazgos que el agente ya reveló, en lugar de dedicar tiempo de revisión a los elementos que Claude Code detecta de forma confiable.

Qué detecta Claude Code Review y qué se le escapa

Es importante ser realista sobre el alcance de sus capacidades. La revisión con IA es genuinamente poderosa para una clase específica de hallazgos, y de forma confiable insuficiente para otros.

Claude Code sobresale en corrección mecánica, patrones de seguridad y consistencia, mientras que el juicio de producto, las amenazas novedosas y el visto bueno de cumplimiento normativo siguen siendo responsabilidad humana.

Claude Code detecta de forma confiable:

• Errores de conteo, desreferencias de null/undefined, y discordancias de tipos visibles en el diff y su contexto inmediato
• Patrones de seguridad conocidos: inyección SQL, XSS, brechas de CSRF, referencias directas a objetos inseguras, validación de entrada faltante, secretos en el código
• Violaciones de estilo y convenciones frente a las reglas definidas en tu CLAUDE.md y archivos de configuración
• Lógica duplicada — la conciencia entre archivos del agente hace que note cuando una función que acabas de añadir ya existe en un módulo de utilidades dos directorios más allá
• Manejo de errores faltante — rechazos de promesas no manejados, cláusulas except vacías, funciones que pueden devolver None o undefined sin que el llamador lo espere
• Brechas de cobertura de pruebas para las rutas de código específicas añadidas en el diff

Claude Code no reemplaza el juicio humano en:

• Decisiones de producto y requisitos. Si la funcionalidad debería existir, si la UX tiene sentido, si el contrato de la API es la abstracción correcta: estas cosas requieren contexto de negocio que ningún agente tiene.
• Amenazas de seguridad novedosas. El agente conoce las clases de vulnerabilidades conocidas; no inventa modelos de amenazas específicos para el entorno de despliegue o la lógica de negocio de tu aplicación.
• Rendimiento a escala. El análisis estático no puede sustituir la salida de un profiler, los resultados de pruebas de carga o la comprensión de los patrones de tráfico reales.
• Cumplimiento normativo. GDPR, HIPAA, PCI-DSS y regulaciones similares requieren el visto bueno humano y a menudo revisión legal. La revisión con IA no puede sustituirlo.
• Dinámica de equipo y gobernanza de arquitectura. "¿Esto pertenece a este módulo?" o "¿Deberíamos incorporar esta dependencia?" requieren contexto organizacional.

El enfoque saludable: la revisión de Claude Code elimina la parte aburrida de la revisión de código —detectar errores mecánicos, hacer cumplir convenciones, señalar patrones ya conocidos como problemáticos— para que tus revisores humanos puedan dedicar su atención limitada a decisiones de juicio que realmente necesitan juicio humano.

Integrar la revisión de Claude Code en el pipeline de un equipo

Lograr que un equipo use la revisión agéntica de forma consistente requiere tratarla como una parte de primera clase de tu flujo de trabajo, no como un extra opcional.

El modelo de tres capas

Un pipeline de equipo que funciona bien tiene tres capas:

1. Pre-commit local — El desarrollador ejecuta /review antes de hacer push. La configuración de hooks descrita anteriormente automatiza esto. Los hallazgos en esta capa son los más baratos de corregir.
2. Puerta de CI — El flujo de trabajo de GitHub Actions publica los hallazgos de Claude Code como un comentario de PR antes de que se asigne cualquier revisor humano. Los revisores humanos se asignan solo después de que la revisión de CI pasa (sin hallazgos críticos).
3. Enfoque de revisión humana — Los revisores humanos usan el comentario de Claude Code como una guía de triaje. Su trabajo es evaluar los elementos de juicio —encaje de arquitectura, corrección de producto, compensaciones de rendimiento— no releer cada línea buscando errores tipográficos.

Compartir las convenciones de CLAUDE.md

Tu CLAUDE.md es la capa de configuración del comportamiento de revisión del agente. Trátalo como código: haz commit de él, versiónalo, revisa los cambios que se le hacen en PRs. Cuando el equipo acuerde que Claude Code debería dejar de señalar un patrón en particular (porque ya tienen un linter para eso), actualiza CLAUDE.md y el cambio se aplica a cada revisión futura.

Calibrar los umbrales de severidad

Los equipos a menudo encuentran que la calibración de severidad por defecto es demasiado ruidosa al principio. Añade instrucciones explícitas a CLAUDE.md para controlarla:

## Review Severity Rules
- Only flag console.log as a warning if it is in a non-test, non-debug file.
- Import ordering is never a finding; Prettier handles it.
- Treat any hardcoded credential as critical regardless of context.
- Performance suggestions are informational only unless they affect O(n²) loops.

Después de algunas semanas de uso, la mayoría de los equipos encuentra que el nivel de ruido disminuye significativamente una vez que la atención del agente se ajusta a los patrones que realmente importan en su base de código.

Manejo de falsos positivos

Claude Code ocasionalmente señalará algo de forma incorrecta. La respuesta correcta no es descartar la revisión por completo, sino añadir una instrucción específica del proyecto a CLAUDE.md que maneje ese patrón. Con el tiempo, esto crea una configuración de revisión cada vez más precisa y específica del proyecto que refleja los estándares reales de tu equipo.

Ejecutar Claude Code Review sin instalación local

Todo lo descrito hasta ahora asume que tienes Claude Code instalado y ejecutándose en tu terminal. Para muchos equipos —especialmente aquellos con máquinas corporativas bloqueadas, entornos Windows sin WSL, o desarrolladores que quieren revisar desde una pestaña del navegador— la instalación local es un punto de fricción.

Happycapy ejecuta Claude Code en un sandbox seguro en la nube directamente en tu navegador. Obtienes toda la capacidad de revisión agéntica —incluida la carga de contexto entre archivos, soporte para CLAUDE.md, y el comando /review— sin instalar nada. Esto es particularmente útil para:

• Revisión de código en pull requests desde un navegador sin descargar la rama localmente
• Equipos que están adoptando la revisión con Claude Code y quieren un entorno compartido y consistente antes de implementar instalaciones locales
• Máquinas bloqueadas donde instalar paquetes globales de npm requiere aprobación de TI
• Revisión de repositorios desconocidos donde quieres la carga de contexto del agente sin clonar todo el repositorio

Si tienes curiosidad sobre cómo se compara Claude Code con alternativas en términos de capacidad agéntica, consulta Claude Code vs. GitHub Copilot y Claude Code vs. Cursor. Y si quieres entender cómo Happycapy ejecuta Claude Code en un contexto de navegador, Claude Code en la web cubre la arquitectura.

Comienza gratis en happycapy.ai

Preguntas frecuentes

P: ¿La revisión de Claude Code funciona con cualquier lenguaje?

Sí. Claude Code no es específico de un lenguaje: lee cualquier diff basado en texto y aplica razonamiento sobre el código que contiene. Tiende a ser más preciso en Python, TypeScript, JavaScript, Go y Rust (lenguajes con gran representación en el entrenamiento), pero produce hallazgos útiles en Ruby, Java, C# y la mayoría de los otros lenguajes convencionales. Para lenguajes específicos de dominio o frameworks poco comunes, añadir contexto en CLAUDE.md mejora notablemente el resultado.

P: ¿En qué se diferencia /review de simplemente pedirle a Claude en un chat que revise mi diff?

La diferencia clave es el uso agéntico de herramientas y el contexto del repositorio. En un chat, Claude solo ve lo que pegas. El comando /review de Claude Code le permite al agente abrir archivos, seguir imports, revisar pruebas y leer las convenciones de tu proyecto, produciendo hallazgos fundamentados en la base de código real en lugar del fragmento. Para cambios grandes o interconectados, esta diferencia es sustancial.

P: ¿La revisión de Claude Code detectará vulnerabilidades de seguridad?

Detecta de forma confiable las clases de vulnerabilidades bien conocidas: inyección SQL, XSS, brechas de CSRF, referencias directas a objetos inseguras, secretos codificados de forma fija, saneamiento de entrada faltante. Es menos confiable en vectores de ataque novedosos y específicos de la aplicación, o en vulnerabilidades que requieren entender tu entorno de despliegue. Trátala como un exhaustivo primer escaneo de seguridad, no como una prueba de penetración.

P: ¿Cómo evito que la revisión señale cosas que mi linter ya maneja?

Añade exclusiones explícitas a tu CLAUDE.md: "No señalar el orden de los imports; isort se encarga de eso." o "No señalar espacios en blanco al final de línea; Prettier lo aplica." La mayoría de los equipos construyen esta lista en dos o tres semanas de uso y encuentran que la relación señal-ruido mejora drásticamente.

P: ¿Puedo usar la revisión de Claude Code en un monorepo con varios lenguajes?

Sí. Puedes acotar la revisión con un argumento de ruta o un rango de diff de git que cubra solo el subdirectorio que modificaste. También puedes mantener secciones de revisión específicas de cada lenguaje en tu CLAUDE.md que el agente lee como parte de la carga de contexto.

P: ¿Qué pasa si el diff es muy grande, digamos, un PR de 3,000 líneas?

Para diffs muy grandes, considera un enfoque de dos pases: primero pide solo los hallazgos críticos y de advertencia (sin sugerencias), tríalos, y luego pide un análisis completo de archivos o subsistemas específicos. Para refactorizaciones extremadamente grandes, dividir el PR es la mejor solución, tanto para la revisión humana como para la de IA.

P: ¿El resultado de la revisión es determinista? ¿Obtendré los mismos hallazgos dos veces?

No; como con toda salida de modelos de lenguaje grandes, hay variación entre ejecuciones. Para revisiones de alto riesgo, ejecutar el comando dos veces y comparar los hallazgos es una práctica razonable. La mayoría de los hallazgos críticos aparecen de forma consistente; las sugerencias menores varían más. Usar una temperatura más baja (si es configurable en tu flujo de trabajo) o prompts más prescriptivos reduce la variabilidad.

P: ¿Cómo interactúa la revisión de Claude Code con los linters y herramientas de análisis estático existentes?

Los complementa, no los reemplaza. Tus linters detectan reglas de estilo aplicadas de forma mecánica y rápida; Claude Code añade comprensión semántica: puede evaluar si una función hace lo correcto, algo que ningún linter puede hacer. El pipeline ideal ejecuta ambos: linters en hooks de pre-commit (rápido, determinista), revisión de Claude Code en CI (más lento, semántico). El comando /review es consciente de la configuración de tu linter y evita duplicar hallazgos que tus herramientas ya producen.

P: ¿Puedo personalizar el formato del resultado de la revisión para publicarlo en Slack o en un ticket?

Sí. Puedes indicarle al agente que produzca los hallazgos en un formato específico: JSON, markdown, o una plantilla que coincida con el estilo de comentarios de PR de tu equipo. Combina esto con el sistema de hooks y un pequeño script de shell, y tendrás un pipeline de revisión completamente automatizado que publica hallazgos estructurados en cualquier lugar donde tu equipo haga seguimiento.

Relacionado: Análisis a fondo de los hooks de Claude Code — automatiza verificaciones de pre-commit, linting y flujos de trabajo personalizados más allá de la revisión.

Guías relacionadas

• Claude Code Hooks: La guía para usuarios avanzados para automatizar tu agente
• Construye agentes autónomos con el Claude Code SDK: una guía práctica para desarrolladores
• Claude Code vs GitHub Copilot: ¿agente autónomo o asistente dentro del editor?
• Claude Code Web: cómo ejecutar Claude Code en tu navegador (sin instalación)