Módulo 3: Entender Arquitectura Existente

Descripción de la capsula

Vas a aprender a transformar exploración en comprensión arquitectural documentada. En los módulos anteriores aprendiste a explorar un codebase (Módulo 1) y a investigar en profundidad con herramientas especializadas (Módulo 2). Pero explorar y entender no es lo mismo. Puedes navegar un codebase archivo por archivo, leer cada función, seguir cada import — y aún no entender la arquitectura. No entender cómo encajan las piezas, qué depende de qué, cómo fluyen los datos de punta a punta, qué patterns se repiten y cuáles son accidentales.

Este módulo cierra ese gap. Es el nivel más alto de comprensión antes de modificar código. Cuando termines, no solo "conocerás" el codebase — tendrás un mapa completo: dependency maps que muestran qué módulo depende de qué, flow diagrams que trazan requests desde el entry point hasta la respuesta, y pattern analysis que identifica tanto lo que funciona bien como lo que necesita mejora. Todo generado con Claude Code.

La diferencia entre un developer que "exploró" un codebase y uno que "entiende su arquitectura" es la diferencia entre haber visitado una ciudad y tener un mapa de la ciudad. El turista sabe dónde están algunos lugares. El cartógrafo puede planificar rutas, identificar cuellos de botella, y decidir dónde construir. Este módulo te convierte en cartógrafo.

Contexto del Módulo

Donde estamos?

Esta es la Guía #8 del Claude Code Agentic Development Path — "Refactoring & Legacy Code with Claude Code." Estás en el Módulo 3 de 8, el último módulo de la Phase 1: Entender Codebases.

Lo que construiste en los módulos anteriores:

Módulo	Lo que aprendiste	El nivel de comprensión que lograste
Módulo 1: Onboarding con AI	Método sistemático de las 5 preguntas, exploración con Claude Code, documentar hallazgos	Familiaridad: "Sé qué hace este proyecto, dónde están las cosas, y cómo fluyen los datos a alto nivel"
Módulo 2: Agentic Research con Explore	Explore subagent, búsqueda semántica, patterns de exploración avanzados	Acceso preciso: "Puedo encontrar cualquier cosa en el codebase y trazar features end-to-end"

Módulo 3 añade la capa final:

Módulo 3: Entender Arquitectura	Dependency maps, flow analysis, pattern identification, anti-pattern detection	Mapa completo: "Puedo visualizar y explicar la arquitectura a cualquier persona"

La progresión de Phase 1 es intencional:

Módulo 1: Familiaridad
   "Conozco el codebase"
        |
        v
Módulo 2: Acceso preciso
   "Puedo encontrar cualquier cosa"
        |
        v
Módulo 3: Mapa completo              <-- ESTAS AQUI
   "Puedo visualizar y explicar la arquitectura"

Cada módulo te da un nivel más profundo de comprensión. El Módulo 1 te dio el "qué." El Módulo 2 te dio el "dónde." El Módulo 3 te da el "cómo" — cómo se conectan las piezas, cómo fluyen los datos, cómo se organizan los patterns.

Hacia donde vamos?

Este módulo cierra Phase 1 y prepara directamente Phase 2:

Phase 1: Entender Codebases (Módulos 1-3)
+-- Módulo 1: Onboarding con AI                    ✅ Completado
+-- Módulo 2: Agentic Research con Explore          ✅ Completado
+-- Módulo 3: Entender Arquitectura Existente       <-- ESTAS AQUI

Phase 2: Refactoring (Módulos 4-6)
+-- Módulo 4: Refactoring Multi-File Coordinado
+-- Módulo 5: Migración de Frameworks y Lenguajes
+-- Módulo 6: Context Management para Proyectos Grandes

Phase 3: Legacy y Proyecto (Módulos 7-8)
+-- Módulo 7: Modernizar Legacy Code
+-- Módulo 8: Proyecto Integrador — Migración Completa

La transición de Phase 1 a Phase 2 es el momento más importante de la guía. Hasta ahora has invertido todo el esfuerzo en comprensión — deliberadamente. No has modificado código de forma significativa. Eso cambia en el Módulo 4.

Pero no cambias a ciegas. Cambias con un mapa. El architecture map que produces en este módulo es el input directo del Módulo 4. Cuando necesites decidir qué refactorizar, el mapa te dice dónde están las dependencias problemáticas. Cuando necesites coordinar un refactoring multi-file, el mapa te dice qué archivos se afectan mutuamente. Cuando necesites priorizar, el mapa te dice qué anti-patterns tienen mayor impacto.

