Módulo 6: Debugging con Claude Code

Descripción de la cápsula

Los módulos 4 y 5 te enseñaron a encontrar problemas mediante inspección estática — leer código, identificar patrones de error, aplicar checklists. Pero hay una categoría de problemas que no puedes encontrar solo leyendo: los que aparecen cuando el código se ejecuta. Un TypeError que solo ocurre con cierto input. Un endpoint que devuelve datos incorrectos pero solo cuando la base de datos tiene registros con cierto formato. Un timeout que aparece únicamente bajo carga.

Esos problemas requieren debugging — un proceso diferente al code review. Y Claude Code puede ser una herramienta extremadamente útil en ese proceso, pero solo si entiendes su rol correctamente. En este módulo vas a aprender a usar Claude Code como herramienta de debugging: pasarle logs, stack traces, y errores de runtime para obtener hipótesis de diagnóstico. Y lo más importante: vas a aprender a evaluar esas hipótesis, no a aceptarlas ciegamente.

Contexto del Módulo

¿Dónde estamos?

Este es el último módulo de la Phase 2 (Code Review Profesional). En el módulo 4 construiste un checklist profesional de code review. En el módulo 5 aprendiste a reconocer patrones de error comunes en código AI-generated. Ahora cierras la phase con la habilidad más práctica de todas: diagnosticar y resolver problemas que se manifiestan en runtime.

¿Hacia dónde vamos?

Después de este módulo, entras en la Phase 3: Mastery. El módulo 7 te dará herramientas avanzadas (subagents para investigación y el framework regenerar vs editar). El módulo 8 es el proyecto integrador donde aplicarás code review, debugging, y todas las técnicas aprendidas en un codebase con problemas reales.

La transición clave

Code review encuentra problemas potenciales. Debugging resuelve problemas reales. El developer que domina ambos tiene un toolkit completo.

Objetivo Profesional

Al final de este módulo podrás:

✅ Usar Claude Code para analizar logs de aplicación y obtener diagnósticos accionables
✅ Interpretar stack traces de Python con ayuda de Claude Code y verificar el diagnóstico
✅ Seguir un proceso sistemático de debugging: reproducir → aislar → diagnosticar → fix → verificar
✅ Identificar cuándo Claude Code ayuda con debugging y cuándo necesitas herramientas manuales
✅ Debuggear una aplicación FastAPI con múltiples bugs usando el proceso sistemático

La Distinción Fundamental: Herramienta vs Oráculo

Antes de entrar en técnicas, necesitas internalizar una idea que define todo este módulo:

Claude Code es una herramienta de debugging, no un oráculo de debugging.

¿Qué significa esto en la práctica?

Claude Code como oráculo (incorrecto)

Tú: "Mi app no funciona, arréglala"
Claude Code: [genera un fix]
Tú: [aplicas el fix sin entender qué pasaba]

Esto falla porque:

Claude Code no tiene acceso al runtime de tu aplicación
No puede ver el estado de la memoria, las variables, las conexiones
No puede reproducir el error — solo puede leer código estático
Si le das información incompleta, te dará un diagnóstico incompleto (o incorrecto)

Claude Code como herramienta (correcto)

Tú: [reproduces el error y capturas el log/stack trace]
Tú: "Aquí está el stack trace. ¿Qué sugiere sobre la causa?"
Claude Code: [analiza y da hipótesis]
Tú: [verificas la hipótesis contra el código y el comportamiento real]
Tú: [aplicas el fix Y verificas que resuelve el problema]

La diferencia es que tú controlas el proceso. Claude Code te da hipótesis basadas en la información que le proporcionas. Tú verificas, tú decides, tú confirmas.

El impacto en tu día a día

Esta distinción no es filosófica — tiene consecuencias prácticas inmediatas:

Approach	Tiempo promedio	Tasa de éxito	Riesgo
Pegar error → aceptar fix	2 min	~40%	Alto: puede crear bugs nuevos
Proceso completo con Claude Code	10-20 min	~85%	Bajo: verificas antes de aplicar
Manual sin AI	20-60 min	~90%	Bajo: pero ineficiente

El sweet spot es el medio: usas Claude Code para acelerar el diagnóstico, pero mantienes el control del proceso y la verificación. Eso te da la velocidad de AI con la precisión de un proceso profesional.

Code Review vs Debugging: Dos Skills Complementarios

