Módulo 1: Onboarding con AI — 5-10x Más Rápido

Proyecto del Módulo: Onboarding a Codebase Open-Source

Descripción del proyecto

Vas a tomar un proyecto open-source real de Python — uno que nunca hayas visto antes — y aplicar todo lo que aprendiste en este módulo para entenderlo en profundidad. No vas a escribir código nuevo desde cero. Vas a leer, analizar, documentar, y validar tu comprension de un codebase existente usando Claude Code como tu herramienta principal.

Este proyecto integra los tres skills fundamentales del módulo: exploracion sistematica (las 5 preguntas), construccion de mental model (3 niveles), y documentación de hallazgos (onboarding doc de 6 secciones). No puedes completar el proyecto sin haber dominado los tres — y al completarlo, tendras evidencia tangible de que los dominas.

La razon por la que usamos un proyecto open-source real (no un proyecto de ejemplo) es intencional: en tu trabajo diario, el código que necesitas entender no fue disenado para ser fácil de aprender. Tiene decisiones historicas, tech debt, patterns inconsistentes, y documentación parcial. Un proyecto open-source de 5K-10K lineas te da exactamente esa experiencia, pero en un contexto donde puedes verificar tu comprension sin riesgo.

Al completar este proyecto tendras tres artefactos: un registro de tu exploracion sistematica (las 5 preguntas respondidas), un mental model documentado en 3 niveles, y un onboarding doc profesional. Además, habras hecho un cambio pequeno al codebase para validar que tu mental model es correcto — y tendras una comparacion de tiempo que demuestra el impacto de usar AI para onboarding.

Objetivo del Proyecto

Hacer onboarding a un codebase open-source de Python de 5K-10K lineas en menos de 2 horas, produciendo documentación que otro developer podria usar para entender el proyecto.

Al completar este proyecto:

✅ Habras aplicado el método de las 5 preguntas iniciales a un proyecto real
✅ Tendras un mental model de 3 niveles documentado con diagramas
✅ Habras producido un onboarding doc profesional de 6 secciones
✅ Habras validado tu comprension con un cambio pequeno al codebase
✅ Tendras una comparacion de tiempo AI vs estimacion manual

Especificaciones Tecnicas

Stack Tecnologico

Lenguaje: Python 3.10+
Herramienta principal: Claude Code (linea de comandos)
Control de versión: Git
Formato de documentación: Markdown
Diagramas: Mermaid y/o ASCII

Proyecto Open-Source a Elegir

Elige UNO de estos proyectos (o uno similar que cumpla los criterios):

Proyecto	Lineas aprox.	Que hace	Dificultad
httpx	~10K	HTTP client moderno (sync + async)	Media
typer	~5K	CLI framework basado en type hints	Media-baja
rich	~15K	Terminal formatting and rendering	Media-alta
pydantic-settings	~3K	Manejo de configuración con Pydantic	Baja
textual	~20K	Framework TUI (Terminal UI)	Alta

Criterios si eliges otro proyecto:

✅ Python puro (no C extensions como requisito)
✅ Entre 3K-15K lineas de código (sin contar tests)
✅ Activamente mantenido (commits en los ultimos 3 meses)
✅ Con tests (para que puedas verificar que tu cambio no rompe nada)
❌ No uses un proyecto que ya conozcas bien
❌ No uses un proyecto con menos de 3K lineas (demasiado simple)

Setup Inicial

# Paso 1: Crear directorio de trabajo
mkdir onboarding-project
cd onboarding-project

# Paso 2: Clonar el proyecto elegido (ejemplo con httpx)
git clone https://github.com/encode/httpx.git
cd httpx

# Paso 3: Crear ambiente virtual
python -m venv venv
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# Paso 4: Instalar dependencias
pip install -e ".[dev]"
# O alternativamente:
pip install -r requirements.txt

# Paso 5: Verificar que los tests pasan (baseline)
pytest --tb=short -q
# Deberia ver algo como: "142 passed, 3 skipped"

# Paso 6: Verificar que Claude Code puede acceder al proyecto
claude "Cuantos archivos Python tiene este proyecto?
Cuantas lineas de codigo aproximadamente?"

Importante: Antes de empezar tu exploracion, verifica que los tests pasan. Ese es tu baseline — cualquier cambio que hagas debe mantener los tests pasando.

Si el setup falla:

# Problema comun: dependencias que requieren compilacion C
# Solucion: instalar solo las dependencias core
pip install -e .

# Problema comun: tests requieren servicios externos (Redis, DB)
# Solucion: correr solo unit tests
pytest tests/unit/ -q --tb=short

# Problema comun: version de Python incompatible
python --version
# Si es < 3.10, usa pyenv para instalar la version correcta:
# pyenv install 3.11.0
# pyenv local 3.11.0

# Verificar que Claude Code funciona en el proyecto
claude "Cuantos archivos Python hay en este directorio?
Excluye tests y __pycache__."

Estructura de Entregables

Tu directorio final debe verse así:

onboarding-project/
├── httpx/                    # (o el proyecto que elegiste)
│   └── ... (con tu cambio pequeno aplicado)
├── entregables/
│   ├── 01-exploracion-sistematica.md
│   ├── 02-mental-model.md
│   ├── 03-onboarding-doc.md
│   ├── 04-cambio-validacion.md
│   └── 05-comparacion-tiempo.md
└── README.md                 # Resumen del proyecto

Funcionalidades Obligatorias

1. Exploracion Sistematica — Las 5 Preguntas

Entregable: entregables/01-exploracion-sistematica.md

Debes responder las 5 preguntas de exploracion sistematica usando Claude Code. Para cada pregunta, documenta:

El prompt exacto que usaste con Claude Code
La respuesta que obtuviste
Tu análisis/interpretacion de la respuesta

Las 5 preguntas:

## Pregunta 1: Cual es la estructura del proyecto?

### Prompt usado:
[El prompt exacto que le diste a Claude Code]

### Respuesta de Claude Code:
[La respuesta completa]

### Mi analisis:
[Tu interpretacion: que te sorprendio, que esperabas,
que no quedo claro]

