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

Claude Code Review: La guía práctica para revisiones de PR agénticas

Claude Code puede revisar una pull request o un diff local de la misma forma en que lo haría un ingeniero senior meticuloso: leyendo los archivos modificados, rastreando los puntos de llamada, comprobando las pruebas y devolviendo hallazgos clasificados por gravedad con propuestas de solución. Esta guía trata específicamente sobre el uso de Claude Code (la herramienta CLI agéntica de Anthropic) para la revisión de código: cómo activarla, cómo formular buenas instrucciones (prompts), cómo automatizarla en cada commit o PR, y cómo integrarla 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 examine un fragmento de código que has pegado. La segunda —y el tema de esta guía— es ejecutar Claude Code, la CLI agéntica de Anthropic, sobre un diff real o una pull request dentro de tu repositorio real.

La diferencia 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 importaciones, leer las instrucciones de tu proyecto en CLAUDE.md, comprobar las pruebas adyacentes y entender el contexto completo de un cambio antes de emitir un solo hallazgo. Esa conciencia entre archivos es lo que hace que el resultado sea realmente útil en lugar de genérico.

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

El flujo de trabajo de /review paso a paso

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

Paso 1 — Indica a Claude Code dónde está el diff

Tienes varias formas de proporcionarle los cambios que quieres revisar.

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 habitual: pones tus cambios en staging, ejecutas /review y ves los hallazgos antes de hacer el commit. (El comportamiento exacto del comando evoluciona; consulta la documentación de Claude Code de Anthropic para conocer la sintaxis actual).

Un rango de git específico: 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 git por sí mismo, generará el diff para el rango que indiques y lo revisará. Esto es útil al revisar una rama de funcionalidad antes de abrir una PR, y evita depender de una sintaxis de flags exacta.

Una URL de pull request de GitHub: Si tu proyecto tiene configurada la CLI de GitHub, Claude Code puede obtener directamente el diff de la PR. Proporcionas la URL o el número de la PR en tu prompt, y el agente usa gh para obtener el diff junto con la descripción de la PR, lo que le aporta 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 para la revisión, patrones prohibidos, reglas de arquitectura o convenciones del equipo. Esta es tu principal palanca para personalizar en qué se fija el agente.
• Módulos importados y llamadores — si una función modificada se invoca desde diez sitios, el agente lee esos puntos de llamada para comprobar si el cambio es retrocompatible.
• Pruebas existentes — lee los archivos de pruebas para entender el contrato previsto del código modificado, y para detectar cuándo la nueva lógica carece de 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, de modo que no repita hallazgos que tu herramienta ya detecta.

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 desplazamiento por uno, desreferencias nulas, suposiciones de algoritmo incorrectas
• Seguridad — riesgos de inyección, credenciales expuestas, deserialización insegura, comprobaciones de autorización ausentes
• Fiabilidad — manejo de errores ausente, rechazos de promesas sin gestionar, casos límite no contemplados
• Mantenibilidad — lógica duplicada, nomenclatura poco clara, documentación ausente para comportamientos no evidentes
• Cobertura de pruebas — rutas de código añadidas sin las pruebas correspondientes

El agente no se limita a señalar una línea; explica por qué importa el hallazgo y cuál sería el impacto si se desplegara.

Paso 4 — Hallazgos estructurados

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

• Una etiqueta de gravedad (normalmente: crítico / advertencia / sugerencia)
• La referencia de archivo y línea
• Una explicación en lenguaje llano del problema
• Una propuesta de solución — 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: enviarlos a un archivo, publicarlos como comentarios de PR mediante gh pr comment, o usar un hook para escribirlos en un registro de revisiones 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 propuestas de solución, con hooks que permiten la automatización completa.

Un ejemplo práctico: diff real, revisión real

Para hacerlo concreto, aquí tienes un diff de Python mínimo 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 de la PR creía 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 retorno None: Los llamadores de get_user que no comprueben None fallarán ahora a distancia. Revisa los tres puntos de llamada (listados por archivo) que asumen que siempre se devuelve un objeto de usuario.

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

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

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

Cómo dar mejores instrucciones a Claude Code para obtener mejores revisiones

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

Usa CLAUDE.md para fijar 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 del proyecto hereda estas reglas sin necesidad de volver a indicarlas.

Aporta la intención en el prompt

Al invocar una revisión de forma interactiva, dile al agente qué pretende conseguir la 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 permite a Claude Code priorizar los hallazgos relevantes en lugar de generar una lista de comprobación uniforme en todas las dimensiones.

Pide primero un pase de solo gravedad

Para diffs grandes, un enfoque en dos pases es más eficiente:

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

Después, una vez que tienes la lista de elementos críticos, pide detalles de solución para hallazgos concretos. Esto evita el problema de una salida 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 ha malinterpretado el diff y puedes corregirlo antes de perder tiempo en hallazgos desencaminados.

Automatizar las revisiones con hooks

Ejecutar /review manualmente es útil, pero la verdadera ganancia de productividad consiste en hacer que la revisión sea automática, de modo que cada commit o cada PR abierta la active sin que nadie tenga que acordarse de hacerlo. El sistema de hooks de Claude Code lo hace posible. (El sistema de hooks se trata en profundidad en la guía de hooks de Claude Code; esta sección se centra específicamente en el caso de uso de revisión).

Revisión automática en cada commit

En el .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 en marcha, 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 registre el commit.

Revisión automática al abrir una PR

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

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 comentario de PR automáticamente en cada push. Tus revisores humanos centran entonces su atención en los hallazgos que el agente ya ha señalado, en lugar de dedicar tiempo de revisión a los elementos que Claude Code detecta de forma fiable.

