Módulo 4: Code Review de Output AI

Módulo 4: Code Review de Output AI

Siguiente →

Módulo 4: Code Review de Output AI

Descripción de la cápsula

Hasta ahora construiste awareness (módulo 1), frameworks mentales (módulo 2), y detección de hallucinations (módulo 3). Entiendes el problema, tienes herramientas de pensamiento, y sabes detectar el error más sutil. Ahora toca el siguiente paso: tener un proceso profesional de code review diseñado específicamente para código generado por AI.

Este módulo abre la Phase 2 (Code Review Profesional) y marca la transición más importante de la guía: pasas de "entiendo el problema" a "tengo herramientas para resolverlo." Al final de este módulo tendrás un checklist profesional de 15+ items, sabrás priorizar qué revisar cuando el tiempo es limitado, reconocerás red flags específicos de AI-generated code, y habrás completado un code review real de un PR generado por Claude Code.

La diferencia clave: el code review de código humano y el code review de código AI no son lo mismo. Con código humano, confías en que el developer entiende el contexto de negocio y revisas la implementación. Con código AI, no puedes confiar en que el modelo entiende el contexto — debes verificar que la implementación coincide con tu intención. Eso cambia las prioridades, los red flags, y el proceso entero.

Contexto del Módulo

¿Dónde estamos?

Estás en la Phase 2 de la guía, que cubre code review profesional y debugging. La Phase 1 te dio el fundamento:

Phase 1 (Completada)Lo que ganaste
Módulo 1: Solo 3% ConfíaAwareness del problema + confianza calibrada
Módulo 2: Mental ModelsManaging an Intern, Circuit Breaker, Trust Calibration
Módulo 3: HallucinationsDetección de imports falsos, APIs inventadas, lógica fabricada

Ahora en Phase 2 construyes las herramientas prácticas:

Phase 2 (Actual)Lo que ganarás
Módulo 4: Code Review de Output AIChecklist profesional + proceso de revisión
Módulo 5: Patrones de Error ComunesPattern recognition para errores frecuentes
Módulo 6: Debugging con Claude CodeDebugging sistemático con AI como herramienta

¿Por qué code review es la habilidad central?

Todo lo demás — patrones de error, debugging, regenerar vs editar — son extensiones del code review. Si sabes revisar código AI con criterio, los patrones de error los detectas durante el review. El debugging lo aplicas cuando el review encuentra algo sospechoso. La decisión de regenerar vs editar la tomas después de un review. Code review es el hub que conecta todas las habilidades de esta guía.

Objetivo Profesional

Al final de este módulo podrás:

  • ✅ Priorizar qué revisar con la pirámide: seguridad → lógica de negocio → edge cases → performance → estilo
  • ✅ Usar un checklist profesional de 15+ items específicos para código AI
  • ✅ Reconocer red flags que solo aparecen en código generado por AI (no en código humano)
  • ✅ Verificar lógica de negocio: que el código haga exactamente lo que el negocio necesita
  • ✅ Completar un code review profesional de un PR generado por Claude Code

Progresión del Módulo

Mapa del Módulo

CápsulaTemaQué aprenderás
02Qué Buscar PrimeroPirámide de prioridades: si solo tienes 5 minutos, qué revisas
03Checklist de Code Review AI15-20 items accionables agrupados por categoría
04Red Flags en Código AISeñales específicas de AI: sobre-ingeniería, APIs obsoletas, abstracciones fantasma
05Verificar Lógica de NegocioEl review más difícil: confirmar que el código hace lo que el negocio necesita
06Ejercicio: Code Review de un PRReview completo de un PR realista generado por Claude Code

Flujo de aprendizaje

Primero aprendes a priorizar — porque no puedes revisar todo y necesitas saber dónde invertir tu tiempo limitado (cápsula 02). Después construyes tu checklist profesional con items específicos y verificables, agrupados por categoría (cápsula 03). Con el checklist listo, profundizas en los red flags que son exclusivos de código AI — cosas que no existen en code review de código humano (cápsula 04). Luego abordas la parte más difícil: verificar que la lógica de negocio es correcta, algo que ningún linter detecta (cápsula 05). Finalmente, aplicas todo en un code review real de un PR con una mezcla de código bueno y problemas sutiles (cápsula 06).

Code Review Humano vs Code Review AI

Antes de entrar en las cápsulas, necesitas entender por qué este módulo existe como algo separado del code review tradicional.

