Módulo 7: Subagents para Debugging, Regenerar vs Editar

Descripción de la cápsula

Los módulos 1 a 6 te dieron un toolkit completo: sabes calibrar confianza, detectar hallucinations, hacer code review profesional, identificar patrones de error, y debuggear con Claude Code como herramienta. Eso es competencia profesional. Ahora entramos en maestría.

Este módulo cubre dos temas que parecen separados pero están profundamente conectados: (1) usar subagents como herramientas de investigación antes de cambiar código, y (2) tener un framework de decisión para la pregunta que te haces 10 veces al día: "¿regenero este código o lo edito manualmente?"

La conexión es directa: investigas con subagents, entiendes el alcance del problema, y esa comprensión informa si regenerar o editar es la mejor opción. Son dos caras de la misma moneda — comprensión profunda antes de actuar.

Contexto del Módulo

¿Dónde estamos?

Este es el primer módulo de la Phase 3: Mastery. Has completado todo el camino desde entender el problema (Phase 1) hasta code review y debugging profesional (Phase 2). Ahora refinas tu criterio con herramientas y frameworks avanzados.

Guía: Debugging & Code Review with Claude Code

Phase 1: Entender el Problema (Módulos 1-3)
├── Módulo 1: Confianza calibrada
├── Módulo 2: Mental models
└── Módulo 3: Detectar hallucinations

Phase 2: Code Review Profesional (Módulos 4-6)
├── Módulo 4: Code review de output AI
├── Módulo 5: Patrones de error comunes
└── Módulo 6: Debugging con Claude Code

Phase 3: Mastery (Módulos 7-8)
├── Módulo 7: Subagents, Regenerar vs Editar  ← estás aquí
└── Módulo 8: Proyecto Integrador

¿Por qué este módulo abre la Phase 3?

Porque ambos temas requieren todo lo anterior:

Subagents solo son útiles si sabes qué preguntar (módulos 1-3) y qué buscar en las respuestas (módulos 4-6). Un developer que no sabe hacer code review no puede evaluar lo que un subagent le reporta.
Regenerar vs editar solo tiene sentido si sabes evaluar calidad de código (code review, módulo 4-5) y diagnosticar problemas (debugging, módulo 6). Sin esas habilidades, regenerar es un tiro al aire y editar es adivinar.

La transición clave

Phase 2 (Módulo 6):    "Encontré un bug. Lo diagnostico y lo arreglo."
Phase 3 (Este módulo): "Encontré un problema. ¿Investigo más a fondo?
                         ¿Regenero? ¿Edito? ¿Una combinación?"

La fase anterior te dio herramientas para problemas puntuales. Esta fase te da el criterio para problemas complejos donde la respuesta no es obvia.

Los Dos Temas y Su Conexión

Tema 1: Subagents como herramientas de investigación

Claude Code ofrece capacidades de exploración e investigación que te permiten entender un codebase antes de hacer cambios. No estás pidiendo que solucione el problema — estás pidiendo que te ayude a entenderlo.

Investigación con subagents:

  "Explica el flujo de autenticación en este codebase"
  → Claude Code navega archivos, sigue imports, mapea el flujo
  → Tú recibes un mapa mental del sistema
  → AHORA puedes decidir qué cambiar y cómo

  vs

  Sin investigación previa:
  "Arregla el bug de autenticación"
  → Claude Code adivina dónde está el problema
  → Puede cambiar lo incorrecto, romper dependencias
  → Introduces bugs nuevos

La diferencia no es la herramienta — es la intención. El subagent de exploración te da comprensión. La comprensión te da decisiones informadas.

Tema 2: El framework regenerar vs editar

Esta es la decisión más frecuente cuando trabajas con AI coding tools. Claude Code generó 100 líneas de código y tiene problemas. ¿Qué haces?

