Módulo 2: Mental Models para AI Code

Descripción de la cápsula

En el módulo anterior entendiste el problema: solo el 3% de developers confía altamente en código AI, y la solución no es aceptar todo ni rechazar todo, sino desarrollar confianza calibrada. Terminaste con un framework básico de verificación — Red Zone, Yellow Zone, Green Zone. Ese framework te dice qué revisar. Pero no te dice cómo pensar mientras revisas.

Este módulo te da algo más poderoso que un checklist: mental models. Un mental model es un marco de pensamiento que te permite tomar buenas decisiones en situaciones nuevas — incluso en situaciones que ningún checklist podría anticipar. Un developer con mental models puede navegar cualquier escenario de AI code. Un developer con solo un checklist está limitado a lo que ese checklist cubre.

Vas a aprender 3 mental models complementarios que, juntos, cubren todas las decisiones que tomas al trabajar con código generado por AI. Piensa en ellos como el "sistema operativo" sobre el cual corren todas las técnicas que aprenderás en el resto de la guía.

Contexto del Módulo

¿Dónde estamos?

Estás en el Módulo 2 de la guía "Debugging & Code Review with Claude Code", dentro de la Phase 1: Entender el Problema.

Phase 1: Entender el Problema
├── Módulo 1: Solo 3% Confía ← completado
│   └── Awareness + framework básico de verificación
│   └── Cápsulas: estadística, extremos, confianza calibrada, framework
├── Módulo 2: Mental Models ← estás aquí
│   └── Frameworks de pensamiento para supervisar AI code
│   └── Cápsulas: intro, MIT, Circuit Breaker, Trust Calibration, ejercicio
└── Módulo 3: Detectar Hallucinations → siguiente
    └── El error más peligroso y sutil de AI code

El módulo 1 te dio awareness y un primer framework de verificación. Este módulo eleva tu pensamiento: en vez de seguir una lista, internalizas modelos mentales que guían todas tus decisiones. El módulo 3 aplicará estos modelos al tipo de error más sutil y peligroso: hallucinations — código que se ve correcto pero no lo es.

La transición: de framework a mental models

En el módulo 1, tu framework de 3 zonas te dice:

🔴 Red Zone: Siempre revisa (seguridad, lógica de negocio, datos)
🟡 Yellow Zone: Frecuentemente revisa (edge cases, error handling)
🟢 Green Zone: Confía generalmente (boilerplate, formateo, docs)

Pero cuando estás frente a código real, surgen preguntas que el framework no responde:

"Este endpoint tiene auth y CRUD. ¿Reviso todo como Red Zone o solo la parte de auth?"
"Claude Code generó 5 archivos. ¿Los reviso todos de golpe o uno por uno?"
"Esta función se ve simple pero toca lógica de negocio. ¿Cuánto confío?"
"Encontré un issue en el archivo 2. ¿Sigo revisando el 3 o me detengo?"

Los mental models responden estas preguntas. El framework del módulo 1 es el "qué." Los mental models de este módulo son el "cómo", "cuándo", y "cuánto."

¿Por qué mental models antes de técnicas?

Podrías pensar: "Ya tengo un checklist del módulo 1, dame más técnicas." El problema es que las técnicas sin criterio son peligrosas. Si alguien te da un checklist de 50 items para code review, ¿los aplicas todos a cada línea? ¿Cuáles saltas? ¿Cuándo profundizas?

Los mental models responden esas preguntas. Son el criterio que te permite decidir cuándo aplicar cada técnica, con qué profundidad, y cuándo parar. Sin ellos, los módulos 3-7 serían una colección de técnicas sin un hilo conductor.

Piensa en la diferencia entre un chef y alguien que sigue recetas:

Developer con solo técnicas (sigue recetas):
├── Tiene un checklist de 50 items
├── Los aplica mecánicamente a todo
├── Gasta 30 minutos en un README
├── Gasta 30 minutos en auth middleware
├── No sabe cuándo puede saltar items
└── Se pierde cuando la situación no encaja en el checklist

Developer con mental models (chef):
├── Tiene los mismos 50 items disponibles
├── Sabe cuáles aplicar a cada tipo de código
├── Gasta 2 minutos en un README, 30 en auth
├── Adapta su proceso a cada situación
├── Puede navegar escenarios que no están en el checklist
└── Su criterio mejora con experiencia

Los 3 Mental Models

Vista general

Los 3 modelos que vas a aprender son complementarios — cada uno responde una pregunta diferente:

Mental Model	Pregunta que responde	Metáfora	Cápsula
Managing an Intern (MIT)	¿Cómo superviso?	Claude Code es un intern brillante	02
Circuit Breaker	¿Cuándo me detengo a verificar?	Checkpoints de seguridad	03
Trust Calibration	¿Cuánto confío en esta tarea?	Termómetro de confianza	04