Es importante entender la diferencia entre lo que hiciste en los módulos 4-5 y lo que harás en este módulo:

Code Review (Módulos 4-5): Inspección estática

Input:    Código fuente
Proceso:  Leer → Identificar patrones → Evaluar riesgo
Output:   Lista de problemas potenciales
Cuando:   ANTES de que el código se ejecute

En code review, miras el código y dices: "Esta query SQL usa string concatenation — podría tener SQL injection." No necesitas ejecutar nada. El problema es visible en el código.

Debugging (Este módulo): Diagnóstico de runtime

Input:    Error + Logs + Stack trace + Código
Proceso:  Reproducir → Aislar → Diagnosticar → Fix → Verificar
Output:   Bug corregido y verificado
Cuando:   DESPUÉS de que el código falla en ejecución

En debugging, el código ya se ejecutó y algo falló. Tienes un error concreto: "El endpoint devuelve 500 cuando el usuario envía una lista vacía." Necesitas encontrar por qué falla y corregirlo.

Cómo se complementan

Los mejores developers hacen ambos:

Code review antes de merge — encuentra problemas antes de que lleguen a producción
Debugging cuando algo falla — resuelve los problemas que el code review no detectó

El code review no puede detectar todo (especialmente bugs de lógica sutiles y problemas de timing). El debugging no debería ser tu única defensa (es más caro arreglar bugs en producción que prevenirlos en review). Juntos, forman tu red de seguridad completa.

El Proceso Sistemático de Debugging

El backbone de este módulo es un proceso de 5 pasos que aplicarás a cada bug:

┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────┐     ┌──────────────┐
│  REPRODUCIR │ ──→ │   AISLAR    │ ──→ │ DIAGNOSTICAR │ ──→ │   FIX    │ ──→ │  VERIFICAR   │
│             │     │             │     │              │     │          │     │              │
│ "¿Puedo     │     │ "¿Cuál es   │     │ "¿Por qué    │     │ "¿Cuál   │     │ "¿El fix     │
│  hacer que  │     │  el input   │     │  falla?"     │     │  es la   │     │  resuelve el │
│  falle de   │     │  mínimo que │     │              │     │  solución│     │  problema    │
│  nuevo?"    │     │  causa el   │     │  🤖 Claude   │     │  correcta│     │  original?"  │
│             │     │  error?"    │     │  Code ayuda  │     │  ?"      │     │              │
└─────────────┘     └─────────────┘     │  aquí        │     └──────────┘     └──────────────┘
                                        └──────────────┘

Claude Code es más útil en el paso 3 (diagnosticar), pero no reemplaza los otros 4 pasos. Muchos developers saltan directamente a "pegar el error en Claude Code y aplicar lo que dice" — eso es saltar del paso 1 al paso 4 sin pasar por 2, 3, ni 5. Y es la receta para fixes que no funcionan o que crean bugs nuevos.

Por qué cada paso importa

Reproducir: Sin reproducción, no puedes confirmar que tu fix funciona. "Me dijeron que hay un bug" no es suficiente — necesitas verlo tú mismo con condiciones específicas.

Aislar: Un error que ocurre con un request de 15 campos podría ser causado por cualquiera de esos campos. Reducir al input mínimo te dice exactamente dónde está el problema. Esto convierte un misterio en una pista concreta.

Diagnosticar: Aquí es donde Claude Code brilla. Con un input mínimo que causa el error y el stack trace, puedes pasarle datos precisos y obtener una hipótesis de alta calidad. Sin los pasos 1 y 2, el diagnóstico es genérico e impreciso.

Fix: No todo fix es igual. Un try/except que silencia el error es un parche. Corregir la validación en el schema de Pydantic es un fix de raíz. Claude Code a veces sugiere parches — tú debes evaluar si el fix es de raíz.

Verificar: El paso más saltado y el más importante. Verificas que: (a) el bug original ya no ocurre, (b) la funcionalidad que sí funcionaba sigue funcionando, (c) edge cases relacionados no causan bugs nuevos.

Dónde Claude Code Ayuda en Cada Paso

No todos los pasos se benefician igual de Claude Code:

Paso	Utilidad de Claude Code	Por qué
Reproducir	Baja	Claude Code no puede ejecutar tu app ni hacer requests
Aislar	Media	Puede sugerir qué variables probar, pero tú ejecutas
Diagnosticar	Alta	Excelente analizando stack traces, logs, y código
Fix	Alta	Puede generar el código de fix basado en el diagnóstico
Verificar	Media	Puede sugerir edge cases para probar, pero tú ejecutas

La clave es que Claude Code es más útil en los pasos analíticos (diagnosticar, sugerir fixes) y menos útil en los pasos ejecutivos (reproducir, verificar) — porque esos requieren interacción con tu aplicación real.

Progresión del Módulo

Mapa del Módulo

Cápsula	Tema	Qué aprenderás
02	Log Analysis con Claude Code	Pasar logs a Claude Code, dar contexto, evaluar el diagnóstico
03	Runtime Errors y Stack Traces	Interpretar stack traces de Python con ayuda de Claude Code
04	Debugging Sistemático	El proceso completo: reproducir → aislar → diagnosticar → fix → verificar
05	Cuando Claude Code No Ayuda	Limitaciones reales y cuándo usar herramientas manuales
06	Ejercicio: Debugging Real	Debuggear una aplicación FastAPI con 4-5 bugs reales

Flujo de aprendizaje

Empiezas con la habilidad más común y más útil: log analysis (cápsula 02). Aprendes qué logs copiar, cuánto contexto dar, y cómo evaluar la respuesta de Claude Code. Después pasas a stack traces (cápsula 03) — la segunda fuente más valiosa de información de debugging. Con esas dos habilidades, aprendes el proceso sistemático completo (cápsula 04) que integra ambas técnicas en un flujo disciplinado. La cápsula 05 es la más importante conceptualmente: cuándo Claude Code no ayuda — las limitaciones reales que evitan que pierdas tiempo. Y cierras con un ejercicio de debugging real (cápsula 06) donde aplicas todo a una aplicación con bugs.

Progresión de dificultad

Cápsula 02: Log Analysis       → Skill individual, ejemplos guiados
Cápsula 03: Stack Traces       → Skill individual, más variedad de errores
Cápsula 04: Proceso Sistemático → Integración de skills en un proceso
Cápsula 05: Limitaciones       → Criterio: saber cuándo NO usar Claude Code
Cápsula 06: Ejercicio Real     → Aplicación completa con múltiples bugs

Cada cápsula construye sobre la anterior. Log analysis y stack traces son los inputs del proceso sistemático. El proceso sistemático es el marco donde decides si Claude Code ayuda o no. Y el ejercicio final requiere todo junto.

Conexión con Proyecto

Ejercicio de este módulo

En la cápsula 06 recibirás una aplicación FastAPI con 5 bugs de diferentes tipos: un runtime error, un error de lógica, un edge case no manejado, un bug de datos silencioso, y una validación incompleta. Deberás diagnosticar cada uno usando el proceso sistemático y documentar cada paso.

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

El proyecto integrador incluye bugs que requieren debugging real — no solo code review. El proceso que aprendes aquí (reproducir → aislar → diagnosticar → fix → verificar) es exactamente lo que seguirás en la fase de debugging del proyecto final. La diferencia es escala: aquí debuggeas 5 bugs aislados; en el módulo 8, debuggeas bugs dentro de un codebase más grande donde los problemas pueden interactuar entre sí.

La documentación del proceso de debugging es parte de la entrega del proyecto integrador. El formato que practicas en la cápsula 06 (reproducir → aislar → diagnosticar → fix → verificar documentado) es el formato que usarás en el módulo 8.

Qué Necesitas para Este Módulo

Herramientas

✅ Claude Code CLI instalado y funcional
✅ Python 3.10+ con FastAPI instalado
✅ Terminal donde puedas ejecutar aplicaciones FastAPI
✅ Un editor de código (para leer código mientras debuggeas)
✅ curl o similar para hacer requests HTTP (o Postman/httpie)

Conocimientos previos

✅ Módulos 1-5 de esta guía (o equivalente en experiencia)
✅ Básico de Python y FastAPI (rutas, modelos Pydantic, respuestas)
✅ Comodidad leyendo logs de terminal
✅ Concepto básico de qué es un stack trace (este módulo te enseña a leerlos en detalle)

Instalación rápida si necesitas

pip install fastapi uvicorn pydantic httpx

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