El espectro de opciones:

  Regenerar todo ←──────────────────────────→ Editar una línea
       │                                              │
       │    Regenerar     Regenerar     Editar        │
       │    archivo       función       varias        │
       │    completo      específica    líneas        │
       │                                              │
  "El approach    "La función    "El approach   "Solo un
   es incorrecto   tiene el       es correcto    off-by-one
   desde la base"  approach       pero hay       error"
                   incorrecto     detalles mal"
                   pero el resto
                   está bien"

No es binario. Hay un espectro completo de opciones y cada situación tiene su respuesta óptima.

La conexión entre los dos temas

Flujo típico cuando enfrentas un problema complejo:

1. INVESTIGAR (subagents)
   → "¿Cómo funciona esta parte del codebase?"
   → "¿Qué archivos dependen de este módulo?"
   → "¿Cuál es el impacto de cambiar esta función?"

2. EVALUAR (tu criterio + módulos 4-6)
   → "¿El approach es fundamentalmente incorrecto?"
   → "¿Cuánto del código necesita cambiar?"
   → "¿Qué contexto perdería si regenero?"

3. DECIDIR (framework regenerar vs editar)
   → Regenerar: "El approach es incorrecto"
   → Editar: "El 90% está bien, solo hay detalles"
   → Mixto: "Regenero esta función, edito el resto"

4. EJECUTAR (con precisión)
   → Si regeneras: prompt mejor informado por la investigación
   → Si editas: sabes exactamente qué cambiar porque investigaste

Sin la investigación del paso 1, la decisión del paso 3 es una apuesta. Con la investigación, es una decisión informada.

Objetivo Profesional

Al final de este módulo podrás:

✅ Usar las capacidades de exploración de Claude Code para investigar un codebase antes de hacer cambios
✅ Formular queries de investigación que producen información accionable (no genérica)
✅ Saber cuándo investigar con subagents vs hacer la investigación manualmente
✅ Reconocer señales claras de que regenerar es la mejor opción
✅ Reconocer señales claras de que editar manualmente es la mejor opción
✅ Aplicar un framework de decisión que cubre el espectro completo: desde regenerar todo hasta editar una línea
✅ Tomar decisiones informadas y justificadas en 5 escenarios realistas
✅ Combinar investigación y decisión en un flujo de trabajo eficiente

Progresión del Módulo

Mapa del Módulo

Cápsula	Tema	Qué aprenderás
02	Subagents Explore para Investigar	Usar exploración de Claude Code antes de cambiar código
03	Cuándo Regenerar Código	Señales claras, costos, y técnicas para regenerar efectivamente
04	Cuándo Editar Manualmente	Señales claras, técnicas de edición eficiente con Claude Code
05	Decision Framework: Regenerar vs Editar	El framework completo con 5 escenarios realistas

Flujo de aprendizaje

Cápsula 02: Investigar                  → La herramienta de comprensión
     │
     ├───→ Cápsula 03: Cuándo Regenerar → Un extremo del espectro
     │
     ├───→ Cápsula 04: Cuándo Editar    → El otro extremo del espectro
     │
     └───→ Cápsula 05: El Framework     → Integración + escenarios prácticos

Empiezas con investigación (cápsula 02) porque es el prerequisito para tomar buenas decisiones — necesitas entender el código antes de decidir qué hacer con él. Después aprendes las señales de regenerar (cápsula 03) y las señales de editar (cápsula 04) como los dos extremos del espectro. Finalmente, el framework integrador (cápsula 05) une todo en un flowchart de decisión con 5 escenarios donde la respuesta no es obvia.

Dependencias entre cápsulas

Cápsula 02 (Investigar) ─────┐
                               ├── Cápsula 05 (Framework)
Cápsula 03 (Regenerar)  ─────├── Integra los 3 temas
                               │   + 5 escenarios prácticos
Cápsula 04 (Editar)     ─────┘

La cápsula 02 es prerequisito para todas — sin saber investigar, no puedes tomar decisiones informadas. Las cápsulas 03 y 04 son independientes entre sí pero ambas son prerequisito para la cápsula 05.

Conexión con Proyecto

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

