Módulo 2: Code Review Automático en PRs

Módulo 2: Code Review Automático en PRs

Siguiente →

Módulo 2: Code Review Automático en PRs

Descripción

El Módulo 1 puso Claude Code dentro de GitHub Actions: un workflow corre en cada PR, ejecuta el agente, y produce algún output. Pero ese output es genérico — un análisis general que aterriza como comentario o artefacto. Ahora subes el nivel: vas a configurar Claude Code como un bot de code review que comenta inline en archivos específicos del PR, detecta bugs potenciales con criterio, sugiere mejoras concretas, y valida convenciones del equipo.

Este es el módulo que produce el resultado más visible de toda la guía. Cuando termines, cada PR de tu equipo tendrá comentarios automáticos de un agente que entiende el contexto del proyecto, no solo la sintaxis. Es la aplicación killer de Claude Code en CI/CD: un reviewer que nunca se cansa, no tiene ego, y conoce las convenciones del equipo.

Al terminar las 6 cápsulas, vas a tener un bot de code review funcional que comenta inline en PRs, opera en suggest-only mode (no bloquea merges hasta que el equipo confíe), maneja PRs grandes con chunking inteligente, y aplica las convenciones específicas de tu codebase.

Dónde Estamos en la Guía

Phase 1: Pre-Merge Automation (Módulos 1-2)
├── Módulo 1: Claude Code en GitHub Actions ✅
└── Módulo 2: Code Review Automático en PRs ← ESTÁS AQUÍ
    → Inline comments, contexto, suggest-only, convenciones

Phase 2: Cross-Platform y Deployment (Módulos 3-4)
├── Módulo 3: GitLab CI/CD y SDK Headless
└── Módulo 4: Deployment Automation

Phase 3: Resiliencia y Proyecto (Módulos 5-6)
├── Módulo 5: Security Scanning y Rollback
└── Módulo 6: Proyecto Integrador — Pipeline Completo

Este es el Módulo 2 de 6. El Módulo 1 te dio un workflow funcional que ejecuta Claude Code; este módulo lo especializa para code review y le da el output que cualquier developer puede ver y usar.

Code Review con Contexto, No Linting

Hay una distinción central que separa este módulo de un linter tradicional:

LINTER (eslint, pylint, ruff):
→ Verifica reglas de syntax y estilo
→ "Falta espacio después de la coma"
→ "Variable no usada"
→ Reglas universales, sin contexto del proyecto
→ Útil pero limitado: detecta forma, no fondo

CLAUDE CODE COMO REVIEWER (este módulo):
→ Lee el diff y entiende qué cambió
→ Razona sobre el contexto: ¿este cambio rompe algo?
→ "Esta función nueva no maneja el caso de input vacío,
   y según UserService.create_user este es un input válido"
→ "El nombre createOrder es inconsistente — el resto del
   módulo usa snake_case"
→ Reglas con contexto del proyecto: detecta forma Y fondo

El linter dice "viola la regla X". Claude Code dice "esto va a romper este caso específico de tu proyecto". La diferencia es contexto.

Una Tarea Real: Antes y Después

Para anclar el módulo, considera un escenario típico de un equipo con 5 developers:

Tarea del equipo: Cada PR debe pasar por code review antes de merge. Los reviewers humanos están saturados — hay PRs esperando 2-3 días para review.

Enfoque A: Solo review humano

Día 1, 09:00 → Developer abre PR con 200 líneas modificadas
Día 1, 11:00 → Reviewer humano asignado, pero ocupado en otra cosa
Día 2, 14:00 → Reviewer toma el PR. Tarda 45 min en entender el cambio.
              Encuentra 3 issues:
              - Nombre inconsistente con el resto del proyecto
              - Falta validación de input
              - Una query sin parametrizar
              Comenta cada uno
Día 3, 10:00 → Developer aplica fixes
Día 3, 14:00 → Re-review (otros 30 min)
Día 3, 16:00 → Approve, merge

TIEMPO TOTAL HUMANO: ~2.5 horas de reviewer
TIEMPO REAL: 3 días desde abrir hasta merge

Enfoque B: Bot + Review humano (este módulo)