---

## Pregunta 2: Donde estan los entry points?

[Mismo formato]

---

## Pregunta 3: Como fluyen los datos?

[Mismo formato]

---

## Pregunta 4: Que patterns se usan?

[Mismo formato]

---

## Pregunta 5: Donde esta el tech debt?

[Mismo formato]

Que debe hacer:

✅ Responder las 5 preguntas en orden (big picture primero, detalles después)
✅ Incluir los prompts exactos (para que sea reproducible)
✅ Incluir la respuesta de Claude Code (no resumida — completa)
✅ Incluir tu análisis personal de cada respuesta
✅ Marcar cosas que te sorprendieron o que no entendiste

2. Mental Model Documentado — 3 Niveles

Entregable: entregables/02-mental-model.md

Debes construir y documentar tu mental model en los 3 niveles aprendidos en la capsula 04.

## Nivel 1: High-Level — Architecture y Layers

### Diagrama de Layers
[Diagrama ASCII o Mermaid de los layers del proyecto]

### Componentes Principales
[Lista de componentes con breve descripcion]

### Entry Points
[Donde entra la ejecucion al sistema]

### Exit Points
[Donde sale informacion: DB, API, archivos, etc.]

---

## Nivel 2: Mid-Level — Modules y Dependencies

### Mapa de Dependencias
[Para los 5 modulos mas importantes: de quien dependen
y quien depende de ellos]

### Dependencias Circulares
[Si hay, documentarlas. Si no, confirmarlo.]

### Hub Files
[Los 3-5 archivos mas conectados del proyecto]

---

## Nivel 3: Low-Level — Key Functions y Data Structures

### Funciones Criticas
[Las 3-5 funciones mas importantes. Para cada una:
input, output, side effects, error handling]

### Data Structures Principales
[Las 3-5 data structures mas importantes.
Para cada una: campos, relaciones, donde se crea/consume]

### Data Flow de la Operacion Principal
[Flujo paso a paso de la operacion mas comun del proyecto]

Que debe hacer:

✅ Cubrir los 3 niveles (no solo el Nivel 1)
✅ Incluir al menos un diagrama (ASCII o Mermaid)
✅ Documentar los hub files (archivos mas conectados)
✅ Incluir el data flow de al menos una operación end-to-end
✅ Ser específico (nombres reales de archivos, funciones, clases)

3. Onboarding Doc Profesional — 6 Secciones

Entregable: entregables/03-onboarding-doc.md

Debes producir un onboarding doc completo siguiendo la estructura de 6 secciones de la capsula 05.

# Onboarding Doc: [Nombre del Proyecto]

**Generado:** [Fecha]
**Autor:** [Tu nombre] (con asistencia de Claude Code)
**Proyecto:** [Nombre y URL del repo]
**Tiempo de onboarding:** [Cuanto te tomo]

---

## Tabla de Contenido
1. Project Overview
2. Architecture Overview
3. Key Patterns
4. Gotchas
5. Data Flows
6. Como Empezar

---

## 1. Project Overview
[Que hace, stack, tamano, estado, consumidores]

## 2. Architecture Overview
[Layers, estructura de directorios, entry points, dependencias]

## 3. Key Patterns
[Patterns arquitecturales, naming, error handling, testing]

## 4. Gotchas
[Minimo 5 gotchas especificas del proyecto]

## 5. Data Flows
[Minimo 2 data flows documentados paso a paso]

## 6. Como Empezar
[Setup, tests, como contribuir, archivos que leer primero]

Que debe hacer:

✅ Tener las 6 secciones completas
✅ La sección Gotchas debe tener minimo 5 items especificos
✅ La sección Data Flows debe tener minimo 2 flujos documentados
✅ La sección Como Empezar debe ser funcional (seguir los pasos debe funcionar)
✅ Estar escrito para un developer que NO conoce el proyecto
✅ Incluir al menos una opinion personal (no solo output de Claude Code)

4. Cambio de Validación

Entregable: entregables/04-cambio-validacion.md

Debes hacer UN cambio pequeno al codebase para validar tu comprension. El cambio puede ser:

Agregar un test para una función que no esta testeada
Mejorar un docstring existente
Agregar type hints a una función que no los tiene
Fix un typo en código o documentación
Agregar logging a una función critica

Documenta:

## Cambio Realizado

### Que cambie:
[Descripcion del cambio en 1-2 frases]

### Archivo(s) modificado(s):
[Lista de archivos]

### Prediccion antes del cambio:
"Si hago [cambio], espero que [consecuencia].
Los tests [deberian/no deberian] pasar porque [razon]."

### Resultado real:
[Que paso al hacer el cambio? Tu prediccion fue correcta?]

### Verificacion:
```bash
# Comando para verificar que los tests pasan
pytest --tb=short -q
# Resultado: [X passed, Y skipped]

Aprendizaje:

[Que aprendiste de este cambio sobre tu mental model? Hubo algo que no predijiste correctamente?]


**Que debe hacer:**

- ✅ El cambio debe ser real (no simulado)
- ✅ Debes predecir el resultado ANTES de hacer el cambio
- ✅ Los tests deben seguir pasando después del cambio
- ✅ Documentar si tu prediccion fue correcta o no
- ✅ Explicar que aprendiste sobre tu mental model

### 5. Comparacion de Tiempo

**Entregable:** `entregables/05-comparacion-tiempo.md`

Debes comparar cuanto tardaste con Claude Code vs cuanto habrias tardado sin AI.

```markdown
## Comparacion de Tiempo

### Tiempo Real (con Claude Code)

| Actividad | Tiempo |
|-----------|--------|
| Setup y verificacion de tests | X min |
| Exploracion sistematica (5 preguntas) | X min |
| Mental model Nivel 1 | X min |
| Mental model Nivel 2 | X min |
| Mental model Nivel 3 | X min |
| Onboarding doc — Project Overview | X min |
| Onboarding doc — Architecture | X min |
| Onboarding doc — Key Patterns | X min |
| Onboarding doc — Gotchas | X min |
| Onboarding doc — Data Flows | X min |
| Onboarding doc — Como Empezar | X min |
| Cambio de validacion | X min |
| **TOTAL** | **X min** |