Qué detecta la revisión de Claude Code y qué se le escapa

Es importante ser realista sobre el alcance de sus capacidades. La revisión con IA es genuinamente potente para una clase concreta de hallazgos, y de forma fiable insuficiente para otros.

Claude Code destaca en corrección mecánica, patrones de seguridad y consistencia, mientras que el criterio de producto, las amenazas novedosas y la aprobación de cumplimiento normativo siguen siendo responsabilidad humana.

Claude Code detecta de forma fiable:

• Errores de desplazamiento por uno, desreferencias de nulo/indefinido y discrepancias 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 ausente, secretos en el código
• Infracciones 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 a dos directorios de distancia
• Manejo de errores ausente: rechazos de promesas sin gestionar, cláusulas except vacías, funciones que pueden devolver None o undefined sin que el llamador lo espere
• Lagunas de cobertura de pruebas para las rutas de código concretas añadidas en el diff

Claude Code no sustituye el criterio humano en:

• Decisiones de producto y de requisitos. Si la funcionalidad debería existir, si la UX tiene sentido, si el contrato de la API es la abstracción correcta: todo esto requiere contexto de negocio que ningún agente posee.
• Amenazas de seguridad novedosas. El agente conoce las clases de vulnerabilidad conocidas; no inventa modelos de amenaza específicos del 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. El RGPD, la HIPAA, la PCI-DSS y normativas similares requieren aprobación humana y, a menudo, revisión legal. La revisión con IA no puede sustituirla.
• Dinámicas de equipo y gobernanza de arquitectura. «¿Esto pertenece a este módulo?» o «¿Deberíamos incorporar esta dependencia?» requieren contexto organizativo.

El planteamiento saludable: la revisión de Claude Code elimina la parte aburrida de la revisión de código —detectar errores mecánicos, aplicar convenciones, señalar patrones conocidos como malos— para que tus revisores humanos puedan dedicar su atención limitada a las decisiones de criterio que de verdad necesitan juicio humano.

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

Conseguir que un equipo use realmente la revisión agéntica de forma consistente exige tratarla como una parte de primer nivel de tu flujo de trabajo, no como algo 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 antes 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 comentario de PR antes de que se asigne ningún revisor humano. Los revisores humanos solo se asignan una vez 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 guía de triaje. Su trabajo es evaluar los elementos de criterio: encaje arquitectónico, corrección del producto, compensaciones de rendimiento, en lugar de releer cada línea buscando erratas.

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 hagan en PRs. Cuando el equipo acuerde que Claude Code debe dejar de señalar un patrón concreto (porque ya tenéis un linter para ello), actualiza CLAUDE.md y el cambio se aplicará a todas las revisiones futuras.

Calibrar los umbrales de gravedad

Los equipos a menudo consideran que la calibración de gravedad 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.

Tras unas semanas de uso, la mayoría de los equipos comprueba que el nivel de ruido baja de forma significativa una vez que la atención del agente se ajusta a los patrones que realmente importan en su base de código.

Gestionar los falsos positivos

Claude Code señalará ocasionalmente algo de forma incorrecta. La respuesta adecuada no es descartar la revisión por completo, sino añadir una instrucción específica del proyecto a CLAUDE.md que gestione 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 la revisión de Claude Code 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 en máquinas corporativas restringidas, 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, el soporte de CLAUDE.md y el comando /review— sin instalar nada. Esto resulta especialmente útil para:

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

Si tienes curiosidad por saber cómo se compara Claude Code con las alternativas en cuanto a 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 explica la arquitectura.

Empieza gratis en happycapy.ai

Preguntas frecuentes

P: ¿Funciona la revisión de Claude Code con cualquier lenguaje?

Sí. Claude Code no es específico de ningún lenguaje: lee cualquier diff basado en texto y aplica razonamiento sobre el código que contiene. Suele ser más preciso en Python, TypeScript, JavaScript, Go y Rust (lenguajes con una gran representación en el entrenamiento), pero produce hallazgos útiles en Ruby, Java, C# y la mayoría de los demás lenguajes habituales. 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 permite al agente abrir archivos, seguir importaciones, comprobar 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: ¿Detectará la revisión de Claude Code vulnerabilidades de seguridad?

Detecta de forma fiable las clases de vulnerabilidad bien conocidas: inyección SQL, XSS, brechas de CSRF, referencias directas a objetos inseguras, secretos codificados, saneamiento de entrada ausente. Es menos fiable con vectores de ataque novedosos y específicos de la aplicación, o 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 gestiona?

Añade exclusiones explícitas a tu CLAUDE.md: «No señales el orden de las importaciones; isort se encarga de eso» o «No señales los espacios en blanco al final de línea; Prettier los aplica». La mayoría de los equipos construyen esta lista a lo largo de dos o tres semanas de uso y comprueban 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 has modificado. También puedes mantener secciones de revisión específicas por lenguaje en tu CLAUDE.md que el agente lee como parte de la carga de contexto.

P: ¿Qué ocurre si el diff es muy grande, por ejemplo, una PR de 3000 líneas?

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

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

No: como en toda salida de un modelo de lenguaje grande, 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 las herramientas de análisis estático existentes?

Las complementa, no las sustituye. 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ápidos, deterministas), la revisión de Claude Code en CI (más lenta, semántica). 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 de la salida de la revisión para publicarla en Slack o en un ticket?

Sí. Puedes indicarle al agente que muestre 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 totalmente automatizado que publica hallazgos estructurados donde sea que tu equipo haga seguimiento.

Relacionado: Análisis en profundidad de los hooks de Claude Code — automatiza comprobaciones 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 avanzada para automatizar tu agente
• Crea agentes autónomos con el SDK de Claude Code: 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)