Día 1, 09:00 → Developer abre PR con 200 líneas modificadas
Día 1, 09:01 → Bot de Claude Code dispara automáticamente
Día 1, 09:03 → Bot deja 3 comentarios inline:
              - Línea 45: "El nombre createOrder no sigue
                snake_case del resto del módulo"
              - Línea 67: "Esta función no valida el caso de
                input vacío, ver UserService.create_user
                como referencia"
              - Línea 89: "Esta query usa string concatenation,
                vulnerable a SQL injection. Sugerencia: usar
                parameterized query"
Día 1, 09:30 → Developer aplica los 3 fixes (los issues que
              el bot detectó son obvios una vez señalados)
Día 1, 10:00 → Re-disparo del bot, todos los issues resueltos
Día 1, 14:00 → Reviewer humano toma el PR. Como los issues
              obvios ya se resolvieron, se enfoca en lo que
              requiere juicio: arquitectura, claridad de la
              solución, edge cases del dominio
Día 1, 14:20 → Approve (20 min de reviewer humano)
Día 1, 14:25 → Merge

TIEMPO TOTAL HUMANO: ~20 minutos de reviewer
TIEMPO REAL: ~5 horas desde abrir hasta merge

Mismo PR. Mismos issues. Resultado radicalmente distinto.

La diferencia no es que el bot reemplaza al humano — es que el bot filtra lo obvio para que el humano se enfoque en lo que requiere juicio. Tiempo del reviewer humano: de 2.5h a 20 min. Tiempo total del PR: de 3 días a 5 horas.

Prerequisitos

Conocimiento requerido:

  • ✅ Módulo 1 completado (workflow YAML funcional, secrets configurados)
  • ✅ Familiaridad con GitHub PRs (cómo abrirlos, qué es un diff, qué es un comentario inline)
  • ✅ Acceso de escritura a un repositorio donde puedas configurar webhooks

Recomendado:

  • ✅ Un CLAUDE.md o equivalente para tu proyecto (Módulo 6 de la Guía 8)
  • ✅ Un proyecto con convenciones de código documentadas

NO requerido:

  • ❌ No necesitas haber configurado un GitHub bot antes
  • ❌ No necesitas conocer la GitHub REST/GraphQL API en profundidad

Roadmap del Módulo

Cápsula 01 — Introducción al módulo (esta cápsula)

Code review con contexto vs linter. El escenario antes/después.

Cápsula 02 — Triggers de PR y extracción del diff

Cómo configurar el workflow para correr en eventos específicos del PR (opened, synchronize, ready_for_review). Cómo extraer el diff y pasarlo a Claude Code de forma eficiente.

Cápsula 03 — Inline comments via GitHub API

La diferencia entre un comentario general del PR y un comentario inline en una línea específica. Cómo usar la GitHub API (REST y GraphQL) para crear inline comments. Manejo de tokens y permisos.

Cápsula 04 — Review summary y suggest-only mode

Cómo generar un resumen de los hallazgos al final del review. Configurar el bot en suggest-only mode (no bloquea merges) hasta que el equipo gane confianza.

Cápsula 05 — Personalizar convenciones del equipo

Cómo pasar al bot las convenciones específicas de tu proyecto: naming, estructura de archivos, patrones aceptados. CLAUDE.md como source of truth de convenciones.

Cápsula 06 — Manejar PRs grandes

Qué hacer cuando un PR tiene 50+ archivos o miles de líneas. Estrategias de chunking, priorización de archivos relevantes, y cómo balancear cobertura vs costo.

Mapa de progresión

Cápsula 01 (esta)  → Por qué code review con contexto
Cápsula 02         → Triggers + extracción del diff
Cápsula 03         → Inline comments (lo que el equipo ve)
Cápsula 04         → Summary + suggest-only mode
Cápsula 05         → Personalización por convenciones
Cápsula 06         → PRs grandes sin saturar costos

Dificultad: ⭐⭐ ────────────────▶ ⭐⭐⭐⭐

Qué Lograrás en Este Módulo

Al completar las 6 cápsulas, podrás:

  1. Configurar triggers de PR que disparan el bot solo cuando es relevante
  2. Extraer y procesar diffs de PRs sin sobrecargar el context window
  3. Generar inline comments en líneas específicas usando la GitHub API
  4. Producir review summaries que resumen los hallazgos en una vista
  5. Operar el bot en suggest-only mode para ganar confianza del equipo gradualmente
  6. Personalizar convenciones específicas de tu proyecto via CLAUDE.md
  7. Manejar PRs grandes con chunking inteligente sin saturar costos