### Estimacion Manual (sin AI)

| Actividad | Estimacion |
|-----------|-----------|
| Setup y verificacion de tests | X min |
| Leer estructura de directorios manualmente | X min |
| Leer archivos principales (grep, lectura) | X hrs |
| Construir mental model por lectura de codigo | X hrs |
| Documentar hallazgos manualmente | X hrs |
| Hacer cambio de validacion | X min |
| **TOTAL ESTIMADO** | **X hrs** |

### Factor de Aceleracion

Tiempo con Claude Code: X horas
Estimacion manual: Y horas
Factor: Y/X = Zx mas rapido

### Reflexion

[En 3-5 frases: donde fue mas util Claude Code? Donde no ayudo?
Que harias diferente la proxima vez?]

Que debe hacer:

✅ Trackear el tiempo real de cada actividad
✅ Estimar honestamente cuanto habria tardado sin AI
✅ Calcular el factor de aceleracion
✅ Reflexionar sobre donde Claude Code fue mas/menos útil

Validaciones y Manejo de Errores

Validaciones Obligatorias

Los tests del proyecto original pasan antes de tu cambio
Los tests del proyecto siguen pasando después de tu cambio
El onboarding doc tiene las 6 secciones completas
El mental model tiene los 3 niveles documentados
Las 5 preguntas de exploracion estan respondidas con prompts reales
La comparacion de tiempo tiene datos reales (no inventados)

Manejo de Errores Comunes

Error: Los tests no pasan antes de empezar

# Algunos proyectos tienen tests que requieren dependencias especificas
# Intenta instalar todas las dependencias de desarrollo
pip install -e ".[dev,test]"

# Si hay tests que fallan por environment (Redis, DB, etc.)
# Corre solo los unit tests
pytest tests/unit/ --tb=short -q

# Si persiste, documenta cuales fallan y por que
pytest --tb=short 2>&1 | tail -20

Error: Claude Code no puede analizar el proyecto (demasiado grande)

# Enfoca Claude Code en subdirectorios especificos
claude "Analiza SOLO el directorio src/httpx/ (no tests, no docs).
Cuantos archivos tiene y cual es la estructura?"

# Usa @-references para archivos especificos
claude "Analiza @src/httpx/_client.py — que funciones expone
y de que modulos depende?"

Error: No sabes que cambio hacer para la validación

# Pide a Claude Code que sugiera un cambio seguro
claude "Sugiere un cambio pequeno y seguro que pueda hacer
a este proyecto para validar que entiendo la estructura.
Criterios: no rompa tests, sea util, y toque al menos 1
archivo que analice en mi mental model."

Errores que DEBEN manejarse:

Si el proyecto elegido tiene mas de 15K lineas: documenta como enfocaste tu análisis (que partes priorizaste y por que)
Si tu prediccion del cambio de validación fue incorrecta: explica por que fallo y como ajustaste tu mental model
Si alguna sección del onboarding doc queda incompleta: explica por que y que harias con mas tiempo

Guia Paso a Paso Detallada

Esta sección te lleva de la mano por cada fase del proyecto con los prompts exactos que puedes usar.

Fase 1: Setup y Verificacion (10 min)

# 1. Clonar (ejemplo con httpx)
git clone https://github.com/encode/httpx.git
cd httpx

# 2. Ambiente virtual
python -m venv venv
source venv/bin/activate

# 3. Instalar
pip install -e ".[dev]"

# 4. Verificar tests (guardar baseline)
pytest -q --tb=short 2>&1 | tail -5
# Anota cuantos tests pasan — este es tu baseline

# 5. Contar tamano del proyecto
find . -name "*.py" -not -path "*/test*" -not -path "*/__pycache__/*" | \
  xargs wc -l | tail -1
# Deberia dar 5,000+ lineas

# 6. Crear directorio de entregables
mkdir -p ../entregables

Fase 2: Exploracion Sistematica (20 min)

Ejecuta cada pregunta en orden. Copia el prompt y la respuesta a tu documento.

# Pregunta 1: Estructura (4 min)
claude "Analiza la estructura de directorios de este proyecto Python.
Para cada directorio principal, explica que tipo de codigo contiene.
No incluyas __pycache__, .git, ni directorios de build."

# Pregunta 2: Entry Points (4 min)
claude "Identifica los entry points de este proyecto:
1. Que importa un usuario cuando hace 'import httpx'?
2. Que archivo define la API publica del package?
3. Hay entry points CLI o scripts?"

# Pregunta 3: Data Flow (4 min)
claude "Traza el data flow de la operacion principal de este proyecto.
Si es una library HTTP: que pasa cuando un usuario llama
a la funcion principal (get, post, etc.)? Que modulos
se involucran y en que orden?"

# Pregunta 4: Patterns (4 min)
claude "Que patterns de diseno se usan en este proyecto?
Busca: factory pattern, adapter pattern, strategy pattern,
dependency injection, observer, o cualquier otro.
Da ejemplos especificos con nombres de archivos y clases."

# Pregunta 5: Tech Debt (4 min)
claude "Identifica tech debt en este proyecto. Busca:
1. TODOs y FIXMEs en el codigo
2. Codigo comentado
3. Funciones demasiado largas (>50 lineas)
4. Dependencias deprecated
5. Inconsistencias en estilo o patterns"

Después de cada respuesta, agrega tu análisis en el documento. No solo copies — interpreta.

Fase 3: Mental Model — Nivel 1 y 2 (20 min)

# Nivel 1: Arquitectura (10 min)
claude "Genera un analisis de arquitectura de este proyecto:
1. Cuales son los layers o componentes principales?
2. Genera un diagrama ASCII mostrando los layers
3. Cual es la regla de dependencia entre layers?
4. Cuales son las dependencias externas y para que se usan?"

# Nivel 2: Dependencias (10 min)
claude "Analiza las dependencias entre modulos:
1. Para los 5 archivos mas importantes del proyecto,
   lista de que dependen y quien depende de ellos