Sin mapa, cada refactoring es una apuesta. Con mapa, es una decisión calculada.

Por que este módulo importa?

El gap entre explorar y entender

Imagina que exploraste un codebase con el método del Módulo 1. Sabes que hay un directorio services/ con 12 archivos, un directorio models/ con 8, y un directorio api/ con 15 endpoints. Sabes que usa SQLAlchemy, tiene middleware de autenticación, y los tests están en tests/.

Ahora alguien te pregunta:

"Si cambio la función de autenticación,
¿qué otros módulos se rompen?"

Puedes responder eso con lo que tienes? Probablemente no. Para responder necesitas saber:

Qué módulos importan el módulo de autenticación (dependency map)
Cómo fluye el request a través del middleware de auth (flow analysis)
Si hay otros módulos que replican la lógica de auth en vez de importarla (pattern analysis)
Si hay dependencias circulares que complican el cambio (anti-pattern detection)

Eso es arquitectura. No es "saber que existe" — es "entender cómo se conecta."

Comprensión que permite decisiones

El architecture map no es un documento académico que guardas y olvidas. Es una herramienta de decisión. Cada pieza del mapa responde una pregunta práctica:

Artefacto	Pregunta que responde
Dependency map	"Si cambio X, ¿qué otros módulos se afectan?"
Flow analysis	"¿Por dónde pasan los datos? ¿Dónde están los cuellos de botella?"
Pattern identification	"¿Qué estructura tiene el código? ¿Es consistente?"
Anti-pattern detection	"¿Dónde están las oportunidades de mejora más impactantes?"

Sin estos artefactos, las decisiones de refactoring son intuitivas — "creo que debería refactorizar este módulo porque se ve desordenado." Con ellos, las decisiones son informadas — "este módulo tiene 15 dependientes, una dependencia circular con el módulo de pagos, y viola el principio de single responsibility. Refactorizarlo primero desbloquea mejoras en 3 módulos más."

Claude Code genera, tu interpretas

Un punto fundamental de este módulo: Claude Code genera los maps, diagrams, y análisis. Tú interpretas qué significan y qué hacer con ellos.

Claude Code puede decirte que user_service.py importa 8 módulos diferentes y es importado por 12 otros. Eso es un dato. Tú decides si eso es un god object que necesita ser dividido, o un hub legítimo que coordina operaciones de usuario.

Claude Code puede decirte que hay una dependencia circular entre auth y users. Eso es un hallazgo. Tú decides si extraer una interface, invertir la dependencia, o crear un módulo intermediario.

La AI hace el trabajo pesado de análisis. El juicio profesional es tuyo.

Anti-patterns son oportunidades

Una nota importante sobre el tono de este módulo: cuando identifiques anti-patterns en un codebase, no estás criticando al autor original. Estás encontrando oportunidades de mejora con información que el autor quizás no tenía cuando escribió el código.

El código legacy no es "malo." Es código que fue escrito con las restricciones del momento: deadline apretado, equipo pequeño, requirements que cambiaron, herramientas que no existían. Identificar anti-patterns es un acto profesional — como un doctor que diagnostica para tratar, no para juzgar.

El Contexto de la Industria

Architecture analysis como skill profesional

En equipos de desarrollo modernos, la capacidad de analizar y comunicar la arquitectura de un sistema es un skill que distingue niveles:

Nivel	Lo que puede hacer
Junior	Entiende la función que está modificando
Mid-level	Entiende el módulo donde trabaja y sus vecinos inmediatos
Senior	Entiende la arquitectura completa y puede explicarla a otros
Staff/Principal	Puede analizar cualquier codebase, crear architecture maps, y tomar decisiones de diseño informadas

Lo que este módulo te da es el toolkit para operar a nivel Senior/Staff — no porque cambies tu título, sino porque tendrás la capacidad de crear representaciones arquitecturales que informan decisiones. Y con Claude Code, puedes hacerlo en horas en lugar de semanas.

Por que ahora?

Históricamente, crear architecture maps era un proceso manual que requería semanas de análisis. Leías código, dibujabas diagramas en pizarrón, actualizabas cuando algo cambiaba (spoiler: nunca se actualizaba). El resultado era documentación desactualizada que nadie confiaba.