Lo que es igual

Tanto en código humano como en AI:
├── La seguridad es prioridad #1
├── Los edge cases necesitan cobertura
├── El error handling debe ser completo
├── Los tests deben verificar comportamiento real
└── El código debe ser mantenible

Lo que es diferente

En código HUMANO:
├── Confías en que el dev entiende el negocio → revisas implementación
├── Red flags: complejidad excesiva, deep nesting, code smells
├── Los errores son de lógica o distracción
├── El dev puede explicar sus decisiones si preguntas
└── El contexto del proyecto está en la mente del dev

En código AI:
├── NO confías en que AI entiende el negocio → verificas intención
├── Red flags: sobre-ingeniería, APIs obsoletas, abstracciones fantasma
├── Los errores son de "confianza sin comprensión"
├── AI no puede explicar por qué eligió un approach
└── El contexto se pierde entre prompts

Ejemplo concreto

Le pides a un developer humano: "Implementa descuento por volumen: 10% si compra más de 10 unidades."

El developer entiende que "más de 10" significa quantity > 10 y que el descuento aplica al total. Si se equivoca, probablemente sea un off-by-one (>= vs >).

Le pides a Claude Code lo mismo. El código puede:

  • Aplicar el descuento al precio unitario en vez del total
  • Usar >= en vez de > (o viceversa)
  • Crear una tabla de descuentos completa con 5 niveles que nadie pidió
  • Aplicar el descuento solo a las unidades extra (después de las 10 primeras)
  • Funcionar perfectamente para el caso base pero fallar cuando quantity es 0

Cada una de esas variaciones se ve profesional. El código compila, los tests triviales pasan, el linter está feliz. Solo un humano que entiende el negocio detecta que el descuento aplica al total, no al precio unitario.

Las consecuencias de no hacer code review de AI

Considera este escenario real:

from fastapi import FastAPI, HTTPException
from decimal import Decimal

app = FastAPI()

SUBSCRIPTION_PRICES = {
    "basic": Decimal("9.99"),
    "pro": Decimal("29.99"),
    "enterprise": Decimal("99.99"),
}


@app.post("/subscriptions/upgrade")
async def upgrade_subscription(
    user_id: str,
    new_plan: str,
):
    user = get_user(user_id)
    current_plan = user["plan"]
    
    current_price = SUBSCRIPTION_PRICES[current_plan]
    new_price = SUBSCRIPTION_PRICES[new_plan]
    
    prorate = new_price - current_price
    
    charge_user(user_id, prorate)
    update_plan(user_id, new_plan)
    
    return {"status": "upgraded", "charged": float(prorate)}

A primera vista, este código se ve correcto. Calcula la diferencia de precio y cobra el prorrateo. Pero:

¿Qué pasa si new_plan == current_plan? → Cobra $0 y "upgradea" al mismo plan.
¿Qué pasa si hace downgrade? (enterprise → basic) → prorate es negativo → ¿cobra -$90?
¿Qué pasa si new_plan no está en SUBSCRIPTION_PRICES? → KeyError no manejado.
¿El prorrateo considera días restantes del ciclo? → No, cobra la diferencia completa.
¿Hay auth? → No. Cualquiera puede cambiar el plan de cualquier usuario.

Cinco problemas en 20 líneas de código que pasan linter, pasan tests triviales, y se ven profesionales. Sin code review, esto llega a producción. Con code review, los encuentras en 5 minutos.

Qué Vas a Construir en Este Módulo

Los 4 artefactos

A lo largo de las 5 cápsulas siguientes, construirás 4 artefactos que usarás el resto de tu carrera:

ARTEFACTOS DEL MÓDULO 4:

1. PIRÁMIDE DE PRIORIDADES (Cápsula 02)
   └── Qué revisar primero cuando el tiempo es limitado
   └── Seguridad → Lógica → Edge Cases → Performance → Estilo
   └── Distribución de tiempo según disponibilidad (5/15/30 min)

2. CHECKLIST PROFESIONAL (Cápsula 03)
   └── 20 items específicos y verificables
   └── Agrupados por: Seguridad, Lógica, Edge Cases, AI-Specific, Calidad
   └── Cada item con: qué verificar, cómo verificar, ejemplo de falla

3. CATÁLOGO DE RED FLAGS (Cápsula 04)
   └── 8 red flags exclusivos de código AI
   └── Sobre-ingeniería, APIs anteriores, abstracciones fantasma
   └── Confianza sin correctitud, mezcla de frameworks
   └── Regla de detección rápida para cada red flag