2. Identifica los hub files (archivos con mas conexiones)
3. Hay dependencias circulares?"

claude "Genera un diagrama Mermaid mostrando las dependencias
entre los 8-10 modulos principales del proyecto.
Usa graph TD con flechas de dependencia."

Fase 4: Mental Model — Nivel 3 (20 min)

# Funciones criticas (10 min)
claude "Identifica las 3 funciones mas criticas de este proyecto.
Para cada una:
1. Firma completa (nombre, parametros, return type)
2. Que hace en 2-3 frases
3. Que side effects tiene
4. Como maneja errores
5. Quien la llama"

# Data structures (5 min)
claude "Cuales son las 3-5 data structures principales?
Para cada una: campos, relaciones, donde se crea, donde se consume."

# Data flow detallado (5 min)
claude "Traza el flujo completo de la operacion mas comun
de este proyecto, paso a paso. Incluye cada archivo y
funcion que se ejecuta, en orden."

Fase 5: Onboarding Doc (30 min)

Genera cada sección por separado para mayor control:

# Seccion 1: Project Overview (3 min)
claude "Genera la seccion 'Project Overview' de un onboarding doc.
Incluye: que hace, stack, tamano (archivos y LOC), estado
(actividad en git), y consumidores principales."

# Seccion 2: Architecture (5 min)
claude "Genera la seccion 'Architecture Overview' con:
diagrama de layers, estructura de directorios, entry points,
dependencias externas y para que se usa cada una."

# Seccion 3: Key Patterns (5 min)
claude "Genera la seccion 'Key Patterns'. Identifica:
patterns arquitecturales con ejemplos de codigo,
naming conventions, patterns de error handling,
patterns de testing."

# Seccion 4: Gotchas (10 min — la mas valiosa)
claude "Genera la seccion 'Gotchas' del onboarding doc.
Busca MINIMO 5 gotchas especificas:
1. Dependencias no obvias entre modulos
2. Side effects ocultos en funciones
3. Configuracion implicita o no documentada
4. Comportamiento que difiere de lo que sugiere el nombre
5. Discrepancias entre documentacion y codigo real
6. Import hacks o workarounds
Cada gotcha debe tener nombre de archivo y explicacion concreta."

# Seccion 5: Data Flows (5 min)
claude "Genera la seccion 'Data Flows' con MINIMO 2 flujos.
Para cada uno: trigger, paso a paso con modulos reales,
side effects, resultado final."

# Seccion 6: Como Empezar (2 min)
claude "Genera la seccion 'Como Empezar': pasos de setup,
como correr tests, como hacer un primer cambio, y los 5
archivos que un developer nuevo deberia leer primero (en orden)."

# Ensamblar y revisar
claude "Revisa este onboarding doc completo. Busca:
1. Inconsistencias entre secciones
2. Informacion faltante
3. Errores factuales vs el codigo real
Sugiere correcciones."

Fase 6: Cambio de Validación (10 min)

# 1. Pedir sugerencia de cambio
claude "Sugiere 3 cambios pequenos que pueda hacer a este proyecto
para validar mi comprension. Criterios:
- Debe tocar un archivo que analice en mi mental model
- No debe romper tests
- Debe ser util (no trivial)
Sugerencias: agregar un test, mejorar un docstring, agregar type hints."

# 2. ANTES de hacer el cambio, escribe tu prediccion:
# "Si hago [cambio X], espero que [consecuencia Y]
#  porque segun mi mental model [razon Z]."

# 3. Hacer el cambio
claude "Haz el siguiente cambio: [descripcion del cambio elegido]"

# 4. Verificar
pytest -q --tb=short
# Los tests deben pasar

Fase 7: Comparacion y Revisión (10 min)

# 1. Anotar tiempos reales de cada fase
# 2. Estimar cuanto habria tardado sin Claude Code
# 3. Escribir reflexion (3-5 frases)
# 4. Revision final de todos los entregables
# 5. Crear README.md del proyecto

Criterios de Exito

Tu proyecto esta completo cuando:

✅ Las 5 preguntas de exploracion estan respondidas con prompts reales y análisis personal
✅ El mental model tiene los 3 niveles con al menos un diagrama
✅ El onboarding doc tiene las 6 secciones con al menos 5 gotchas
✅ Hiciste un cambio real al codebase con prediccion y verificacion
✅ La comparacion de tiempo tiene datos reales y reflexion
✅ Los tests del proyecto pasan después de tu cambio
✅ Todos los entregables estan en la estructura de directorios especificada

Rubrica de Evaluacion (100 puntos)

Funcionalidad (50 puntos)

(10 pts) Exploracion sistematica completa: Las 5 preguntas respondidas con prompts reales, respuestas de Claude Code, y análisis personal para cada una
(10 pts) Mental model de 3 niveles: Nivel 1 (layers, entry points), Nivel 2 (dependencias entre modulos, hub files), Nivel 3 (funciones criticas, data structures, data flow)
(10 pts) Onboarding doc de 6 secciones: Project Overview, Architecture, Key Patterns, Gotchas (minimo 5), Data Flows (minimo 2), Como Empezar (funcional)
(10 pts) Cambio de validación: Cambio real, prediccion previa, verificacion post-cambio, tests pasan, aprendizaje documentado
(10 pts) Comparacion de tiempo: Tiempo real trackeado, estimacion manual razonada, factor de aceleracion calculado, reflexion personal

Código (30 puntos)

(10 pts) Prompts efectivos: Los prompts usados con Claude Code son especificos, bien estructurados, y producen resultados utiles. No son genericos ("explicame este proyecto")
(10 pts) Diagramas y visualizaciones: Al menos 1 diagrama Mermaid o ASCII en el mental model. Al menos 1 data flow documentado con modulos reales y paso a paso
(5 pts) Cambio de validación correcto: El cambio es útil (no trivial), los tests pasan, y demuestra comprension del area del codebase que toca
(5 pts) Reproducibilidad: Siguiendo los prompts documentados, otro developer podria reproducir el análisis

Documentación (20 puntos)