Con Claude Code, el proceso es diferente:

Análisis manual (2025):
  Leer código -> Dibujar en pizarrón -> Transcribir a Confluence
  -> Desactualizarse en 2 semanas -> Nadie lo usa
  Tiempo: 2-4 semanas. Costo: alto. Valor: decreciente.

Análisis con Claude Code (2026):
  Prompt -> Dependency map generado -> Flow analysis generado
  -> Pattern analysis generado -> Re-generar cuando cambie el código
  Tiempo: 1-3 horas. Costo: bajo. Valor: regenerable.

La diferencia clave no es solo velocidad — es que el análisis es regenerable. Si el código cambia, re-ejecutas los prompts y obtienes un mapa actualizado. Eso lo hace práctico, no solo teórico.

Autodiagnostico: Donde Estas Hoy?

Test rápido de 5 preguntas

1. Si te pido que dibujes el mapa de dependencias de tu proyecto actual, puedes hacerlo?

(a) No — no sé exactamente qué depende de qué
(b) Más o menos — conozco las dependencias principales
(c) Sí — puedo dibujar el grafo completo con módulos y relaciones
(d) No aplica — no estoy trabajando en un proyecto actualmente

2. Puedes trazar el flujo completo de un request desde el entry point hasta la respuesta?

(a) Solo vagamente — sé que pasa por algunos servicios
(b) Los flujos principales sí, los secundarios no
(c) Sí, con detalle de cada paso y transformación de datos
(d) No estoy seguro de dónde empezar

3. Puedes nombrar 3 patterns arquitecturales que usa tu proyecto actual?

(a) No estoy seguro de qué patterns usa
(b) Puedo nombrar 1-2 (MVC, por ejemplo)
(c) Sí — puedo nombrar patterns específicos y dónde se implementan
(d) No conozco bien los patterns arquitecturales

4. Alguna vez identificaste un anti-pattern en código existente?

(a) No — no sabría qué buscar
(b) Sí, pero intuitivamente ("esto se ve mal")
(c) Sí — puedo nombrar anti-patterns específicos y por qué son problemáticos
(d) He escuchado el término pero no lo he aplicado

5. Has usado Claude Code para generar diagramas o mapas de arquitectura?

(a) No — solo lo uso para generar código
(b) He intentado, pero los resultados no fueron útiles
(c) Sí — genero diagramas regularmente con Claude Code
(d) No sabía que se podía hacer eso

Interpretacion

Mayoría de (a) o (d): Este módulo te abre una capacidad completamente nueva. Cada cápsula será reveladora.
Mayoría de (b): Tienes intuición pero no método. Las técnicas de este módulo le darán estructura a lo que ya percibes.
Mayoría de (c): Ya tienes una base sólida. Este módulo te dará herramientas de Claude Code para hacer el análisis más rápido y más riguroso.

El denominador comun

Independientemente de tus respuestas, hay algo que aplica a todos: la mayoría de developers no tiene un mapa explícito de la arquitectura de su propio proyecto. La comprensión está en la cabeza — fragmentada, incompleta, y no compartible. Este módulo te enseña a externalizar esa comprensión en artefactos concretos.

Vocabulario Clave

Estos son los términos que usarás a lo largo del módulo. Algunos son nuevos, otros amplían conceptos de módulos anteriores:

Término	Definición
Dependency map	Representación visual o textual de qué módulo depende de qué. Muestra las relaciones de importación entre componentes
Dependency graph	Sinónimo de dependency map, pero enfatiza la estructura de grafo (nodos = módulos, aristas = dependencias)
Flow analysis	Proceso de trazar el camino que siguen los datos o requests a través del sistema, de entrada a salida
Request flow	Caso específico de flow analysis: cómo un HTTP request viaja desde el entry point hasta la response
Data pipeline	Secuencia de transformaciones que sufren los datos: input -> validación -> procesamiento -> storage -> output
Pattern (arquitectural)	Estructura recurrente de organización de código: MVC, service layer, repository, event-driven, etc.
Anti-pattern	Estructura de código que parece funcionar pero genera problemas: circular dependencies, god objects, deep coupling
Circular dependency	A depende de B, y B depende de A. Crea acoplamiento y hace difícil modificar cualquiera de los dos
God object	Una clase o módulo que hace demasiadas cosas — tiene demasiadas responsabilidades
Fan-out	Número de módulos que un módulo dado importa. Fan-out alto = depende de muchos otros
Fan-in	Número de módulos que importan un módulo dado. Fan-in alto = muchos dependen de él
Zoom level	Nivel de detalle del análisis: high-level (componentes), medium (módulos), low (funciones)
Architecture map	El artefacto completo que produces: dependency map + flow analysis + pattern identification + anti-pattern detection
Mermaid	Formato de texto para generar diagramas (grafos, secuencias, flowcharts) que se renderiza en Markdown