El proyecto integrador te dará un codebase con múltiples problemas. Antes de tocar una línea, necesitas:

Investigar con subagents: entender la estructura, las dependencias, y el alcance de los problemas
Decidir para cada problema: ¿regenero, edito, o hago una combinación?
Ejecutar con la técnica correcta para cada caso

El módulo 8 es donde todo lo que aprendes aquí se pone a prueba en un escenario real y completo.

Este módulo (7):
├── Aprendes a investigar con subagents
├── Aprendes señales de regenerar
├── Aprendes señales de editar
└── Practicas el framework de decisión

Proyecto integrador (8):
├── Investigas el codebase con subagents
├── Decides regenerar vs editar para cada problema
├── Ejecutas con la técnica correcta
└── Documentas cada decisión con justificación

La documentación de las decisiones es parte de la entrega del proyecto. No basta con "arreglé el código" — necesitas explicar "investigué el codebase, encontré que X era el problema, decidí regenerar/editar porque Y, y el resultado fue Z."

Qué Necesitas para Este Módulo

Herramientas

✅ Claude Code CLI instalado y funcional
✅ Python 3.10+ con FastAPI instalado
✅ Un codebase real o el codebase de práctica proporcionado en los ejercicios
✅ Terminal para ejecutar comandos
✅ Editor de código (VS Code, Cursor, etc.)

Conocimientos previos

✅ Módulos 1-6 de esta guía completados (o equivalente)
✅ Experiencia con Claude Code para generar y modificar código
✅ Code review profesional (módulo 4-5)
✅ Debugging con Claude Code (módulo 6)
✅ Familiaridad con Python y FastAPI

Instalación rápida si necesitas

pip install fastapi uvicorn pydantic sqlalchemy httpx

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

❌ Cómo crear subagents personalizados — Usamos las capacidades de exploración que Claude Code ofrece, no creamos herramientas nuevas
❌ Automatización de decisiones — El framework es para humanos, no para automatizar la decisión regenerar vs editar
❌ Code review — Eso fue módulos 4-5. Aquí asumes que ya sabes evaluar calidad de código
❌ Debugging — Eso fue módulo 6. Aquí asumes que ya sabes diagnosticar problemas
❌ Gestión de proyectos — No cubrimos cuándo regenerar un proyecto entero o cambiar de stack tecnológico
❌ Refactoring avanzado — Patrones de refactoring profundo están fuera de scope. Nos enfocamos en la decisión, no en técnicas avanzadas de transformación

Antes de Empezar: Autodiagnóstico

Evalúa tu nivel actual en las dos áreas de este módulo:

Investigación con subagents

¿Cómo investigas un codebase nuevo antes de hacer cambios?

A. "No investigo — abro el archivo y empiezo a cambiar"
   → Este módulo va a cambiar tu workflow completamente

B. "Hago grep/find para buscar archivos relevantes"
   → Estás en el nivel manual — los subagents te aceleran 10x

C. "Le pregunto a Claude Code pero sin estructura"
   → Formular mejores queries te dará mejores resultados

D. "Investigo sistemáticamente antes de cada cambio"
   → Valida que tus queries estén bien formuladas

E. "Combino investigación con subagents y manual según el caso"
   → Estás en nivel avanzado — refina tu criterio con los ejercicios

Decisión regenerar vs editar

¿Cómo decides si regenerar o editar código con problemas?

A. "Siempre regenero — es más fácil"
   → Estás perdiendo horas por semana y customizaciones valiosas

B. "Siempre edito — no confío en regenerar"
   → A veces regenerar es más eficiente y produce mejor código

C. "Depende de mi estado de ánimo"
   → Un framework te dará consistencia y mejores resultados

D. "Tengo una intuición pero no la puedo articular"
   → Este módulo convierte tu intuición en proceso

E. "Tengo criterios claros para cada caso"
   → Compara tus criterios con el framework — podrías refinarlo

Qué nivel deberías tener al empezar

Para aprovechar este módulo al máximo, necesitas:

Prerequisitos reales (no teóricos):
├── ✅ Has hecho al menos 5 code reviews de código AI-generated
├── ✅ Has debuggeado al menos 3 bugs con ayuda de Claude Code
├── ✅ Puedes leer un stack trace de Python y entender qué pasó
├── ✅ Conoces al menos 3 patrones de error comunes en AI code
├── ✅ Has usado Claude Code para generar código al menos 20 veces
└── ✅ Has enfrentado la pregunta "¿regenero o edito?" al menos una vez

Si no cumples estos prerequisitos:
└── Repasa los módulos 4-6 antes de continuar

El Costo de No Tener Framework

Para entender por qué este módulo importa, considera lo que pasa sin un framework de decisión:

Sin framework: la rutina ineficiente

Lunes 9:00 — Claude Code genera un endpoint con 3 problemas
  → "Hmm, regenero" (15 min)
  → El nuevo código tiene 2 problemas diferentes
  → "Regenero otra vez" (15 min)
  → Ahora funciona pero perdiste una hora

Lunes 11:00 — Un off-by-one en un filtro
  → "Regenero para estar seguro" (15 min)
  → El nuevo código pierde el logging que agregaste ayer
  → "Re-agrego el logging" (10 min)
  → Un fix de 30 segundos tomó 25 minutos

Lunes 14:00 — Approach algorítmico incorrecto
  → "Edito, seguro puedo arreglarlo" (30 min de parches)
  → El código es un Frankenstein de parches sobre diseño incorrecto
  → "Ok, regenero desde cero" (15 min)
  → 45 minutos perdidos en ediciones inútiles

Total del lunes: ~2 horas perdidas en decisiones sub-óptimas.

Con framework: la rutina eficiente

Lunes 9:00 — Claude Code genera un endpoint con 3 problemas
  → Framework: "3 cambios, independientes, sin customizaciones → editar"
  → 10 minutos editando → done

Lunes 11:00 — Un off-by-one en un filtro
  → Framework: "1 carácter, 95% correcto → editar"
  → 30 segundos → done

Lunes 14:00 — Approach algorítmico incorrecto
  → Framework: "Approach incorrecto → regenerar función"
  → Prompt informado → 12 minutos → done

Total del lunes: ~25 minutos. La diferencia es de ~1.5 horas por día, o ~7.5 horas por semana.

Tono de Este Módulo: Senior-to-Senior

Este módulo tiene un tono diferente a los anteriores. No es introductorio — es una conversación entre seniors:

Módulos 1-3 (Phase 1): "Déjame explicarte por qué esto importa"
Módulos 4-6 (Phase 2): "Aquí están las herramientas profesionales"
Este módulo (Phase 3):  "En mi experiencia, esto funciona y esto no"

El enfoque es práctico y basado en experiencia:

No hay definiciones largas — ya sabes qué es un subagent, qué es code review, qué es debugging
Hay criterio y heurísticas — "cuando veo X, generalmente hago Y, porque Z"
Hay matices — "a veces la respuesta correcta es regenerar la función pero editar el archivo"
Hay señales concretas — no "regenera cuando el código es malo" sino "regenera cuando el approach algorítmico es incorrecto: usó bubble sort donde necesitas hash map lookup"

Lo que hace este módulo diferente

Módulo genérico:
├── "Regenerar: cuando el código tiene muchos errores"
├── "Editar: cuando el código está casi correcto"
└── Sin matices, sin escenarios, sin señales concretas

Este módulo:
├── "Regenerar: usó un for loop O(n²) donde necesitas un dict lookup O(1)"
│   └── Señal: el approach algorítmico es fundamentalmente incorrecto
├── "Editar: el sort está bien pero falta un reverse=True"
│   └── Señal: el 95% del código es correcto, el fix es puntual
├── "Mixto: regenerar la función de cálculo, editar los imports"
│   └── Señal: parte del código es incorrecto, parte está bien
└── Cada decisión con justificación y análisis de costos