(8 pts) Onboarding doc útil: Un developer que no conoce el proyecto podria leer el doc y entender la arquitectura, patterns, y gotchas en 15-20 minutos
(5 pts) Estructura clara: Los 5 entregables siguen el formato especificado, son navegables, y estan bien organizados
(4 pts) Opiniones personales: El onboarding doc incluye al menos 2-3 observaciones propias (no solo output de Claude Code)
(3 pts) README del proyecto: Incluye un README.md con resumen del proyecto, codebase elegido, y como navegar los entregables

Extra Credit (hasta +10 puntos)

(+3 pts) Versión TL;DR: Crear una versión de 1 página del onboarding doc además de la versión completa
(+3 pts) Segundo data flow: Documentar un tercer data flow (además de los 2 obligatorios)
(+2 pts) Script de validación: Crear un script que verifique que el onboarding doc esta actualizado vs el código
(+2 pts) Comparacion de 2 proyectos: Hacer el onboarding de un segundo proyecto y comparar las arquitecturas

Ejemplo de Implementación Minima

Este es el esqueleto minimo que debes completar. NO es la solución completa — es la estructura base sobre la que construyes.

`entregables/01-exploracion-sistematica.md` (esqueleto)

# Exploracion Sistematica: [Nombre del Proyecto]

## Fecha: [YYYY-MM-DD]
## Proyecto: [URL del repo]

---

## Pregunta 1: Cual es la estructura del proyecto?

### Prompt usado:

claude "Analiza la estructura de directorios de este proyecto. Identifica los directorios principales y que tipo de código contiene cada uno."


### Respuesta de Claude Code:
[Pegar respuesta aqui]

### Mi analisis:
- Lo que esperaba: [...]
- Lo que me sorprendio: [...]
- Lo que no entendi: [...]

---

## Pregunta 2: Donde estan los entry points?

### Prompt usado:

claude "[Tu prompt aquí]"


### Respuesta de Claude Code:
[Pegar respuesta]

### Mi analisis:
[Tu analisis]

---

[Repetir para preguntas 3, 4, 5]

`entregables/02-mental-model.md` (esqueleto)

# Mental Model: [Nombre del Proyecto]

## Nivel 1: High-Level

### Diagrama de Layers

[Tu diagrama ASCII aquí] Layer 1: [nombre] | v Layer 2: [nombre] | v Layer 3: [nombre]


### Entry Points
- [archivo 1] — [que hace]
- [archivo 2] — [que hace]

---

## Nivel 2: Mid-Level

### Mapa de Dependencias (Top 5 Modulos)

**[modulo 1]:**
- Depende de: [lista]
- Dependido por: [lista]

[Repetir para 4 modulos mas]

### Hub Files
1. [archivo] — [X dependencias entrantes, Y salientes]
2. [archivo] — [...]
3. [archivo] — [...]

---

## Nivel 3: Low-Level

### Funcion Critica: [nombre]
- Input: [...]
- Output: [...]
- Side effects: [...]
- Error handling: [...]

[Repetir para 2-4 funciones mas]

### Data Flow: [operacion principal]

[Paso 1] → [Paso 2] → [Paso 3] → [Resultado]

`entregables/03-onboarding-doc.md` (esqueleto)

# Onboarding Doc: [Nombre del Proyecto]

**Generado:** [Fecha]
**Autor:** [Tu nombre]
**Tiempo de onboarding:** [X horas]

---

## 1. Project Overview

**Que es:** [1-2 frases]
**Stack:** [Lenguaje, frameworks, dependencias]
**Tamano:** [~X archivos, ~Y LOC]
**Estado:** [Activo/legacy, frecuencia de commits]

## 2. Architecture Overview

[Diagrama de layers]
[Estructura de directorios]
[Entry points]

## 3. Key Patterns

- [Pattern 1: nombre y ejemplo de codigo]
- [Pattern 2: nombre y ejemplo]
- [Pattern 3: nombre y ejemplo]

## 4. Gotchas

- ⚠️ [Gotcha 1]
- ⚠️ [Gotcha 2]
- ⚠️ [Gotcha 3]
- ⚠️ [Gotcha 4]
- ⚠️ [Gotcha 5]

## 5. Data Flows

### Flow 1: [nombre]
[Paso a paso]

### Flow 2: [nombre]
[Paso a paso]

## 6. Como Empezar

```bash
# Pasos para correr el proyecto

Archivos que leer primero:

[archivo] — [por que]
[archivo] — [por que]
[archivo] — [por que]


### `entregables/04-cambio-validacion.md` (esqueleto)

```markdown
# Cambio de Validacion

## Que cambie:
[Descripcion]

## Archivo(s) modificado(s):
- [archivo 1]

## Mi prediccion:
"Si hago [cambio], espero que [consecuencia]."

## Resultado real:
[Que paso]

## Tests:
```bash
pytest --tb=short -q
# Resultado: [X passed]

Aprendizaje:

[Que aprendiste]


### `entregables/05-comparacion-tiempo.md` (esqueleto)

```markdown
# Comparacion de Tiempo

## Tiempo Real (con Claude Code)

| Actividad | Tiempo |
|-----------|--------|
| Setup | X min |
| Exploracion 5 preguntas | X min |
| Mental model (3 niveles) | X min |
| Onboarding doc | X min |
| Cambio validacion | X min |
| **TOTAL** | **X min** |

## Estimacion Manual (sin AI)

| Actividad | Estimacion |
|-----------|-----------|
| [Mismas actividades] | X hrs |
| **TOTAL** | **X hrs** |

## Factor: Xhrs / Yhrs = Zx

## Reflexion:
[3-5 frases]

`README.md` (esqueleto)

# Proyecto de Onboarding: [Nombre del Proyecto]

## Resumen

Onboarding al codebase open-source [nombre] usando Claude Code
y el metodo sistematico del Modulo 1 de la guia
"Refactoring & Legacy Code with Claude Code."

## Proyecto Elegido

- **Nombre:** [nombre]
- **URL:** [github URL]
- **Tamano:** ~[X] LOC (sin tests)
- **Por que lo elegi:** [1 frase]

## Tiempo Total