4. PROCESO DE VERIFICACIÓN DE LÓGICA (Cápsula 05)
   └── 4 pasos: requisitos → trazar → verificar → edge cases
   └── La parte más difícil y más importante del review
   └── Ninguna herramienta automática lo hace por ti

Cómo se conectan

Pirámide de Prioridades
      ↓ (te dice QUÉ revisar primero)
Checklist Profesional
      ↓ (te dice CÓMO revisar cada categoría)
Catálogo de Red Flags
      ↓ (te dice QUÉ BUSCAR específicamente en código AI)
Verificación de Lógica
      ↓ (te dice CÓMO VERIFICAR la parte más difícil)
Ejercicio: PR Review
      ↓ (aplicas TODO junto en un escenario real)

La Realidad del Code Review con AI en la Industria

Lo que hacen la mayoría de developers

Developer promedio con AI:
1. Pide código a Claude Code
2. Mira que "se ve bien"
3. Ejecuta y funciona → merge
4. Problemas aparecen en producción días/semanas después

Lo que hacen los profesionales

Developer profesional con AI:
1. Pide código a Claude Code
2. Aplica pirámide: seguridad primero
3. Ejecuta checklist: items específicos por categoría
4. Busca red flags de AI: sobre-ingeniería, APIs viejas
5. Verifica lógica de negocio: ¿hace lo que el negocio necesita?
6. Documenta findings: severidad, categoría, corrección
7. Decisión: aprobar, editar, regenerar, o rechazar

La diferencia no es talento — es proceso. El developer profesional no es más inteligente. Tiene un sistema que le permite encontrar problemas de forma consistente. Eso es lo que construyes en este módulo.

¿Cuánto tiempo agrega al workflow?

Sin review: 0 minutos (pero pagas después en bugs y hotfixes)
Con review básico (pirámide + seguridad): 5-10 minutos
Con review completo (checklist + red flags): 15-25 minutos
Con review exhaustivo (+ lógica de negocio): 25-40 minutos

ROI estimado:
- 15 minutos de review ahora
- vs 2-4 horas de debugging un bug en producción
- vs días de incident response por un security breach

Conexión con Proyecto

Ejercicio de este módulo

Vas a hacer un code review completo de un PR generado por Claude Code. El PR tiene ~100 líneas de código FastAPI con una mezcla de código bueno y 6-8 problemas distribuidos en todas las categorías: seguridad, lógica de negocio, edge cases, y red flags de AI.

Conexión con el proyecto integrador (Módulo 8)

El checklist que construyes en este módulo es el artefacto más importante para el proyecto integrador. En el módulo 8, recibirás un codebase FastAPI completo con 15-20 problemas plantados. Tu checklist es tu herramienta principal para encontrarlos. Si tu checklist es bueno, encontrarás los problemas. Si es incompleto, los perderás.

Este móduloProyecto integrador (M8)
1 PR con 6-8 issuesCodebase completo con 15-20 issues
~100 líneas de código~500-800 líneas en 8-12 archivos
Checklist como herramienta de prácticaChecklist como herramienta de evaluación
30-45 minutos90-120 minutos

Límites: Qué NO Se Cubre en Este Módulo

  • ❌ Debugging paso a paso — Eso es el módulo 6. Aquí identificas problemas; allá los resuelves.
  • ❌ Patrones de error específicos con detalle — Eso es el módulo 5. Aquí tienes el checklist general; allá profundizas en cada tipo de error.
  • ❌ Cuándo regenerar vs editar — Eso es el módulo 7. Aquí haces el review; allá decides la acción correcta.
  • ❌ Code review genérico — Este módulo se enfoca en lo que es específico de AI-generated code. Las buenas prácticas generales de code review se asumen conocidas.

El Tono de Este Módulo

Este módulo tiene un tono profesional y metódico. No es improvisación — es proceso. Así trabajan los seniors: con un checklist, con prioridades claras, y con criterio para saber dónde invertir su tiempo limitado.