❌ Debugging de frontend o JavaScript — El módulo se enfoca en Python/FastAPI. Los principios aplican a otros lenguajes, pero los ejemplos son Python.
❌ Configuración avanzada de herramientas de debugging — No hacemos un tutorial de pdb, debuggers de IDE, ni profilers. Mencionamos cuándo usarlos, pero el módulo se enfoca en el proceso y en el uso de Claude Code.
❌ Debugging de infraestructura — Problemas de Docker, networking, o deployment están fuera de scope. Nos enfocamos en bugs de código de aplicación.
❌ Testing — Testing es la guía #8 del path. Aquí mencionamos tests como herramienta de verificación (paso 5), pero no enseñamos a escribir tests.
❌ Debugging en producción — Técnicas como feature flags, canary deploys, y observabilidad avanzada están fuera de scope. Nos enfocamos en debugging en entorno de desarrollo.

Evidencia de Éxito

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

✅ Puedes pasar logs a Claude Code y obtener un diagnóstico útil (no solo pegar el error, sino dar contexto suficiente)
✅ Puedes leer un stack trace de Python y explicar qué pasó, con o sin ayuda de Claude Code
✅ Sigues el proceso reproducir → aislar → diagnosticar → fix → verificar de forma natural, sin saltarte pasos
✅ Sabes cuándo parar de usar Claude Code y abrir pdb o un profiler
✅ Debuggeaste exitosamente los 5 bugs de la aplicación del ejercicio (cápsula 06)
✅ Documentaste tu proceso de debugging para cada bug

Indicadores de que necesitas repasar

⚠️ Copias y pegas errores en Claude Code sin incluir contexto — repasa cápsula 02
⚠️ No puedes explicar un stack trace sin ayuda de AI — repasa cápsula 03
⚠️ Aplicas fixes sin verificar — repasa el paso 5 en cápsula 04
⚠️ Pasas más de 30 minutos con Claude Code sin resolver un bug — repasa cápsula 05

Debugging en la Era de AI: Qué Cambió y Qué No

Lo que cambió

Antes de AI, debugging era 100% manual: lees el error, buscas en Stack Overflow, pones breakpoints, lees documentación, pruebas hipótesis una por una. El cuello de botella era el tiempo de diagnóstico — entender qué pasaba podía tomar más que arreglarlo.

Con Claude Code, el diagnóstico se acelera dramáticamente para ciertos tipos de errores:

✅ Stack traces de errores conocidos — Claude Code conoce los patrones de cientos de excepciones de Python y puede explicarlos en segundos
✅ Log analysis — Claude Code puede procesar 200 líneas de logs y encontrar la anomalía más rápido que un humano leyendo línea por línea
✅ Errores de librerías — "¿Qué significa sqlalchemy.exc.IntegrityError?" Claude Code conoce la respuesta inmediatamente
✅ Sugerir fixes — Una vez diagnosticado, generar el código de fix es rápido

Lo que NO cambió

❌ Necesitas entender tu aplicación — Claude Code no conoce tus reglas de negocio ni tu arquitectura
❌ Necesitas reproducir el bug — Sin reproducción, ni tú ni Claude Code pueden confirmar el fix
❌ Necesitas verificar — Un fix generado por AI puede crear bugs nuevos si no lo verificas
❌ Bugs complejos requieren herramientas manuales — Race conditions, memory leaks, performance issues necesitan pdb, profilers, y herramientas de observabilidad

El developer efectivo combina ambos

El developer más efectivo en 2026 no es el que usa más AI ni el que se rehúsa a usarla. Es el que sabe cuándo usar cada herramienta:

Error con stack trace claro → Claude Code primero
Bug intermitente sin errores → Logging + debugging manual
Performance issue → Profiler primero, Claude Code para el fix
Bug de lógica de negocio → Entender el requisito, debugging manual

Este módulo te da el criterio para tomar esa decisión rápidamente.

Anatomía de un Bug: Los Tipos que Encontrarás

En este módulo trabajarás con 4 categorías de bugs, cada una requiere un enfoque diferente:

Runtime Errors (crash)

El servidor devuelve 500 con un stack trace. Es el tipo más fácil de debuggear porque Python te dice exactamente dónde falló.

TypeError: 'NoneType' object is not subscriptable
→ Algo es None cuando esperabas un dict o list

Claude Code ayuda: Mucho. El stack trace es información textual que Claude Code procesa excelentemente.

Logic Errors (resultado incorrecto)