- Con Claude Code: [X] minutos
- Estimacion manual: [Y] horas
- Factor de aceleracion: [Z]x

## Como Navegar los Entregables

| Archivo | Contenido |
|---------|-----------|
| `entregables/01-exploracion-sistematica.md` | 5 preguntas respondidas con prompts y analisis |
| `entregables/02-mental-model.md` | Mental model en 3 niveles con diagramas |
| `entregables/03-onboarding-doc.md` | Onboarding doc de 6 secciones |
| `entregables/04-cambio-validacion.md` | Cambio al codebase con prediccion y verificacion |
| `entregables/05-comparacion-tiempo.md` | Comparacion de tiempo AI vs manual |

Ejemplo de Contenido Real (fragmento de exploracion)

Para que veas la diferencia entre un entregable minimo y uno bien hecho, aquí esta un ejemplo de como deberia verse la Pregunta 1 de la exploracion para el proyecto httpx:

## Pregunta 1: Cual es la estructura del proyecto?

### Prompt usado:

claude "Analiza la estructura de directorios de httpx/. Para cada directorio y archivo principal, explica que tipo de código contiene. Excluye pycache y .git."


### Respuesta de Claude Code:

httpx/ es el package principal con la siguiente estructura:

httpx/ ├── init.py # API publica: re-exporta Client, AsyncClient, get, post... ├── _api.py # Funciones de conveniencia (get(), post(), etc.) ├── _auth.py # Handlers de autenticación (Basic, Digest, custom) ├── _client.py # Client y AsyncClient (clases principales) ├── _compat.py # Compatibilidad entre Python versions ├── _config.py # Timeout, Limits, SSL configuration ├── _content.py # Encoding/decoding de request/response bodies ├── _decoders.py # Decompresion de respuestas (gzip, deflate, brotli) ├── _exceptions.py # Jerarquia de excepciones ├── _models.py # Request, Response, URL, Headers, Cookies ├── _multipart.py # Multipart form data encoding ├── _status_codes.py # HTTP status codes como constantes ├── _transports/ # Transporte HTTP (sync y async) │ ├── default.py # HTTPTransport, AsyncHTTPTransport │ ├── mock.py # MockTransport para testing │ └── wsgi.py # WSGITransport para testing de apps WSGI ├── _types.py # Type aliases └── _urls.py # URL parsing y construccion


### Mi analisis:

**Lo que esperaba:** Una estructura tipica de library Python con un archivo
principal y utilidades. Mas o menos acerte.

**Lo que me sorprendio:**
- Todos los archivos internos tienen prefijo `_` (single underscore).
  Esto indica que son "privados" — la API publica es SOLO lo que
  `__init__.py` re-exporta. Es una convencion muy limpia.
- Hay un archivo `_compat.py` dedicado a compatibilidad. Esto sugiere
  que soportar multiples versiones de Python es una prioridad.
- El directorio `_transports/` tiene un `mock.py`. No estoy seguro
  si es para tests internos o si es parte de la API publica para
  que los usuarios puedan mockear httpx en sus tests.

**Lo que no entendi todavia:**
- Cual es la diferencia entre `_api.py` y `_client.py`? Ambos parecen
  ser "la forma de hacer requests." Necesito investigar esto.

Este nivel de detalle — prompt exacto, respuesta completa, análisis con sorpresas y dudas — es lo que distingue un entregable de 10/10 puntos de uno de 5/10.

Este ejemplo:

✅ Muestra la estructura esperada de cada entregable
✅ Es funcional como punto de partida
✅ Muestra el nivel de detalle esperado en el análisis personal
❌ NO incluye contenido real para todas las secciones (eso es tu trabajo)
❌ NO es suficiente para obtener puntos — debes completar con análisis real

Errores Comunes

Error 1: Elegir un proyecto demasiado simple

Causa: Elegiste un proyecto de <2K lineas donde el onboarding toma 10 minutos con o sin AI. Solución: Elige un proyecto de 5K-10K lineas minimo. El punto es que la diferencia entre exploracion manual y con AI sea palpable. Con un proyecto trivial, el factor de aceleracion sera insignificante.

# Verificar tamano del proyecto
find . -name "*.py" -not -path "*/test*" -not -path "*/__pycache__/*" | \
  xargs wc -l | tail -1
# Deberia mostrar al menos 5,000 lineas

Error 2: Copiar la respuesta de Claude Code sin análisis

Causa: Pegaste la respuesta de Claude Code en el entregable y no agregaste nada propio. Solución: Para cada respuesta de Claude Code, agrega tu análisis: que te sorprendio, que esperabas, que no quedo claro, que verificaste. Tu valor esta en el análisis, no en el copy-paste.

# ❌ Incorrecto:
## Pregunta 1: Estructura
[Respuesta de Claude Code copiada directamente. Fin.]

# ✅ Correcto:
## Pregunta 1: Estructura
### Respuesta de Claude Code:
[Respuesta completa]

### Mi analisis:
Lo que me sorprendio: no esperaba que el proyecto tuviera
un directorio _compat/ dedicado a compatibility con Python
versions viejas. Esto sugiere que soportar multiples versions
es una prioridad alta del proyecto.

Lo que no entendi: el directorio _transports/ tiene un archivo
mock.py — no estoy seguro si es para tests o si es un transport
real. Necesito investigar esto en el Nivel 2.

Error 3: Mental model sin diagramas

Causa: Describiste la arquitectura solo con texto, sin ninguna representacion visual. Solución: Incluye al menos un diagrama. Puede ser ASCII (rápido) o Mermaid (profesional). Un diagrama comunica la estructura en 5 segundos; el texto requiere 5 minutos.

# Pedir a Claude Code que genere el diagrama
claude "Genera un diagrama Mermaid de la arquitectura de este
proyecto. graph TD mostrando los componentes principales y
sus dependencias."

Error 4: Cambio de validación trivial (solo fix un typo en un comentario)

Causa: Elegiste un cambio que no valida tu mental model porque no toca ninguna funcionalidad real. Solución: El cambio debe tocar un archivo que analizaste en tu mental model. Agregar un test, mejorar un docstring de una función critica, o agregar type hints son buenos candidatos. Fix de typo en un comentario random no demuestra comprension.