Managing an Intern (MIT)

El modelo más intuitivo. La idea central: Claude Code es como un intern brillante que sabe muchos lenguajes y frameworks, trabaja increíblemente rápido, pero no entiende tu negocio, no sabe por qué se tomaron ciertas decisiones, y a veces inventa cosas que suenan plausibles.

Un buen manager de intern:
├── Supervisa las decisiones importantes
├── Delega el trabajo routine
├── Verifica la lógica de negocio
├── No micro-managea cada variable
└── Da contexto que el intern no tiene

Lo mismo aplica con Claude Code:
├── Supervisa lógica de negocio y seguridad
├── Delega boilerplate y formateo
├── Verifica que el código cumple los requisitos
├── No revisa cada import statement
└── Proporciona contexto en el prompt

Circuit Breaker

Adaptado del patrón de software engineering. En sistemas distribuidos, un Circuit Breaker detiene los requests cuando un servicio falla para evitar cascadas. Aplicado a code review: defines checkpoints donde pausas y verificas antes de continuar. Si algo falla, te detienes — no sigues generando código sobre una base defectuosa.

Sin Circuit Breaker:
Genera 5 archivos → Acepta todos → Descubre bug en archivo 2
→ Archivos 3, 4, 5 basados en código buggy → Revert completo

Con Circuit Breaker:
Genera archivo 1 → Checkpoint ✅ → Genera archivo 2 → Checkpoint ❌
→ Corrige archivo 2 → Regenera 3, 4, 5 sobre base correcta

Trust Calibration

El modelo más accionable. Convierte "creo que está bien" en un proceso estructurado. Para cada tipo de tarea, defines un nivel de confianza que determina tu profundidad de revisión.

Trust Calibration en acción:

Boilerplate setup   → 85% → Revisión visual (1-2 min)
CRUD endpoint       → 65% → Revisión enfocada (5-8 min)
Business logic      → 30% → Revisión exhaustiva (15-20 min)
Auth/Security       → 15% → Línea por línea + docs (20-30 min)
Payment processing  → 10% → Todo + tests + compliance (30+ min)

Cómo se complementan

Imagina que Claude Code acaba de generar 3 archivos para una feature nueva. ¿Qué haces?

1. Trust Calibration → ¿Cuánto confío en cada archivo?
   "models.py: 80% (modelos de datos, routine)
    service.py: 35% (lógica de negocio, necesito verificar)
    routes.py: 55% (endpoints, revisar auth y validaciones)"

2. Managing an Intern → ¿Cómo reviso cada uno?
   "models.py: Revisión visual — campos y tipos correctos?
    service.py: Las 5 preguntas del manager — cada una
    routes.py: Verificar auth en endpoints sensibles"

3. Circuit Breaker → ¿Cuándo pauso?
   "Checkpoint después de models.py → si los modelos están mal,
    service.py y routes.py están basados en modelos incorrectos.
    Checkpoint después de service.py → si la lógica está mal,
    routes.py expone lógica defectuosa."

Sin los 3 modelos, tu revisión es inconsistente — a veces revisas demasiado, a veces muy poco, y no tienes un criterio para saber cuál es cuál.

Progresión del Módulo

Mapa del Módulo

Cápsula	Tema	Qué aprenderás	Tipo
02	Managing an Intern (MIT)	Cómo supervisar AI code sin micro-manage ni abandonar	Técnica
03	Circuit Breaker	Cuándo pausar y verificar — checkpoints para tu flujo	Técnica
04	Trust Calibration	Cuánto confiar por tipo de tarea — la tabla que usas diario	Técnica
05	Ejercicio Integrador	Aplicar los 3 modelos a escenarios reales con código	Ejercicio

Flujo de aprendizaje

Empiezas con el modelo más intuitivo: Managing an Intern (cápsula 02). La metáfora es poderosa — si alguna vez supervisaste a alguien junior, ya entiendes el 80% del modelo. Después aprendes Circuit Breaker (cápsula 03), que te da la disciplina de pausar en puntos clave en vez de aceptar todo de golpe. Luego Trust Calibration (cápsula 04), que te da la herramienta más accionable: una tabla detallada con 15 tipos de tarea y su nivel de confianza recomendado. Finalmente, el ejercicio integrador (cápsula 05) te hace aplicar los 3 modelos juntos a 3 escenarios reales con código Python/FastAPI.

La progresión es: cómo supervisar → cuándo pausar → cuánto confiar → aplicar todo junto.

Dependencias entre cápsulas

Las cápsulas se construyen unas sobre otras:

Cápsula 02 (MIT) ─────────┐
                            ├── Cápsula 05 (Ejercicio)
Cápsula 03 (Circuit Breaker)├── Aplica los 3 modelos
                            │   a código real
