Módulo 3: Entender Arquitectura Existente

Proyecto del Módulo: Architecture Map de Proyecto Real

Siguiente →

Proyecto del Módulo: Architecture Map de Proyecto Real

Descripción del proyecto

Este es el proyecto que cierra Phase 1 de la guía. Vas a producir un Architecture Map completo de un proyecto real — un documento que combina dependency maps (cápsula 02), flow analysis (cápsula 03), y pattern/anti-pattern identification (cápsula 04) en un artefacto profesional que cualquier developer puede consultar.

Este proyecto tiene un peso especial porque su output es el input directo del Módulo 4 (Refactoring Multi-File Coordinado). El Architecture Map que produces aquí informa qué refactorizar, en qué orden, y con qué riesgos. Sin este mapa, el refactoring es una apuesta; con él, es una decisión informada.

El escenario es realista: tu equipo necesita planificar el próximo trimestre de mejoras técnicas. Para hacerlo, necesitan un análisis arquitectural del codebase principal. Tú produces ese análisis usando Claude Code. El entregable no es un ejercicio académico — es un documento de trabajo que informa decisiones de ingeniería.

La diferencia con el proyecto del Módulo 1 (onboarding) y del Módulo 2 (exploración) es el nivel de formalidad y completitud. Aquí no solo exploras y documentas hallazgos — produces un analysis package con tres componentes estructurados, conclusiones accionables, y un plan de mejora priorizado.

Objetivo del Proyecto

Generar un Architecture Map completo de un proyecto real usando Claude Code, integrando dependency analysis, flow analysis, y pattern identification en un documento profesional de referencia.

Al completar este proyecto:

  • ✅ Habrás generado dependency maps a múltiples niveles de zoom
  • ✅ Habrás trazado al menos 2 flujos críticos del proyecto
  • ✅ Habrás identificado patterns y anti-patterns con priorización
  • ✅ Habrás producido un documento de referencia para el equipo
  • ✅ Habrás conectado findings con decisiones de refactoring accionables

Especificaciones Técnicas

Codebase a Analizar

Opción A — Proyecto sugerido (recomendada para aprendizaje):

Usa el mismo proyecto que exploraste en los Módulos 1-2 (httpx, typer, rich, o fastapi). Esto te permite profundizar en un codebase que ya conoces superficialmente.

Opción B — Tu propio proyecto:

Si trabajas en un proyecto real que necesita architecture analysis, úsalo. El beneficio es que produces un artefacto útil para tu equipo.

Requisitos mínimos del codebase:

  • Al menos 5K líneas de código
  • Al menos 3 directorios/módulos principales
  • Al menos 1 dependency externa significativa
  • Algún grado de complejidad arquitectural (no un solo archivo)

Herramientas

  • Claude Code con Explore subagent
  • Terminal para grep complementario
  • Editor de texto para el documento final
  • Opcional: Mermaid Live Editor para visualizar diagramas

Setup

# Si usas un proyecto nuevo:
git clone [URL_del_proyecto]
cd [nombre_del_proyecto]
claude

# Si continúas con el proyecto de Módulos 1-2:
cd [nombre_del_proyecto]
claude

Los 3 Componentes del Architecture Map

Componente 1: Dependency Analysis

Qué debes producir:

  1. Dependency map de alto nivel — Diagrama mostrando los 4-6 componentes principales y cómo se conectan
  2. Dependency map de un módulo crítico — Diagrama detallado de un módulo con dependencias salientes y entrantes
  3. Tabla de dependencias externas — Cada librería/paquete externo, qué se usa, y dónde

Formato del deliverable:

### 1. Dependency Analysis

#### 1.1 High-Level Dependency Map

[Diagrama mermaid o ASCII]

**Descripción:** [1-2 párrafos describiendo la estructura]

#### 1.2 Detailed: [Módulo crítico]

Dependencias salientes:
| Módulo | Qué importa | Para qué |
|--------|-------------|----------|
| ... | ... | ... |

Dependientes entrantes:
| Módulo | Qué usa | Riesgo si cambia |
|--------|---------|------------------|
| ... | ... | ... |

[Diagrama mermaid del módulo]

#### 1.3 Dependencias Externas

| Paquete | Versión | Uso principal | Archivos que lo usan |
|---------|---------|---------------|---------------------|
| ... | ... | ... | ... |

#### 1.4 Hallazgos de Dependencies