No necesitas memorizarlos todos ahora. Los irás usando en cada cápsula y se internalizarán con la práctica.

Objetivo Profesional

Al final de este módulo podras:

Generar dependency maps con Claude Code — mapas que muestran qué módulo depende de qué, a diferentes niveles de zoom: high-level (3-5 componentes principales), medium (módulos dentro de cada componente), y low (funciones dentro de un módulo).
Crear flow analysis para requests completos — desde el entry point (route handler) hasta la respuesta, pasando por middleware, services, repositories, y database. Visualizado como diagramas de secuencia en Mermaid.
Mapear data flow a través del sistema — cómo los datos se transforman: input -> validación -> processing -> storage -> response. Identificar dónde ocurren las transformaciones y qué formato tienen los datos en cada paso.
Identificar patterns arquitecturales — reconocer MVC, service layer, repository pattern, event-driven, y otros patterns en código existente. No para juzgar, sino para entender la estructura intencional del sistema.
Detectar anti-patterns como oportunidades — circular dependencies, god objects, deep coupling, leaky abstractions. Cada anti-pattern identificado es un candidato de refactoring para Phase 2.
Producir un architecture map completo — el artefacto integrador que combina dependency map, flow analysis, pattern identification, y anti-pattern detection en un documento que informa decisiones de refactoring.

El cambio de perspectiva

Entras a este módulo sabiendo explorar e investigar un codebase. Sales sabiendo crear representaciones arquitecturales que no solo documentan lo que existe — informan lo que debe cambiar. Es la diferencia entre un mecánico que sabe abrir el capó y uno que tiene los diagramas del motor.

Por que esto importa en tu carrera

En code reviews: Puedes identificar si un PR introduce dependencias problemáticas o rompe patterns establecidos
En planificación: Puedes estimar el impacto real de un cambio: "esto afecta 3 módulos" vs "esto afecta 15"
En onboarding de otros: Tu architecture map se convierte en la mejor herramienta de onboarding del equipo
En decisiones técnicas: "Reescribir vs refactorizar" es una pregunta que se responde con datos, no con intuición
En entrevistas: Poder analizar y comunicar la arquitectura de un sistema es lo que separa seniors de mid-levels

Progresion del Módulo

Mapa del Módulo

Cápsula	Tema	Qué aprenderás
02	Dependency Maps y Grafos de Dependencias	Generar mapas de dependencias a diferentes niveles de zoom. Detectar circular dependencies y high fan-out. Comparar análisis manual vs Claude Code
03	Flow Analysis — Request->Response y Data Pipelines	Trazar requests de punta a punta. Analizar data flow y transformaciones. Generar diagramas de secuencia con Mermaid
04	Pattern Identification y Anti-Pattern Detection	Reconocer patterns arquitecturales en código existente. Detectar anti-patterns como oportunidades de refactoring
05	Proyecto: Architecture Map de Proyecto Real	Integrar todo en un architecture map completo para un proyecto real. Dependency map + flow analysis + patterns + anti-patterns

Flujo de aprendizaje

Cápsula 02: Dependencies           Cápsula 03: Flows
(qué depende de qué)          ->  (cómo fluyen datos y requests)
        |                                  |
        v                                  v
Cápsula 04: Patterns                     |
(qué patterns se usan               <---+
y cuáles son anti-patterns)
        |
        v
Cápsula 05: Proyecto
(todo integrado en un
architecture map completo)

La narrativa del módulo

Primero aprenderás a mapear las dependencias del sistema — qué módulo depende de qué, a diferentes niveles de detalle (cápsula 02). Con las dependencias mapeadas, trazarás cómo fluyen los datos y requests a través de esas dependencias (cápsula 03). Con dependencias y flujos claros, identificarás los patterns arquitecturales que organizan el código y los anti-patterns que sugieren mejoras (cápsula 04). Finalmente, integrarás todo en un architecture map completo para un proyecto real (cápsula 05).