No vas a revisar cada línea con la misma intensidad. Vas a aprender a ser estratégico: dedicar 80% de tu atención al 20% del código que tiene mayor riesgo. Eso no es pereza — es profesionalismo. Un doctor no hace un examen completo cada vez que un paciente llega con dolor de cabeza. Evalúa síntomas, prioriza, y profundiza donde importa. Tú harás lo mismo con código AI.

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

  • ✅ Puedes recitar la pirámide de prioridades sin consultarla
  • ✅ Tu checklist tiene 15+ items que son específicos y verificables (no genéricos)
  • ✅ Puedes identificar al menos 5 red flags exclusivos de código AI
  • ✅ Puedes explicar por qué verificar lógica de negocio es la parte más difícil del review
  • ✅ Completaste el code review del PR con al menos 5 de los 6-8 issues documentados
  • ✅ Documentaste cada finding con severidad, categoría, y acción recomendada

Troubleshooting

Problema 1: "Ya hago code review — ¿por qué necesito un proceso diferente para AI?"

Causa: El code review tradicional asume que el autor entiende el contexto. Con AI, esa asunción no aplica. Solución: No reemplazas tu proceso actual — lo expandes. Los items de seguridad y edge cases son similares. Lo que agregas es: verificación de intención (¿resuelve MI problema?), red flags de AI (sobre-ingeniería, APIs viejas), y verificación de lógica de negocio (¿hace lo que el negocio necesita, no lo que AI cree que necesita?).

Problema 2: "Mi equipo no hace code review formal — ¿cómo aplico esto?"

Causa: Muchos equipos tienen procesos de review informales o inexistentes. Solución: Empieza contigo. Aplica el checklist a tu propio código AI antes de hacer commit. No necesitas un proceso formal de equipo para beneficiarte. Cuando tu código tenga menos bugs, el equipo notará y preguntará cómo.

Problema 3: "El checklist se siente burocrático — ¿no es más rápido 'solo revisar'?"

Causa: La revisión ad-hoc se siente más rápida pero es menos efectiva. Solución: "Solo revisar" funciona para developers con 10+ años de experiencia que han internalizado los checks. Para el resto, el checklist compensa la falta de experiencia con un proceso. Con el tiempo, internalizas el checklist y ya no necesitas consultarlo — pero sigue ejecutándose en tu cabeza.

Ejercicios

Ejercicio 1: Autodiagnóstico (Fácil)

Responde honestamente:

  1. Cuando Claude Code genera código, ¿cuánto tiempo dedicas a revisarlo antes de usarlo?

    • a) < 1 minuto
    • b) 1-5 minutos
    • c) 5-15 minutos
    • d) > 15 minutos

  2. ¿Tienes un proceso definido o revisas "por feeling"?

  3. ¿Has encontrado un bug en producción que venía de código generado por AI?

Ver reflexión

Si respondiste (a) a la primera pregunta, estás en el extremo de "acepto sin verificar." Si respondiste (d), podrías estar sobre-revisando. El punto óptimo depende del tipo de código:

  • Boilerplate/CRUD: 1-5 minutos (respuesta b)
  • Lógica de negocio: 5-15 minutos (respuesta c)
  • Seguridad/finanzas: 15+ minutos (respuesta d)

Si no tienes proceso definido (pregunta 2), este módulo te da uno. Si encontraste bugs de AI en producción (pregunta 3), este módulo te enseña a encontrarlos en review, no en producción.

Ejercicio 2: Clasificar revisiones (Fácil)

Para cada tipo de código, define cuánto tiempo dedicarías al review y por qué:

  1. Un endpoint GET que devuelve la versión de la API
  2. Un servicio que procesa pagos con tarjeta de crédito
  3. Una función que formatea fechas para display
  4. Un endpoint que permite a admins borrar cuentas de usuario
  5. Un archivo de configuración de logging
Ver solución

  1. Versión de API → 1 minuto. Zero riesgo. Review visual: ¿devuelve la versión correcta? ¿No expone info sensible?

  2. Pagos con tarjeta → 30-45 minutos. Máximo riesgo. Seguridad (PCI compliance, secrets), lógica (cálculos correctos, atomicidad), edge cases (monto negativo, timeout de API). Considerar: ¿debería revisar un segundo par de ojos?

  3. Formateo de fechas → 2-3 minutos. Bajo riesgo. Verificar: ¿maneja timezones? ¿Fechas inválidas? ¿El formato es el que necesita el frontend?

  4. Borrar cuentas → 15-20 minutos. Alto riesgo. Seguridad (¿solo admins?), lógica (¿soft delete o hard delete?), edge cases (¿qué pasa con los datos del usuario?), confirmación (¿hay doble confirmación?).

  5. Config de logging → 3-5 minutos. Bajo riesgo pero importante. ¿Loggea datos sensibles? ¿El nivel es correcto para producción? ¿Los logs van al lugar correcto?