- [Hallazgo 1: e.g., "Circular dependency entre X e Y"]
- [Hallazgo 2: e.g., "Módulo Z tiene fan-out de 12"]
- [Hallazgo 3: e.g., "Dependencia A está deprecated"]

Prompts sugeridos:

> "Genera un dependency map de alto nivel del proyecto.
   Muestra los 5-6 componentes principales y las
   dependencias entre ellos. Formato mermaid."

> "Analiza las dependencias de [módulo crítico].
   Lista dependencias salientes y entrantes con detalle."

> "Lista todas las dependencias externas del proyecto
   con versión, uso principal, y archivos que las usan."

> "¿Hay dependencias circulares, módulos con exceso
   de dependencias, o dependencias deprecated?"

Componente 2: Flow Analysis

Qué debes producir:

  1. Flujo principal — Trace completo del flujo más importante del proyecto (el happy path del feature principal)
  2. Flujo secundario — Trace de un segundo flujo significativo (puede ser error handling, un flujo async, o un background job)
  3. Data transformation — Cómo se transforman los datos en al menos uno de los flujos

Formato del deliverable:

### 2. Flow Analysis

#### 2.1 Flujo Principal: [Nombre del flujo]

**Trigger:** [Qué inicia el flujo]
**Resultado:** [Qué produce]

| Paso | Archivo | Función | Input | Output |
|------|---------|---------|-------|--------|
| 1 | ... | ... | ... | ... |
| 2 | ... | ... | ... | ... |
| ... | ... | ... | ... | ... |

[Diagrama de secuencia mermaid]

**Side effects:** [Lista de todo lo que pasa además del resultado principal]

**Error handling:** [Cómo se manejan errores en cada paso crítico]

#### 2.2 Flujo Secundario: [Nombre]

[Misma estructura]

#### 2.3 Data Transformation: [Nombre del flujo]

| Paso | Estructura de datos |
|------|-------------------|
| Input | `{campo1: tipo, campo2: tipo}` |
| Después de validación | `{...campos validados...}` |
| Después de procesamiento | `{...campos enriquecidos...}` |
| Lo que se guarda en DB | `{...modelo de DB...}` |
| Response al cliente | `{...campos de respuesta...}` |

#### 2.4 Hallazgos de Flows

- [Hallazgo 1: e.g., "El flujo de checkout no tiene rollback si el email falla"]
- [Hallazgo 2: e.g., "Hay 3 side effects no documentados en la creación de órdenes"]

Prompts sugeridos:

> "Rastrear el flujo completo de [feature principal].
   Para cada paso: archivo, función, input, output."

> "Generar diagrama de secuencia mermaid para [flujo]."

> "Rastrear cómo se transforman los datos en [flujo]
   desde el input hasta lo que se guarda en DB."

> "¿Hay puntos en [flujo] donde un error podría dejar
   datos inconsistentes?"

Componente 3: Pattern & Anti-Pattern Analysis

Qué debes producir:

  1. Patterns identificados — Qué patterns arquitecturales usa el proyecto
  2. Anti-patterns encontrados — Lista priorizada de anti-patterns con severidad
  3. Plan de mejora — Top 5 acciones de refactoring priorizadas

Formato del deliverable:

### 3. Pattern & Anti-Pattern Analysis

#### 3.1 Patterns Arquitecturales

| Pattern | Dónde | Consistencia | Notas |
|---------|-------|-------------|-------|
| [e.g., Service Layer] | src/services/ | Alta | Controllers delgados, services con lógica |
| [e.g., Repository] | src/repos/ | Media | Solo para User y Order, no para Product |
| ... | ... | ... | ... |

#### 3.2 Anti-Patterns Encontrados

| # | Anti-Pattern | Archivo | Severidad | Impacto |
|---|-------------|---------|-----------|---------|
| 1 | [e.g., God Object] | [path] | Alta | [descripción] |
| 2 | [e.g., Circular Dep] | [paths] | Media | [descripción] |
| ... | ... | ... | ... | ... |

#### 3.3 Plan de Mejora Priorizado

| Prioridad | Acción | Anti-Pattern | Riesgo | Impacto |
|-----------|--------|-------------|--------|---------|
| 1 | [e.g., Eliminar dead code] | Dead Code | Bajo | Medio |
| 2 | [e.g., Separar UserManager] | God Object | Alto | Alto |
| 3 | [e.g., Resolver circular dep auth↔user] | Circular | Medio | Alto |
| 4 | ... | ... | ... | ... |
| 5 | ... | ... | ... | ... |