# Pedir a Claude Code un cambio significativo pero seguro
claude "Sugiere un cambio que pueda hacer para validar
mi comprension del modulo _client.py. El cambio debe:
1. Tocar un archivo que analice en mi mental model
2. No romper tests existentes
3. Ser util (no trivial)
Sugerencias: agregar un test, mejorar docstring de funcion
publica, agregar type hints."

Error 5: Onboarding doc sin gotchas reales

Causa: La sección de Gotchas tiene items genericos como "el proyecto es complejo" en lugar de gotchas especificas del codebase. Solución: Las gotchas deben ser especificas: nombres de archivos, lineas de código, comportamiento concreto. "El proyecto es complejo" no es una gotcha. "El archivo _config.py usa lazy loading para SSL contexts, lo que significa que errores de certificado no aparecen hasta el primer request" es una gotcha.

# Pedir gotchas especificas
claude "Busca gotchas ESPECIFICAS en este proyecto. Quiero:
- Nombres de archivos y funciones concretas
- Comportamiento que sorprende a un developer nuevo
- Side effects no obvios
- Configuracion implicita no documentada
NO quiero observaciones genericas como 'el proyecto es grande'."

Error 6: Comparacion de tiempo inventada

Causa: No trackeaste el tiempo real y pusiste numeros que "suenan bien." Solución: Trackea el tiempo desde el inicio. Usa un timer (tu telefono, un pomodoro). La estimacion manual si puede ser subjetiva, pero el tiempo con Claude Code debe ser real.

# Tip: usa el comando time de tu terminal
time claude "Analiza la estructura de este proyecto..."
# Muestra cuanto tardo el comando

Error 7: No seguir el orden de las 5 preguntas

Causa: Empezaste por detalles ("como funciona esta función?") antes de entender el big picture. Solución: El orden importa: estructura → entry points → data flow → patterns → tech debt. Cada pregunta construye sobre la anterior. Si saltas a tech debt sin entender la estructura, tus observaciones seran descontextualizadas.

Error 8: Usar un proyecto que ya conoces

Causa: Elegiste un proyecto que usas diariamente o al que ya contribuiste. Solución: El punto del ejercicio es practicar onboarding a algo desconocido. Si ya conoces el proyecto, no puedes evaluar honestamente el proceso. Elige algo nuevo.

Preguntas Frecuentes

Puedo usar un proyecto en otro lenguaje que no sea Python?

No para este módulo. La guia usa Python como lenguaje de referencia, y los ejemplos y prompts estan disenados para proyectos Python. En modulos posteriores podras aplicar las mismas tecnicas a otros lenguajes, pero para este proyecto necesitas un codebase Python para que la experiencia sea consistente con lo aprendido.

Que pasa si el proyecto que elegi tiene tests que fallan?

Documenta cuales fallan y por que (dependencia de servicios externos, versión de Python, etc.). Si mas del 20% de los tests fallan, considera elegir otro proyecto. Si son pocos tests con razones claras (ej: requieren Redis corriendo), excluye esos tests de tu baseline:

# Excluir tests que requieren servicios externos
pytest --ignore=tests/integration/ -q --tb=short

Puedo hacer el proyecto en equipo?

Si, pero cada persona debe producir sus propios entregables sobre un proyecto DIFERENTE. Pueden comparar resultados al final — eso es un ejercicio valioso. Pero si ambos hacen el mismo proyecto, no estan practicando onboarding a algo desconocido.

Cuanto detalle se espera en el onboarding doc?

Suficiente para que un developer que no conoce el proyecto pueda leer tu doc y entender la arquitectura, patterns, y gotchas en 15-20 minutos. No es una documentación exhaustiva de cada función — es una guia de orientacion. Piensa en lo que TU habrias querido leer antes de explorar el proyecto.

Que hago si Claude Code da información incorrecta?

Documentalo. Es parte del aprendizaje. En tu sección de análisis, marca: "Claude Code dijo X pero al verificar descubri que es Y." Esto demuestra pensamiento critico y es mas valioso que una respuesta perfecta.

Puedo usar herramientas además de Claude Code (ej: grep, tree, ctags)?

Si, pero el foco es Claude Code. Puedes usar herramientas complementarias para verificar, pero el 80%+ de tu exploracion debe ser con Claude Code. Si usas otra herramienta, documenta por que fue necesaria en ese caso.

Recursos para el Proyecto

httpx — GitHub Repository https://github.com/encode/httpx HTTP client para Python. Tamano ideal (~10K LOC), bien estructurado, buena cobertura de tests. Recomendado como primera opción.
typer — GitHub Repository https://github.com/tiangolo/typer CLI framework. Mas pequeno (~5K LOC), creado por el autor de FastAPI. Buena opción si prefieres un proyecto mas simple.
rich — GitHub Repository https://github.com/Textualize/rich Terminal rendering library. Mas grande (~15K LOC). Buena opción si quieres un desafio mayor con arquitectura mas compleja.
Claude Code Documentation https://docs.anthropic.com/en/docs/claude-code Referencia oficial para los comandos y capacidades de Claude Code que usaras durante el proyecto.
Mermaid Live Editor — https://mermaid.live/ Editor online para crear y previsualizar diagramas Mermaid. Útil para refinar los diagramas que genere Claude Code antes de incluirlos en tu documentación.
"Working Effectively with Legacy Code" — Michael Feathers Capitulo 16 especificamente. El concepto de "seams" (puntos donde puedes hacer cambios sin modificar la estructura) es relevante para tu cambio de validación.

Conexión con Siguiente Módulo

Lo que construiste en este proyecto establece la base para el Módulo 2: Agentic Research con Explore Subagent.

En este módulo, exploraste un codebase usando Claude Code directamente — escribiendo prompts manuales para cada pregunta, cada nivel del mental model, cada sección del onboarding doc. Funciona, pero requiere que tu sepas que preguntar y como formular cada prompt.