La progresión es intencional: no puedes analizar flujos sin conocer las dependencias, no puedes identificar anti-patterns sin entender los flujos, y no puedes producir un mapa completo sin las tres piezas anteriores.

Cada cápsula produce un artefacto concreto. No sales de ninguna cápsula solo con "conocimiento" — sales con un documento que puedes usar, compartir, y actualizar.

Conexión con Proyecto

Mini-proyecto del módulo: Architecture Map de Proyecto Real

En la cápsula 05 vas a generar un paquete completo de architecture analysis para un proyecto real. No un ejercicio teórico — un proyecto con dependencias reales, flujos reales, y patterns (y anti-patterns) reales.

Lo que entregarás:

✅ Dependency map a dos niveles de zoom (high-level y medium)
✅ Flow analysis de al menos 2 flujos críticos del sistema
✅ Pattern identification: qué patterns arquitecturales usa el proyecto
✅ Anti-pattern detection: qué oportunidades de mejora identificaste
✅ Architecture summary: documento integrador con hallazgos y recomendaciones

Todo generado con asistencia de Claude Code. El proyecto no evalúa tu conocimiento de software architecture teórico — evalúa tu capacidad de usar Claude Code para analizar la arquitectura que ya existe.

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

El Módulo 8 es una Migración Completa de Proyecto Legacy. El architecture map que produces aquí es el segundo paso de esa migración (después del onboarding del Módulo 1):

Módulo 1: Onboarding -> "Entiendo qué hace el proyecto"
Módulo 2: Explore -> "Puedo investigar cualquier parte"
Módulo 3: Architecture -> "Tengo el mapa completo"           <-- AQUI
    |
    v
Módulo 4: Refactoring -> "Mejoro la estructura del código"
Módulo 5: Migración -> "Cambio frameworks y lenguajes"
Módulo 6: Context -> "Manejo proyectos grandes"
Módulo 7: Legacy -> "Modernizo código viejo"
    |
    v
Módulo 8: Proyecto Integrador -> "Todo junto en una migración real"

El architecture map informa qué refactorizar (Módulo 4), qué migrar (Módulo 5), y qué modernizar (Módulo 7). Sin el mapa, cada decisión de mejora es una apuesta. Con él, es una decisión informada.

Conexión directa con Módulo 4

La transición de Módulo 3 a Módulo 4 es la más importante de la guía:

"Ahora tienes el mapa completo del codebase: structure, dependencies, flows, patterns. Es hora de mejorar lo que encontraste. El primer tipo de mejora es refactoring — cambiar la estructura del código sin cambiar su comportamiento. Y con Claude Code, puedes coordinar refactoring que toca 5, 10, o 20 archivos simultáneamente."

Tu architecture map se convierte en el input del refactoring plan. Las circular dependencies que detectaste se convierten en targets de extract interface. Los god objects se convierten en candidatos de split. Los patterns inconsistentes se convierten en oportunidades de normalización.

Limites: Que NO Se Hara

Para mantener el foco, este módulo tiene límites claros:

❌ No vas a diseñar arquitectura nueva. Este módulo es sobre analizar lo que existe, no diseñar lo que debería ser. No es una clase de software architecture (SOLID, clean architecture, hexagonal, etc.)
❌ No vas a modificar código. El análisis arquitectural es read-only. Modificar código viene en Phase 2 (Módulos 4-7)
❌ No vas a usar herramientas de diagramación externas. Todo se genera con Claude Code — texto y Mermaid. No necesitas Lucidchart, draw.io, ni otras herramientas
❌ No vas a analizar codebases de 100K+ líneas. Context management para proyectos grandes es el Módulo 6. Aquí trabajas con proyectos de 5K-30K líneas
❌ No vas a cubrir deployment architecture (servidores, containers, cloud). El scope es la arquitectura del código fuente
❌ No vas a estudiar software architecture teórica. Los patterns se mencionan para reconocerlos, no para aprenderlos desde cero. Si quieres profundizar en arquitectura de software, hay recursos excelentes en la sección de Recursos Adicionales

Lo que si cubrimos a profundidad:

✅ Dependency maps generados con Claude Code a diferentes niveles de zoom
✅ Flow analysis de requests y data pipelines
✅ Pattern identification en código existente
✅ Anti-pattern detection como base para decisiones de refactoring
✅ Architecture map como artefacto integrador y herramienta de decisión