El antes y después

ANTES del módulo:
→ "El bot deja un comentario genérico al final del PR"
→ "Bloquea merges desde el primer review (frustrante)"
→ "Aplica reglas genéricas, no las del equipo"
→ "Para PRs grandes, falla o gasta demasiado"

DESPUÉS del módulo:
→ Comentarios inline en la línea exacta del problema
→ Suggest-only mode hasta que el equipo confíe
→ Aplica convenciones específicas del proyecto
→ Maneja PRs grandes con chunking eficiente

Trampas a Evitar al Cursar Este Módulo

Cinco malentendidos previsibles que vale la pena anticipar.

1. "El bot debe bloquear merges desde el día 1"

No. Un bot que bloquea merges sin que el equipo confíe en él genera frustración y workarounds. La gente empieza a marcar el bot como "ignorar" o a hacer commits con [skip ci]. La cápsula 04 desarrolla suggest-only mode como punto de partida — el bot comenta, no bloquea — y cómo evolucionar hacia bloqueo selectivo (solo en issues críticos como SQL injection) cuando el equipo ya confía en el output.

2. "Un comentario general al final del PR es suficiente"

No. Los developers escanean los PRs línea por línea. Un comentario al final que dice "encontré 3 problemas, ver líneas 45, 67 y 89" obliga al developer a saltar entre el comentario y el código. Comentarios inline en la línea exacta se ven y se accionan inmediatamente. La cápsula 03 te enseña a generarlos con la GitHub API.

3. "Convenciones genéricas son suficientes"

No. Si el bot aplica convenciones genéricas ("usa snake_case en Python"), el equipo lo va a percibir como ruido — porque cada equipo tiene matices: "snake_case excepto para los handlers que vienen del legacy", "TypeScript pero con camelCase para variables y PascalCase para tipos", etc. La cápsula 05 te muestra cómo personalizar via CLAUDE.md para que las convenciones sean del equipo, no genéricas.

4. "Un PR de 50 archivos lo proceso de una vez"

No. Pasar 50 archivos al modelo en un solo prompt:

  • Sobrepasa el context window útil (degradación de calidad — Módulo 6 de Guía 8)
  • Cuesta mucho dinero (token-heavy)
  • Genera comentarios genéricos porque el modelo no puede prestar atención a todo

La cápsula 06 te da estrategias de chunking: por archivo, por feature, con priorización de archivos relevantes (los que más cambiaron, los que tocan código crítico).

5. "Inline comments funcionan igual que comments normales"

No. Crear inline comments via API requiere especificar path, line, commit_id, y a veces start_line para multi-line. Los errores son comunes: línea fuera de rango, archivo binario, conflictos de merge. La cápsula 03 te enseña los detalles del API y cómo manejar errores.

Diagnóstico: ¿Cuál es tu Punto de Partida?

Cinco preguntas para calibrar antes de empezar.

Pregunta 1: ¿Has usado un bot de code review antes (Codecov, SonarQube, Snyk, etc.)? ¿Cuál fue tu experiencia?

Si la experiencia fue positiva: este módulo te da algo más profundo: review con contexto del proyecto, no solo reglas universales.

Si fue negativa (ruido, falsos positivos): la cápsula 04 (suggest-only) y 05 (convenciones) son específicamente para evitar esos problemas.

Pregunta 2: ¿Sabes la diferencia entre un comentario general del PR y un inline comment?

Si sí: la cápsula 03 formaliza la implementación con la API.

Si no: un inline comment va en una línea específica de un archivo específico (lo ves al lado del código). Un comentario general aparece al final del PR. Inline = más accionable.

Pregunta 3: ¿Tu proyecto tiene un CLAUDE.md o documento de convenciones para AI tools?

Si sí: la cápsula 05 te muestra cómo conectarlo con el bot.

Si no: el bot va a aplicar convenciones genéricas. Considera crear un CLAUDE.md mínimo antes de la cápsula 05 (Módulo 6 de Guía 8 te enseña).

Pregunta 4: ¿Qué pasaría si el bot empieza a bloquear merges desde el primer día?

Si dijiste "el equipo se frustraría": vas con el modelo mental correcto. La cápsula 04 (suggest-only mode) es la respuesta.