En el Módulo 2 vas a aprender a usar el Explore subagent — una herramienta dentro de Claude Code disenada especificamente para investigacion de codebases. Es read-only (no puede modificar nada), usa busqueda semantica (encuentra "donde se maneja autenticación" sin saber el nombre de la función), y esta optimizado para explorar proyectos grandes.

La transicion es:

Modulo 1: Exploracion manual con Claude Code
           (tu formulas cada prompt, tu decides el orden)
              │
              ▼
Modulo 2: Exploracion asistida con Explore subagent
           (la herramienta optimiza la busqueda por ti)
              │
              ▼
Modulo 3: Analisis arquitectural profundo
           (dependency maps, flow analysis, pattern identification)

Lo que hiciste manualmente aquí, el Explore subagent lo puede automatizar. Pero primero necesitabas entender el proceso manual para saber cuando la herramienta automatica esta haciendo un buen trabajo y cuando necesitas intervenir.

Tu onboarding doc y mental model de este proyecto te serviran como referencia cuando compares los resultados del Explore subagent en el Módulo 2 — podras ver si la herramienta descubre las mismas gotchas, los mismos hub files, y los mismos data flows que tu encontraste manualmente.

Timeline Sugerido

Para completar este proyecto en ~2 horas:

Bloque	Tiempo	Actividad
1	0:00 - 0:10	Setup: clonar proyecto, instalar deps, verificar tests
2	0:10 - 0:30	Exploracion sistematica: 5 preguntas con Claude Code
3	0:30 - 0:50	Mental model: Nivel 1 (10 min) + Nivel 2 (10 min)
4	0:50 - 1:10	Mental model: Nivel 3 selectivo (20 min)
5	1:10 - 1:40	Onboarding doc: generar 6 secciones con Claude Code
6	1:40 - 1:50	Cambio de validación: predecir, hacer, verificar
7	1:50 - 2:00	Comparacion de tiempo y revisión final

Tips de time management:

✅ No perfecciones cada sección en la primera pasada. Genera todo primero, refina después.
✅ Si una pregunta de exploracion toma mas de 5 minutos, sigue adelante y vuelve luego.
✅ El Nivel 3 del mental model es selectivo — no analices todas las funciones, solo las 3-5 criticas.
✅ La sección de Gotchas del onboarding doc puede crecer conforme descubres cosas. No la dejes para el final.
❌ No pases 45 minutos en el setup. Si las dependencias dan problemas, continua con el análisis del código fuente directamente.

Checklist Final

Antes de entregar, verifica:

Estructura: Los 5 entregables estan en entregables/ con los nombres correctos
01-exploracion: Las 5 preguntas tienen prompt, respuesta, Y análisis personal
02-mental-model: Los 3 niveles estan documentados con al menos 1 diagrama
03-onboarding-doc: Las 6 secciones estan completas, gotchas tiene 5+ items
04-cambio: El cambio es real, hay prediccion previa, tests pasan post-cambio
05-comparacion: Tiempos reales (no inventados), reflexion personal incluida
Tests: Los tests del proyecto pasan después de tu cambio
README: Hay un README.md con resumen y como navegar los entregables
Proyecto elegido: Es de 5K+ lineas y no lo conocias previamente

← AnteriorDocumentar Hallazgos con Claude Code Siguiente →Módulo 2: Agentic Research con Explore Subagent

Proyecto del Módulo: Onboarding a Codebase Open-Source

Proyecto del Módulo: Onboarding a Codebase Open-Source

Descripción del proyecto

Objetivo del Proyecto

Especificaciones Tecnicas

Stack Tecnologico

Proyecto Open-Source a Elegir

Setup Inicial

Estructura de Entregables

Funcionalidades Obligatorias

1. Exploracion Sistematica — Las 5 Preguntas

2. Mental Model Documentado — 3 Niveles

3. Onboarding Doc Profesional — 6 Secciones

4. Cambio de Validación

Aprendizaje:

Validaciones y Manejo de Errores

Validaciones Obligatorias

Manejo de Errores Comunes

Guia Paso a Paso Detallada

Fase 1: Setup y Verificacion (10 min)

Fase 2: Exploracion Sistematica (20 min)

Fase 3: Mental Model — Nivel 1 y 2 (20 min)

Fase 4: Mental Model — Nivel 3 (20 min)

Fase 5: Onboarding Doc (30 min)

Fase 6: Cambio de Validación (10 min)

Fase 7: Comparacion y Revisión (10 min)

Criterios de Exito

Rubrica de Evaluacion (100 puntos)

Funcionalidad (50 puntos)

Código (30 puntos)

Documentación (20 puntos)

Extra Credit (hasta +10 puntos)

Ejemplo de Implementación Minima

entregables/01-exploracion-sistematica.md (esqueleto)

entregables/02-mental-model.md (esqueleto)

entregables/03-onboarding-doc.md (esqueleto)

Aprendizaje:

README.md (esqueleto)

Ejemplo de Contenido Real (fragmento de exploracion)

Errores Comunes

Error 1: Elegir un proyecto demasiado simple

Error 2: Copiar la respuesta de Claude Code sin análisis

Error 3: Mental model sin diagramas

Error 4: Cambio de validación trivial (solo fix un typo en un comentario)

Error 5: Onboarding doc sin gotchas reales

Error 6: Comparacion de tiempo inventada

Error 7: No seguir el orden de las 5 preguntas

Error 8: Usar un proyecto que ya conoces

Preguntas Frecuentes

Puedo usar un proyecto en otro lenguaje que no sea Python?

Que pasa si el proyecto que elegi tiene tests que fallan?

Puedo hacer el proyecto en equipo?

Cuanto detalle se espera en el onboarding doc?

Que hago si Claude Code da información incorrecta?

Puedo usar herramientas además de Claude Code (ej: grep, tree, ctags)?

Recursos para el Proyecto

Conexión con Siguiente Módulo

Timeline Sugerido

Checklist Final

`entregables/01-exploracion-sistematica.md` (esqueleto)

`entregables/02-mental-model.md` (esqueleto)

`entregables/03-onboarding-doc.md` (esqueleto)

`README.md` (esqueleto)