Evidencia de Exito

Al terminar el módulo, estos son los criterios medibles que demuestran que lo completaste con éxito:

Criterios obligatorios:

Criterio	Cómo verificarlo
Puedes generar un dependency map con Claude Code	Produces un mapa a dos niveles de zoom para un proyecto real
Puedes trazar un request flow de punta a punta	Desde entry point hasta response, con todos los pasos intermedios documentados
Puedes identificar al menos 3 patterns en un codebase	Los nombras, los ubicas en el código, y explicas por qué se usan
Puedes detectar al menos 2 anti-patterns	Los identificas, explicas por qué son problemáticos, y sugieres mejora
Produces un architecture map completo	Documento con dependency map + flow analysis + patterns + anti-patterns

Criterios de excelencia (opcionales):

✅ Tu architecture map es suficientemente claro para que alguien que no conoce el proyecto lo entienda
✅ Identificaste un anti-pattern que no es obvio a primera vista (no solo "este archivo es grande")
✅ Tus diagramas Mermaid son renderizables y útiles (no solo correctos sintácticamente)
✅ Conectaste al menos un anti-pattern con una acción de refactoring concreta

Como se ve el exito en la practica

Antes de este módulo:

"Exploré el codebase, entiendo más o menos cómo funciona"
-> No puedes explicar las dependencias
-> No puedes predecir qué se rompe si cambias algo
-> No puedes priorizar qué refactorizar

Después de este módulo:

"Tengo un architecture map del codebase"
-> Dependency map muestra exactamente qué depende de qué
-> Flow analysis traza cada request de punta a punta
-> Pattern analysis identifica la estructura intencional
-> Anti-pattern detection señala oportunidades de mejora concretas

La pregunta de validación final:

Si alguien te muestra un codebase que nunca has visto y te dice "tengo 2 horas para entender la arquitectura y decidir qué refactorizar primero," puedes hacerlo con confianza y producir un document que respalde tu decisión?

Si la respuesta es sí, completaste este módulo con éxito.

El Principio Central de Este Módulo

Analizar lo que existe, no diseñar lo que debería ser

Este principio distingue este módulo de un curso de software architecture:

Curso de Software Architecture	Este Módulo
"Así deberías diseñar tu sistema"	"Así es como está diseñado este sistema"
Parte de principios teóricos (SOLID, DDD)	Parte de código real que existe
Output: diseño ideal	Output: mapa de lo real
Evalúa: "¿Es correcto el diseño?"	Evalúa: "¿Puedes analizar lo que hay?"

No vas a juzgar si la arquitectura es "correcta" según algún estándar teórico. Vas a mapear lo que existe, identificar patterns, detectar problemas, y documentar hallazgos. El juicio sobre qué cambiar viene después, con la información del mapa.

Los tres niveles de zoom

Un error común al analizar arquitectura es intentar mapear todo al mismo nivel de detalle. Un dependency map con 50 módulos y 200 flechas es ruido visual — no es un mapa útil.

El approach de este módulo usa tres niveles de zoom:

Nivel 1: HIGH-LEVEL (3-5 componentes)
┌──────────┐    ┌──────────┐    ┌──────────┐
│   API    │───>│ Services │───>│ Database │
└──────────┘    └──────────┘    └──────────┘
"¿Cuáles son los bloques principales?"

Nivel 2: MEDIUM (módulos dentro de cada componente)
┌─ API ─────────────┐    ┌─ Services ──────────┐
│ auth_routes       │───>│ user_service         │
│ user_routes       │───>│ payment_service      │
│ payment_routes    │───>│ notification_service  │
└───────────────────┘    └──────────────────────┘
"¿Qué módulos hay dentro de cada bloque?"

Nivel 3: LOW (funciones dentro de un módulo)
┌─ user_service ────────────┐
│ get_user()                │
│ create_user()             │
│ update_user()             │
│ delete_user()             │
│ _validate_email()         │
│ _hash_password()          │
└───────────────────────────┘
"¿Qué hace cada módulo internamente?"

Tú eliges el nivel de detalle según tu necesidad. Para entender la big picture, Nivel 1. Para planificar un refactoring, Nivel 2. Para entender una función específica, Nivel 3.

Claude Code te da velocidad, tu pones el juicio