Cápsula 04 (Trust Cal.) ───┘

Puedes leer las cápsulas 02, 03, y 04 en cualquier orden — son independientes. Pero la cápsula 05 requiere haber completado las tres.

Objetivo Profesional

Al final de este módulo podrás:

✅ Explicar el modelo Managing an Intern y aplicarlo: qué supervisas, qué delegas, cómo revisas
✅ Definir Circuit Breakers en tu flujo de trabajo: checkpoints concretos donde pausas y verificas
✅ Calibrar confianza por tipo de tarea: "para boilerplate confío 80%, para auth confío 15%"
✅ Aplicar los 3 modelos juntos a un escenario real de generación de código con Claude Code
✅ Adaptar los modelos a tu contexto específico (no son reglas rígidas, son frameworks)
✅ Documentar tu proceso de validación de forma reproducible

Conexión con Proyecto

Cómo se conecta con el proyecto integrador (Módulo 8)

Los mental models son la base del proyecto integrador. En el módulo 8 recibirás un codebase FastAPI con problemas reales plantados y tu trabajo será hacer code review profesional. Usarás estos modelos así:

Managing an Intern: Para decidir qué partes del codebase revisar con profundidad y cuáles solo necesitan un vistazo. No vas a revisar cada import — vas a enfocarte en lógica de negocio y decisiones de arquitectura.
Circuit Breaker: Para estructurar tu revisión en checkpoints. Archivo por archivo, no todo de golpe. Si encuentras algo grave, paras y documentas antes de seguir.
Trust Calibration: Para ajustar la profundidad de revisión por módulo. El CRUD básico recibe revisión rápida; el módulo de auth recibe revisión exhaustiva.

Anticipación

Sin estos modelos, el proyecto del módulo 8 se vuelve caótico — revisas todo con la misma profundidad y te toma 3x más tiempo sin encontrar los issues que importan. Con ellos, tu revisión es eficiente y efectiva: más issues encontrados en menos tiempo.

La diferencia cuantificable:

Sin mental models (módulo 8):
├── Tiempo: 3-4 horas
├── Issues encontrados: 8-10 de 20
├── Priorización: ninguna
└── Resultado: revisión incompleta y agotadora

Con mental models (módulo 8):
├── Tiempo: 1.5-2 horas
├── Issues encontrados: 15-18 de 20
├── Priorización: críticos primero, menores después
└── Resultado: revisión completa y eficiente

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

❌ Técnicas específicas de detección — Detectar hallucinations es el módulo 3. Aquí construyes frameworks de pensamiento, no técnicas de detección.
❌ Checklist de code review — El checklist profesional completo de 15+ items es el módulo 4. Aquí aprendes el criterio para priorizar qué items del checklist aplicar.
❌ Debugging de errores — Debugging con Claude Code es el módulo 6. Aquí aprendes a pensar sobre AI code, no a debuggearlo.
❌ Reglas rígidas — Los mental models no son reglas. Son lentes para pensar. Si los tratas como reglas, pierdes su valor porque no se adaptan a tu contexto.

Antes de Empezar: Un Autodiagnóstico

Antes de entrar en los modelos, evalúa cómo supervisas AI code hoy:

¿Cómo revisas código de Claude Code actualmente?

A. "Reviso todo con la misma profundidad"
   → Estás gastando tiempo donde no agrega valor
   → Necesitas: Trust Calibration (cápsula 04)

B. "A veces reviso mucho, a veces nada — depende del día"
   → Tu supervisión es inconsistente
   → Necesitas: Los 3 modelos para tener criterio estable

C. "Reviso lo que se siente importante"
   → Tu intuición puede ser buena, pero no es comunicable
   → Necesitas: Convertir intuición en proceso

D. "Acepto si funciona, reviso si falla"
   → Estás en modo reactivo — los bugs llegan a producción
   → Necesitas: Circuit Breaker (cápsula 03)

E. "Tengo un proceso diferenciado por tipo de tarea"
   → Ya tienes una base. Los modelos la van a formalizar
   → Aprovecha los ejercicios para refinar tu proceso

No hay respuesta "mala." Lo que importa es que al final del módulo, tu respuesta sea E — con un proceso que puedes explicar, enseñar, y mejorar con experiencia.

Qué necesitas para este módulo

Requisitos:
├── ✅ Haber completado el módulo 1 (confianza calibrada)
├── ✅ Experiencia básica con Claude Code o AI coding tools
├── ✅ Familiaridad con Python/FastAPI (para los ejercicios)
└── ✅ Disposición a cambiar cómo piensas sobre code review

No necesitas:
├── ❌ Experiencia como manager (la metáfora es intuitiva)
├── ❌ Conocimiento de Circuit Breaker pattern en software
└── ❌ Haber trabajado con todos los tipos de código que se cubren

Nota sobre Mental Models