Estructura del Entregable Final

# Architecture Map: [Nombre del Proyecto]

**Analista:** [Tu nombre]
**Fecha:** [Fecha]
**Codebase:** [URL o descripción]
**Herramientas:** Claude Code + Explore subagent

## Executive Summary

[3-5 frases: qué es el proyecto, cuál es su estado arquitectural,
y las 2-3 conclusiones más importantes]

---

## 1. Dependency Analysis
[Componente 1 completo]

---

## 2. Flow Analysis
[Componente 2 completo]

---

## 3. Pattern & Anti-Pattern Analysis
[Componente 3 completo]

---

## 4. Conclusiones y Recomendaciones

### Fortalezas arquitecturales
- [Lo que está bien diseñado]
- [Patterns que funcionan]

### Áreas de mejora
- [Top 3 anti-patterns a resolver]

### Plan de acción recomendado
1. [Acción inmediata (bajo riesgo)]
2. [Acción a corto plazo]
3. [Acción a mediano plazo]

---

## 5. Métricas

| Métrica | Valor |
|---------|-------|
| Tiempo total de análisis | [X minutos/horas] |
| Prompts a Claude Code | [X] |
| Archivos analizados | [X] |
| Anti-patterns encontrados | [X] |
| Dependencias externas | [X] |

---

## Apéndice: Prompts Utilizados

[Lista de todos los prompts exactos usados, para reproducibilidad]

Criterios de Éxito

Tu proyecto está completo cuando:

  • ✅ Dependency map de alto nivel con diagrama incluido
  • ✅ Dependency map detallado de al menos 1 módulo
  • ✅ Al menos 2 flujos trazados con pasos detallados
  • ✅ Al menos 1 data transformation documentada
  • ✅ Patterns arquitecturales identificados y nombrados
  • ✅ Al menos 3 anti-patterns encontrados con severidad
  • ✅ Plan de mejora priorizado con 5 acciones
  • ✅ Executive summary conciso y accionable
  • ✅ Prompts documentados para reproducibilidad
  • ✅ El documento es legible por cualquier developer del equipo

Rúbrica de Evaluación (100 puntos)

Dependency Analysis (30 puntos)

  • (10 pts) Dependency map de alto nivel completo con diagrama
  • (10 pts) Análisis detallado de 1+ módulo con salientes/entrantes
  • (5 pts) Tabla de dependencias externas
  • (5 pts) Hallazgos de dependencies documentados

Flow Analysis (30 puntos)

  • (10 pts) Flujo principal trazado paso a paso con diagrama
  • (10 pts) Flujo secundario trazado
  • (5 pts) Data transformation documentada
  • (5 pts) Hallazgos de flows (errores, side effects, inconsistencias)

Pattern Analysis (25 puntos)

  • (8 pts) Patterns arquitecturales identificados correctamente
  • (8 pts) Anti-patterns encontrados con severidad asignada
  • (9 pts) Plan de mejora priorizado (5 acciones con impacto/riesgo)

Documentación y Profesionalismo (15 puntos)

  • (5 pts) Executive summary claro y accionable
  • (5 pts) Prompts documentados (reproducibilidad)
  • (3 pts) Métricas de tiempo completas
  • (2 pts) Formato limpio, legible, profesional

Extra Credit (hasta +10 puntos)

  • (+3 pts) Diagramas mermaid renderizados (no solo código)
  • (+3 pts) Comparación con documentation existente del proyecto
  • (+2 pts) 3+ flujos trazados (en vez del mínimo de 2)
  • (+2 pts) Recomendaciones incluyen estimación de esfuerzo

Ejemplo de Implementación Mínima

Este es un ejemplo abreviado del Executive Summary y Componente 1 para el proyecto httpx:

# Architecture Map: httpx

**Analista:** [Nombre]
**Fecha:** Abril 2026
**Codebase:** https://github.com/encode/httpx

## Executive Summary

httpx es un HTTP client Python con soporte sync y async. La arquitectura
sigue un patrón de capas limpias: API pública (convenience functions) →
Client (session management) → Transport (conexión HTTP) → httpcore
(protocolo). La principal fortaleza es la separación de concerns entre
capas. Las principales áreas de mejora son: acoplamiento entre Client
y Transport, y falta de abstracción consistente para HTTP/1.1 vs HTTP/2.