Claude Code puede generar un dependency map en 30 segundos. Pero interpretar ese mapa — decidir qué significa, qué es un problema, y qué hacer al respecto — es tu trabajo profesional.

Este módulo te enseña ambas partes: cómo pedir a Claude Code que genere los artefactos, y cómo leer esos artefactos para tomar decisiones.

Prerequisites del Módulo

Conocimiento requerido:

✅ Módulo 1 completado: Método de las 5 preguntas, onboarding doc, exploración con Claude Code
✅ Módulo 2 completado: Explore subagent, búsqueda semántica, patrones de exploración
✅ Python intermedio: Leer imports, entender clases y funciones, seguir flujos de datos
✅ Git básico: Clonar repos, navegar historial
✅ Claude Code fluido: Formular prompts de análisis, interpretar respuestas largas

No necesitas:

❌ Conocimiento previo de software architecture (SOLID, DDD, hexagonal, etc.)
❌ Experiencia con herramientas de diagramación
❌ Conocimiento de Mermaid syntax (se explica en las cápsulas)
❌ Experiencia con refactoring (eso viene en Phase 2)

Verificacion de setup

# Verifica Claude Code
claude --version
# Esperado: version instalada

# Verifica Python
python --version
# Esperado: Python 3.10+

# Verifica que tienes un proyecto para analizar
# (el que usaste en Módulos 1-2, o uno nuevo)
ls tu-proyecto/
# Esperado: archivos del proyecto

Distribucion de Tiempo Estimada

Cápsula	Tiempo estimado	Actividad principal
01 (esta)	10-15 min	Lectura: objetivos y contexto del módulo
02	20-25 min	Dependency maps y grafos de dependencias
03	20-25 min	Flow analysis: request->response y data pipelines
04	20-25 min	Pattern identification y anti-pattern detection
05	40-50 min	Proyecto: architecture map de proyecto real
Total	~1.75-2.5 hrs

El módulo está diseñado para completarse en una sesión larga o dos sesiones cortas. Si necesitas dividirlo, el punto natural de pausa es después de la cápsula 03 (flow analysis). Las primeras tres cápsulas construyen los skills individuales; la cápsula 04 los combina; la cápsula 05 los aplica a un proyecto real.

Resumen

✅ Este módulo cierra Phase 1: transforma exploración (M1) y acceso preciso (M2) en comprensión arquitectural documentada
✅ Genera dependency maps a diferentes niveles de zoom: high-level, medium, y low
✅ Produce flow analysis: cómo fluyen requests y datos a través del sistema
✅ Identifica patterns arquitecturales y detecta anti-patterns como oportunidades de refactoring
✅ Todo generado con Claude Code — tú interpretas y decides qué hacer con los hallazgos
✅ El foco es analizar lo que existe, no diseñar lo que debería ser
✅ El architecture map que produces es el input directo del Módulo 4 (Refactoring)
✅ Anti-patterns son oportunidades de mejora, no críticas al autor original

Recursos Adicionales

Working Effectively with Legacy Code — Michael Feathers — El libro de referencia sobre entender y trabajar con código existente. Contexto fundamental para todo el análisis arquitectural.
Software Architecture in Practice — Bass, Clements & Kazman — Referencia completa de arquitectura de software. Útil si quieres profundizar en los patterns que reconoces en este módulo.
Mermaid Documentation — Documentación oficial de Mermaid para diagramas. Usarás este formato para generar dependency graphs y sequence diagrams.
Visualizing Software Architecture — Simon Brown (C4 Model) — El modelo C4 para visualizar arquitectura a diferentes niveles de zoom. Inspiración directa para el approach de este módulo.
Claude Code Documentation — Anthropic — Documentación oficial de Claude Code. Features de análisis de código y generación de diagramas.
Software Design X-Rays — Adam Tornhill — Análisis de codebases usando datos de versión control. Complementa el análisis con AI del módulo.
Refactoring Guru — Anti-Patterns — Catálogo visual de anti-patterns con explicaciones y soluciones. Referencia rápida para la cápsula 04.

Siguiente cápsula: Dependency Maps y Grafos de Dependencias — qué módulo depende de qué, a diferentes niveles de zoom, generados con Claude Code.

Módulo 3, Cápsula 01 — Refactoring & Legacy Code with Claude Code Guide

← AnteriorProyecto del Módulo: Exploración de Codebase con Explore Siguiente →Dependency Maps y Grafos de Dependencias