El código no crashea — devuelve 200. Pero los datos son incorrectos. El cálculo de descuento da 55% cuando debería dar 20%. El filtro incluye registros que debería excluir.

GET /api/stats → {"completion_rate": -15.0}
→ El completion rate no debería ser negativo

Claude Code ayuda: Parcialmente. Puede analizar el código y encontrar la lógica incorrecta, pero necesita que le digas cuál es el resultado esperado vs el obtenido.

Edge Case Errors (falla con inputs específicos)

El código funciona con inputs "normales" pero falla con inputs válidos pero inesperados: listas vacías, strings con caracteres especiales, fechas en el pasado, valores None donde no se esperan.

GET /api/tasks/search?q=test → 200 OK
GET /api/tasks/search?q=test con tarea sin descripción → 500

Claude Code ayuda: Mucho, especialmente si le muestras un input que funciona y uno que falla. La comparación le permite aislar el problema.

Silent Data Corruption (datos incorrectos sin error)

El más peligroso. El código no crashea ni devuelve errores. Pero silenciosamente corrompe datos: campos que deberían actualizarse no se actualizan, valores que deberían ser None se convierten en empty string, IDs que se reutilizan.

PATCH /api/tasks/1 con {"assignee_id": null} → 200 OK
GET /api/tasks/1 → assignee_id sigue siendo el anterior

Claude Code ayuda: Poco. Estos bugs no producen stack traces ni errores en logs. Necesitas inspeccionar el estado de los datos antes y después de cada operación.

Resumen

Este módulo cierra la Phase 2 con la habilidad más práctica: debugging con asistencia de AI
Claude Code es una herramienta de debugging, no un oráculo — le das datos, te da hipótesis, tú verificas
El proceso sistemático (reproducir → aislar → diagnosticar → fix → verificar) es el backbone del módulo
Log analysis es el caso de uso más común y más útil de Claude Code para debugging
Stack traces son tu segundo aliado: aprender a leerlos te da independencia
Saber cuándo Claude Code no ayuda es tan importante como saber cuándo sí
Hay 4 tipos de bugs (runtime, lógica, edge case, corrupción silenciosa) y cada uno requiere un enfoque diferente
Todo lo que aprendes aquí se aplica directamente al proyecto integrador del módulo 8
La documentación del proceso es tan importante como el fix — es evidencia de pensamiento profesional

Recursos Adicionales

Python Debugging — Real Python - Tutorial completo de debugging en Python con pdb
FastAPI — Debugging Tips - Documentación oficial de FastAPI sobre debugging
Python Logging HOWTO - Guía oficial de Python para logging efectivo
Anthropic — Claude Code Best Practices - Documentación oficial de Claude Code
The Debugging Mindset — ACM Queue - Artículo clásico sobre el mindset de debugging
Nine Rules for Debugging — David Agans - Framework profesional de debugging aplicable a cualquier tecnología

Preview Rápido: Qué Verás en Cada Cápsula

Para que sepas qué esperar:

Cápsula 02: Copiarás 20+ líneas de logs de una aplicación FastAPI que falla y se las pasarás a Claude Code con un prompt estructurado. Verás la diferencia entre dar contexto y no darlo. Aprenderás a evaluar si el diagnóstico de Claude Code es correcto antes de actuar.
Cápsula 03: Leerás stack traces de Python — empezando por los simples (KeyError, TypeError) hasta los encadenados (exception during handling of another exception). Practicarás leerlos sin AI primero, y después usarás Claude Code para los complejos.
Cápsula 04: Recorrerás el proceso de 5 pasos completo con un bug realista: tareas duplicadas en un endpoint con filtros. Verás cómo cada paso reduce la incertidumbre hasta llegar al fix correcto.
Cápsula 05: Verás 5 categorías de bugs donde Claude Code NO puede ayudar: race conditions, lógica de negocio, performance, estado en memoria, y configuración de entorno. Para cada una, conocerás la herramienta manual correcta.
Cápsula 06: Recibirás una aplicación FastAPI completa (TaskFlow API) con 5 bugs plantados. Debuggearás cada uno siguiendo el proceso sistemático y documentarás tu trabajo.

Siguiente cápsula: Log Analysis con Claude Code — la habilidad más útil de debugging con AI.

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

← AnteriorEjercicio: Identificar Patrones de Error Siguiente →Log Analysis con Claude Code