Ejercicio 3: Identificar la diferencia (Medio)

Lee estos dos snippets. Uno fue escrito por un developer humano y otro por AI. ¿Cuál es cuál? ¿Cómo lo sabes?

Snippet X:

@app.post("/users")
async def create_user(user: UserCreate, db: Session = Depends(get_db)):
    existing = db.query(User).filter(User.email == user.email).first()
    if existing:
        raise HTTPException(status_code=409, detail="Email taken")
    
    new_user = User(**user.model_dump())
    new_user.password_hash = hash_password(user.password)
    db.add(new_user)
    db.commit()
    db.refresh(new_user)
    return new_user

Snippet Y:

@app.post("/users", response_model=UserResponse, status_code=201)
async def create_user(
    user: UserCreate,
    db: AsyncSession = Depends(get_async_session),
    background_tasks: BackgroundTasks = BackgroundTasks(),
):
    """Create a new user account with email verification."""
    existing = await db.execute(
        select(User).where(User.email == user.email)
    )
    if existing.scalar_one_or_none():
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="An account with this email already exists",
        )
    
    new_user = User(
        email=user.email,
        name=user.name,
        password_hash=hash_password(user.password),
        is_verified=False,
        created_at=datetime.now(timezone.utc),
    )
    db.add(new_user)
    await db.commit()
    await db.refresh(new_user)
    
    background_tasks.add_task(
        send_verification_email,
        email=new_user.email,
        user_id=str(new_user.id),
    )
    
    return new_user
Ver solución

Snippet X es más probable que sea humano. Es directo, sin extras. Hace exactamente lo que se pidió y nada más. Usa patrones simples (db.query en vez de select), no agrega funcionalidad extra.

Snippet Y es más probable que sea AI. Señales:

  • Agrega funcionalidad no pedida (email verification, background tasks)
  • Más verbose y "presentable" (docstring, status constants, mensajes detallados)
  • Usa async + SQLAlchemy 2.0 patterns (puede ser correcto, pero AI tiende a usar lo más moderno)
  • Agrega is_verified y created_at que nadie pidió explícitamente

Ambos snippets son funcionales. Pero Y tiene señales claras de AI: sobre-completitud, presentación profesional excesiva, y funcionalidad que anticipa necesidades futuras sin que se las pidan.

Nota: esta distinción no es 100% confiable. Un developer senior podría escribir como Y, y AI podría generar algo como X. El punto es desarrollar intuición para saber cuándo profundizar el review.

Resumen

  • Este módulo abre la Phase 2 y marca la transición de awareness a herramientas prácticas
  • Code review de AI ≠ code review de humano: prioridades diferentes, red flags diferentes, proceso diferente
  • Con código humano confías en el contexto del developer; con código AI verificas la intención
  • La pirámide de prioridades te dice qué revisar cuando el tiempo es limitado: seguridad > lógica > edge cases > performance > estilo
  • El checklist profesional es el artefacto que te llevas de este módulo y usas el resto de tu carrera
  • Los red flags de AI son conocimiento especializado que te diferencia de developers que solo revisan código humano
  • Verificar lógica de negocio es la parte más difícil: el linter no la detecta, los tests no la cubren
  • El ejercicio final es un code review real de un PR con problemas distribuidos en todas las categorías

Recursos Adicionales

  1. Google — Code Review Developer Guide - El estándar de la industria para code review, adaptable a código AI
  2. Anthropic — Claude Code Best Practices - Documentación oficial con recomendaciones de validación
  3. OWASP — Code Review Guide - Framework de code review con foco en seguridad
  4. Microsoft — Code Review Best Practices - Perspectiva de Microsoft sobre proceso de code review
  5. Stack Overflow — AI-Generated Code Survey 2024 - Datos sobre cómo developers manejan código AI

Siguiente cápsula: Qué Buscar Primero — la pirámide de prioridades que define dónde invertir tu tiempo limitado.

Debugging & Code Review with Claude Code — Módulo 4, Cápsula 01 Claude Code Agentic Development Path — Guía #6 de 11

← AnteriorEjercicio: Detectar Hallucinations en CódigoSiguiente →Qué Buscar Primero: La Pirámide de Prioridades