Si dijiste "estaría bien, así aprenden": la trampa #1 te aplica. Los bots que bloquean sin confianza se desactivan.

Pregunta 5: ¿Has visto un PR con 50+ archivos? ¿Cómo lo manejaría tu bot?

Si tienes una respuesta: la cápsula 06 valida o refina tu approach.

Si no has pensado en eso: los PRs grandes son donde la mayoría de los bots fallan (por costo o calidad). La cápsula 06 te da estrategias.

Si dudaste en 3 o más: este módulo es prioritario. Si respondiste todas con criterio, úsalo enfocado en la cápsula 06 (PRs grandes), que casi nadie domina al inicio.

Conexión con el Proyecto Final

En el Módulo 6 (Proyecto Integrador), el bot de code review es uno de los steps más visibles del pipeline completo. Es la feature que el equipo ve en cada PR — los comentarios automáticos del agente. Sin este módulo funcional, el pipeline integrador queda con un step crítico vacío.

Cómo Trabajar Este Módulo

  1. La cápsula 02 es la más mecánica. Léela con un PR abierto en tu repo de pruebas para hacer cada paso.
  2. La cápsula 03 es donde el módulo se vuelve visible. Inline comments aparecen en el PR — ese es el feedback inmediato.
  3. La cápsula 04 es la más estratégica. Cómo el bot se inserta en la cultura del equipo importa más que la implementación técnica.
  4. La cápsula 05 transforma el bot de genérico a específico. Sin convenciones del equipo, el bot pierde valor rápido.
  5. La cápsula 06 es la que escala el bot a la realidad. Los PRs grandes son donde la mayoría de los bots se rompen.

Tiempo estimado:

Cápsula 01 (esta)  →  10 min lectura
Cápsula 02         →  20 min + práctica
Cápsula 03         →  25 min + práctica con la API
Cápsula 04         →  15 min + configuración
Cápsula 05         →  20 min + escribir CLAUDE.md
Cápsula 06         →  20 min + estrategias de chunking

Total: ~1.75-2 horas

Evidencia de Éxito

Antes de avanzar al Módulo 3 (GitLab CI/CD y SDK Headless), deberías poder:

  • ✅ Disparar el bot automáticamente en eventos de PR (opened, synchronize)
  • ✅ Extraer el diff del PR y pasarlo al modelo de forma eficiente
  • ✅ Generar inline comments en líneas específicas usando la GitHub API
  • ✅ Producir un review summary al final del review con los hallazgos principales
  • ✅ Operar en suggest-only mode sin bloquear merges en el primer setup
  • ✅ Personalizar convenciones del proyecto usando CLAUDE.md
  • ✅ Manejar un PR grande (30+ archivos) con chunking sin saturar costos

Si alguno no se cumple al final, regresa a la cápsula correspondiente. El Módulo 3 (portabilidad cross-platform) asume que ya tienes un bot funcional en GitHub para portarlo a GitLab.

Resumen

  • Este módulo te da el resultado más visible de toda la guía: comentarios automáticos en cada PR
  • Code review con contexto, no linter — Claude Code entiende qué hace el código, no solo si sigue reglas
  • Inline comments son la diferencia entre "feedback que se acciona" y "feedback que se ignora"
  • Suggest-only mode es el punto de partida correcto — bloquear sin confianza genera workarounds
  • Convenciones específicas del equipo transforman el bot de genérico a invaluable
  • Chunking inteligente maneja PRs grandes sin saturar costos
  • La diferencia entre los "3 días con 2.5h de reviewer humano" y "5 horas con 20 min" del escenario inicial es exactamente este módulo

Siguiente cápsula: 02 — Triggers de PR y extracción del diff. Empezamos por el primer paso técnico: configurar los triggers correctos del workflow y extraer el diff del PR de forma eficiente para que Claude Code pueda razonar sobre él.

Recursos Adicionales

  1. GitHub Pull Request API — Referencia de la REST API para PRs
  2. GitHub PR Review Comments API — Específicamente para inline comments
  3. GitHub Actions: pull_request events — Triggers disponibles
  4. Octokit — Librería oficial para GitHub API en JS/TS
  5. PyGithub — Librería para GitHub API en Python
  6. Anthropic API for Code Review — Casos de uso oficiales
← AnteriorCostos y Rate LimitingSiguiente →Triggers de PR y Extracción del Diff