Qué son y qué no son

Los mental models no son reglas que sigues mecánicamente. Son frameworks de pensamiento que internalizas con práctica. La diferencia es importante:

Regla: "Siempre revisa los imports."
→ La aplicas sin pensar.
→ No se adapta al contexto.
→ Puede ser excesiva (imports estándar) o insuficiente 
  (imports de librerías que podrían ser hallucinations).

Mental model: "Supervisa como un buen manager supervisa a un intern."
→ Lo interpretas según el contexto.
→ Se adapta a cualquier situación nueva.
→ Mejora con experiencia — cada revisión te enseña algo.

Un developer con mental models puede navegar situaciones que nunca ha visto antes, porque el modelo le da un marco para pensar. Un developer con solo reglas se paraliza cuando la situación no encaja en una regla existente.

Cómo internalizarlos

Los mental models se internalizan con práctica, no con lectura. Por eso:

Cada cápsula técnica (02, 03, 04) tiene 4-5 ejercicios con código real
La cápsula 05 es un ejercicio integrador completo con 3 escenarios de complejidad creciente
El ejercicio extra de la cápsula 05 te pide generar código real con Claude Code y aplicar los 3 modelos

La lectura te da comprensión. Los ejercicios te dan internalización. El proyecto del módulo 8 te da maestría.

Progresión de internalización:

Lectura (cápsulas 02-04):
"Entiendo los modelos conceptualmente"

Ejercicios (cápsulas 02-04):
"Puedo aplicar cada modelo por separado"

Ejercicio integrador (cápsula 05):
"Puedo aplicar los 3 modelos juntos"

Ejercicio extra (cápsula 05):
"Puedo aplicar los modelos a MI código"

Proyecto (módulo 8):
"Los modelos son parte de cómo pienso"

Evidencia de Éxito

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

✅ Puedes explicar cada modelo en una frase y dar un ejemplo concreto
✅ Cuando Claude Code genera código, automáticamente piensas en los 3 modelos
✅ Tu revisión de AI code es más eficiente: menos tiempo total, más issues encontrados
✅ Puedes justificar por qué revisas algo con profundidad y por qué confías en otra cosa
✅ Aplicaste los 3 modelos a un escenario real y documentaste el proceso
✅ Puedes adaptar los modelos a situaciones que no se cubrieron en las cápsulas

La prueba definitiva: si alguien te pregunta "¿por qué aceptaste este código sin revisión exhaustiva?", puedes dar una respuesta articulada: "Es CRUD estándar (Trust Calibration: 70%), revisé validaciones y error handling (MIT Nivel 2), y mi checkpoint pasó sin issues (Circuit Breaker)."

Comparación: antes y después del módulo

Antes del módulo (revisión sin modelos):
├── Revisas "lo que se te ocurre"
├── Gastas 20 min en un README
├── Gastas 5 min en auth middleware
├── No puedes explicar por qué revisaste X y no Y
├── Tu proceso cambia según tu energía del día
└── Resultado: revisión inconsistente, issues se escapan

Después del módulo (revisión con modelos):
├── Trust Calibration te dice la profundidad
├── 2 min en README (confianza 85%)
├── 25 min en auth middleware (confianza 15%)
├── Puedes justificar cada decisión de revisión
├── Tu proceso es estable independientemente del día
└── Resultado: revisión eficiente, issues críticos detectados

Resumen

Este módulo te da 3 mental models para supervisar AI-generated code
Los modelos son complementarios: cómo supervisar (MIT), cuándo pausar (Circuit Breaker), cuánto confiar (Trust Calibration)
Son frameworks de pensamiento, no reglas — se adaptan a tu contexto y mejoran con experiencia
Los mental models son el "sistema operativo" sobre el cual corren todas las técnicas de los módulos 3-7
En el proyecto integrador (módulo 8) usarás los 3 modelos para hacer code review eficiente de un codebase completo
La progresión del módulo: cómo supervisar → cuándo pausar → cuánto confiar → aplicar todo junto
Se internalizan con práctica: ejercicios en cada cápsula + ejercicio integrador + proyecto

Recursos Adicionales

Mental Models — Farnam Street - Colección curada de mental models para pensamiento claro y toma de decisiones
The Manager's Path — Camille Fournier - Cómo managers efectivos supervisan sin micro-manage
Circuit Breaker Pattern — Martin Fowler - El pattern original de software engineering adaptado a code review
Thinking in Bets — Annie Duke - Calibración de confianza y toma de decisiones bajo incertidumbre
Anthropic — Claude Code Best Practices - Documentación oficial de Claude Code

Siguiente cápsula: Managing an Intern (MIT) — el modelo más intuitivo para supervisar AI code.

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

← AnteriorTu Primer Framework de Verificación Siguiente →Managing an Intern (MIT)