## 1. Dependency Analysis

### 1.1 High-Level Dependency Map

```mermaid
graph TD
    API[_api.py - Convenience] --> Client[_client.py - Session]
    Client --> Transport[_transports/ - Connection]
    Client --> Models[_models.py - Request/Response]
    Client --> Auth[_auth.py - Authentication]
    Transport --> httpcore[httpcore - Protocol]
    Models --> URLLib[_urls.py - URL handling]

Descripción: httpx tiene 4 capas principales. La capa API es un thin wrapper sobre Client. Client maneja sessions, auth, y redirects. Transport maneja la conexión HTTP real delegando a httpcore. Models define Request y Response como objetos inmutables.

[... continúa con el resto del análisis ...]


---

## Errores Comunes

### Error 1: Architecture Map demasiado superficial

**Ejemplo:** Dependency map de 3 cajas sin detalles. Flows de 2 pasos.
**Solución:** Profundiza. El map de alto nivel tiene 4-6 componentes. El detallado tiene 8+ dependencias. Los flows tienen 5+ pasos.

### Error 2: Anti-patterns sin priorización

**Ejemplo:** Lista de 10 anti-patterns sin severidad ni plan de acción.
**Solución:** Toda lista necesita priorización. Usa la matriz impacto/riesgo.

### Error 3: No incluir prompts

**Ejemplo:** Análisis completo pero sin documentar cómo se generó.
**Solución:** Los prompts son parte del entregable. Permiten reproducibilidad y enseñan a otros a hacer lo mismo.

### Error 4: Copiar output de Claude Code sin interpretar

**Ejemplo:** "Claude Code reportó: [raw output]"
**Solución:** Claude Code genera datos. Tú produces análisis. Interpreta, conecta puntos, saca conclusiones.

### Error 5: Ignorar inconsistencias

**Ejemplo:** El dependency map muestra que A no depende de B, pero el flow trace muestra que A llama a B.
**Solución:** Investiga y resuelve. Una inconsistencia entre dependency map y flow trace puede indicar dependencia oculta (via eventos, globals, o reflection).

### Error 6: Plan de mejora genérico

**Ejemplo:** "Mejorar la arquitectura y reducir tech debt."
**Solución:** Acciones específicas: "Separar UserManager en UserAuthService y UserProfileService" con archivos concretos.

### Error 7: No conectar con refactoring

**Ejemplo:** Architecture Map sin plan de acción.
**Solución:** El Componente 3 debe terminar con 5 acciones priorizadas que son directamente ejecutables en el Módulo 4.

### Error 8: Elegir un proyecto sin complejidad

**Ejemplo:** Analizar un proyecto de 200 líneas con 1 archivo.
**Solución:** Mínimo 5K líneas, 3+ módulos. Si no hay complejidad, no hay nada que analizar.

---

## Recursos para el Proyecto

1. [Mermaid Live Editor](https://mermaid.live/) - Para visualizar y refinar diagramas mermaid
2. [Architecture Decision Records](https://adr.github.io/) - Formato estándar para documentar decisiones arquitecturales
3. [C4 Model](https://c4model.com/) - Framework de diagramación de arquitectura por niveles de zoom
4. [httpx - GitHub](https://github.com/encode/httpx) - Proyecto sugerido para análisis
5. [pydeps](https://pypi.org/project/pydeps/) - Generador de grafos de dependencia para Python
6. [Architecture Review Checklist](https://wiki.sei.cmu.edu/confluence/display/ARID) - Checklist de revisión arquitectural del SEI/CMU

---

## Conexión con Siguiente Módulo

Este Architecture Map es el cierre de **Phase 1: Entender Codebases**. Todo lo que sigue en Phase 2 se construye sobre este fundamento.

El **Módulo 4: Refactoring Multi-File Coordinado** toma tu plan de mejora priorizado y lo ejecuta. La transición es directa:

- Los **anti-patterns** que encontraste son los targets de refactoring
- Los **dependency maps** te muestran qué archivos se verán afectados por cada cambio
- Los **flow traces** te confirman que el comportamiento se preserva después del refactoring
- El **plan de mejora** es tu backlog de trabajo

"Ahora tienes el mapa completo del codebase: estructura, dependencias, flujos, 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."
← AnteriorPattern Identification y Anti-Pattern DetectionSiguiente →Módulo 4: Refactoring Multi-File Coordinado