Evidencia de Éxito

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

✅ Puedes usar las capacidades de exploración de Claude Code para investigar un codebase que no conoces y obtener un mapa mental del sistema
✅ Formulas queries de investigación que producen información útil y accionable
✅ Ante un problema en código AI-generated, tu primera reacción es investigar antes de actuar
✅ Puedes articular por qué regenerar es mejor que editar (o viceversa) con señales concretas
✅ Tomas la decisión correcta en al menos 4 de los 5 escenarios de la cápsula 05
✅ Tu justificación para cada decisión incluye: señales observadas, costos considerados, y alternativas descartadas

Indicadores de que necesitas repasar

⚠️ Regeneras código sin investigar primero el alcance del problema — repasa cápsula 02
⚠️ Regeneras siempre que hay más de un error — repasa cápsula 04 (a veces editar es más eficiente)
⚠️ Editas parche sobre parche cuando el approach es incorrecto — repasa cápsula 03
⚠️ No puedes justificar tu decisión de regenerar vs editar — repasa cápsula 05

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

Para que sepas qué esperar:

Cápsula 02: Usarás las capacidades de exploración de Claude Code para investigar un codebase de una API FastAPI antes de hacer cambios. Aprenderás a formular queries como "Explica el flujo de autenticación en este proyecto" y "Encuentra todos los lugares donde se verifican permisos de usuario." Verás la diferencia entre investigar antes de actuar vs actuar a ciegas.
Cápsula 03: Aprenderás las 5 señales claras de que regenerar es mejor que editar: approach algorítmico incorrecto, arquitectura equivocada, más del 50% del código necesita cambios, el código no cumple los requisitos, y la deuda técnica sería masiva si se parchea. También aprenderás el costo de regenerar — pierdes context, customizaciones, y puedes obtener problemas nuevos.
Cápsula 04: Aprenderás las 5 señales de que editar es mejor: el 90% está correcto, el fix es puntual y claro, el contexto se perdería, el issue es un patrón conocido, y regenerar tomaría más tiempo. Practicarás técnicas de edición eficiente con asistencia de Claude Code.
Cápsula 05: Aplicarás el framework completo en 5 escenarios realistas donde la respuesta no es obvia. Cada escenario tiene código real con problemas reales. Usarás el flowchart: evaluar daño → estimar tiempo de edición → estimar tiempo de regeneración → considerar pérdida de contexto → decidir. El espectro completo: regenerar todo ↔ regenerar función ↔ editar múltiples líneas ↔ editar una línea.

Resumen

Este módulo abre la Phase 3: Mastery con dos temas conectados: investigación con subagents y el framework regenerar vs editar
Subagents de exploración te dan comprensión del codebase antes de hacer cambios — investigación, no solución
Regenerar vs editar es un espectro, no una decisión binaria — desde regenerar todo hasta editar una línea
Los dos temas se conectan: investigas → entiendes → decides → ejecutas
El tono es senior-to-senior: criterio basado en experiencia, señales concretas, matices reales
Todo lo que aprendes aquí se aplica directamente al proyecto integrador del módulo 8
Ambos temas requieren todo lo aprendido en módulos 1-6: sin code review y debugging, no puedes investigar efectivamente ni decidir con criterio

Recursos Adicionales

Anthropic — Claude Code Best Practices - Documentación oficial de Claude Code, incluyendo subagents
Refactoring Guru — When to Refactor - Framework profesional para decidir cuándo refactorizar vs reescribir
Joel Spolsky — Things You Should Never Do - El artículo clásico sobre por qué reescribir no siempre es la respuesta
Martin Fowler — Refactoring - El libro de referencia sobre cuándo y cómo cambiar código existente
The Pragmatic Programmer — Refactoring - Principios de decisión para cambios de código

Siguiente cápsula: Subagents Explore para Investigar — la herramienta que transforma investigación de código.

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

← AnteriorEjercicio: Debugging Real Siguiente →Subagents Explore para Investigar