Documentar Hallazgos con Claude Code

Descripción de la capsula

Exploraste el codebase. Construiste tu mental model. Sabes que el proyecto tiene 3 layers, que order_service.py es el hub central, y que hay una dependencia circular entre notification y order_service. Excelente. Ahora cierra la terminal, vete a dormir, y vuelve manana. Cuanto de eso recuerdas con precision? La respuesta honesta: menos del 50%.

El conocimiento que vive solo en tu cabeza es efimero. Se degrada con el tiempo, se distorsiona con nuevas experiencias, y es imposible de compartir. El resultado real del onboarding no es "ahora lo entiendo" — es un documento que captura tu comprension de forma precisa, organizada, y útil para otros. Un onboarding doc bien hecho es el artefacto mas valioso que puedes producir en tus primeras horas con un codebase nuevo: reduce el onboarding del siguiente developer de semanas a horas.

En esta capsula vas a aprender a usar Claude Code para generar cada sección de un onboarding doc profesional: structure overview, key patterns, gotchas, entry points, y data flows. No vas a escribir el documento desde cero — vas a guiar a Claude Code con prompts especificos para que genere borradores que tu editas, corriges, y completas. El resultado es un documento que podrías entregarle a un companero nuevo y que le ahorraria semanas de exploracion.

Por Que la Documentación Es EL Output del Onboarding

El problema de "ya lo entiendo"

Hay dos tipos de comprension:

Comprension efimera:
──────────────────────
"Ya lei el codigo, entiendo como funciona."
→ 24 horas despues: "Espera, como era la relacion entre orders y payments?"
→ 1 semana despues: "Necesito releer todo desde cero."
→ Valor para el equipo: CERO (solo tu "entendiste" y ya lo olvidaste)

Comprension documentada:
───────────────────────────
"Aqui esta el onboarding doc. Seccion 2 explica la arquitectura,
seccion 4 tiene los gotchas que descubri, seccion 5 muestra el data flow."
→ 24 horas despues: abres el doc y recuerdas al instante
→ 1 semana despues: el doc sigue ahi, actualizado
→ Valor para el equipo: ALTO (cualquiera puede leerlo)

El ROI de documentar

El calculo es claro: 2-3 horas documentando ahorra 10-20 semanas de productividad perdida al ano en un equipo que crece.

Que hace a un onboarding doc bueno

Un onboarding doc bueno tiene estas caracteristicas:

• ✅ Estructurado: secciones claras, navegable, se puede ir directo a lo que necesitas
• ✅ Preciso: refleja el código actual, no una versión idealizada
• ✅ Opinionado: incluye observaciones, gotchas, y "cosas que me sorprendieron"
• ✅ Accionable: un developer puede leerlo y empezar a contribuir
• ✅ Mantenible: fácil de actualizar cuando el código cambia
• ❌ No es exhaustivo: no documenta cada función. Documenta lo que importa.
• ❌ No es un tutorial: no explica Python o FastAPI. Asume que el lector sabe programar.

Estructura del Onboarding Doc

Un onboarding doc profesional tiene 6 secciones. Cada una responde una pregunta critica que un developer nuevo tiene al llegar al proyecto.

Sección 1: Project Overview

Pregunta que responde: "Que hace este proyecto y por que existe?"

## Project Overview

**Que es:** [1-2 frases describiendo el proyecto]
**Para quien:** [Usuarios/clientes del sistema]
**Stack:** [Lenguaje, framework, DB, servicios externos]
**Tamano:** [~X archivos, ~Y lineas de codigo, Z dependencias]
**Estado:** [Activo/mantenimiento/legacy. Ultimo commit: fecha]

Como generarlo con Claude Code:

claude "Genera un Project Overview de este proyecto en formato markdown.
Incluye: que hace, para quien es, stack tecnologico, tamano
aproximado (archivos y lineas de codigo), y estado del proyecto
(mira el historial de git para determinar actividad reciente)."

Output esperado:

## Project Overview

**Que es:** API REST para gestion de pedidos de e-commerce.
Maneja usuarios, productos, ordenes, pagos (via Stripe),
y notificaciones (via SendGrid).

**Para quien:** Frontend web y app mobile del e-commerce.
Consumido por ~3 clientes: web app (React), mobile app (React Native),
y admin dashboard (interno).

**Stack:** Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL 15,
Redis (cache), Stripe API, SendGrid.

**Tamano:** 47 archivos Python, ~8,200 lineas de codigo,
23 dependencias directas.

**Estado:** Activo. Ultimo commit: hace 3 dias.
~15 commits/semana. 4 contributors activos.

Sección 2: Architecture Overview

Pregunta que responde: "Como esta organizado el código?"

Esta sección toma tu mental model Nivel 1 y lo convierte en documentación permanente.

claude "Genera una seccion 'Architecture Overview' para un onboarding doc.
Incluye:
1. Diagrama de layers (ASCII o Mermaid)
2. Que directorio corresponde a cada layer
3. La regla de dependencia entre layers
4. Entry points del sistema
5. Dependencias externas y para que se usa cada una"

Output esperado:

## Architecture Overview

### Layers

El proyecto sigue una arquitectura de 3 layers con regla
estricta de dependencia: Layer N solo llama a Layer N+1.

Presentacion (api/) → Recibe HTTP requests, valida input │ ▼ Negocio (services/) → Business logic, orquestacion │ ▼ Datos (repositories/) → DB queries, modelos, persistencia

### Estructura de Directorios

proyecto/ ├── api/ │ ├── v1/routes/ # Endpoints por dominio │ ├── middleware/ # Auth, CORS, logging │ └── dependencies/ # Dependency injection ├── services/ # Business logic ├── repositories/ # DB access ├── models/ # SQLAlchemy models ├── core/ # Config, security, utils ├── tests/ # Tests por módulo └── main.py # Entry point (FastAPI app)

### Entry Points

- `main.py` — HTTP server (FastAPI, uvicorn)
- `cli/manage.py` — Comandos admin (seed DB, migrations)
- `worker.py` — Background jobs (Celery)

### Dependencias Externas

| Dependencia | Para que |
|-------------|----------|
| PostgreSQL | Base de datos principal |
| Redis | Cache de sessions y rate limiting |
| Stripe | Procesamiento de pagos |
| SendGrid | Envio de emails transaccionales |
| Celery | Background jobs asincrónos |

Sección 3: Key Patterns

Pregunta que responde: "Que convenciones y patterns debo seguir?"

claude "Analiza este proyecto e identifica los patterns y convenciones
que se usan consistentemente. Documenta:
1. Patterns arquitecturales (repository pattern, service layer, etc.)
2. Convenciones de naming (archivos, clases, funciones, variables)
3. Patterns de error handling
4. Patterns de testing
5. Cualquier pattern custom o inusual"

Output esperado:

## Key Patterns

### Repository Pattern
Cada modelo tiene su repository en `repositories/`.
Los repositories NUNCA se llaman directamente desde routes —
siempre a traves de un service.

```python
# CORRECTO
# routes/orders.py
order = order_service.create_order(user_id, items)

# INCORRECTO (viola el patron)
# routes/orders.py
order = order_repo.create(user_id=user_id, items=items)

Service Layer Pattern

Business logic vive en services/. Un service puede llamar a otros services y a repositories, pero nunca a routes.

Error Handling

Todos los errores de negocio heredan de core/exceptions.py:AppError. Los routes los capturan con un exception handler global en main.py.

# Pattern de error
class OrderNotFoundError(AppError):
    status_code = 404
    message = "Order not found"

Naming Conventions

• Archivos: snake_case (order_service.py)
• Clases: PascalCase (OrderService)
• Funciones: snake_case (create_order)
• Constantes: UPPER_SNAKE (MAX_RETRY_COUNT)
• Tests: test_ prefix (test_create_order_success)

Testing Pattern

• Un archivo de test por modulo: tests/test_order_service.py
• Fixtures en tests/conftest.py
• Mocks para APIs externas (Stripe, SendGrid)
• Factories para crear test data (tests/factories/)

### Sección 4: Gotchas y Trampas

**Pregunta que responde:** "Que me va a sorprender o morder si no lo se?"

Esta es la sección mas valiosa del onboarding doc. Ningun README la tiene. Solo la puede escribir alguien que exploro el codebase.

```bash
claude "Identifica las 'gotchas' de este proyecto — cosas que
sorprenderian a un developer nuevo o que podrian causar bugs
si no se conocen. Busca:
1. Dependencias circulares
2. Side effects no obvios
3. Configuracion no documentada
4. Codigo que parece una cosa pero hace otra
5. TODOs o FIXMEs criticos
6. Inconsistencias en el estilo o patterns"

Output esperado:

## Gotchas

### ⚠️ Dependencia circular notification ↔ order_service
`notification.py` importa `order_service` para obtener datos
del pedido al enviar emails. Esto crea un import circular que
se resuelve con import lazy dentro de la funcion. Si mueves
imports al top-level, se rompe.

### ⚠️ create_order() no tiene transaccion atomica
Si el pago en Stripe se cobra pero la creacion de la orden en DB
falla, el usuario queda cobrado sin orden. Hay un TODO en linea 147
pero no se ha resuelto.

### ⚠️ Redis es obligatorio (no optional)
Aunque parece cache, el rate limiter depende de Redis.
Si Redis no esta corriendo, TODOS los requests fallan con 500.
No hay fallback.

### ⚠️ Los tests usan SQLite, produccion usa PostgreSQL
Hay queries con funciones PostgreSQL-specific (jsonb_extract_path)
que no se testean realmente. Los tests pasan pero el codigo
podria fallar en produccion.

### ⚠️ Variables de entorno no documentadas
Se necesitan 12 env vars para correr el proyecto.
Solo 5 estan en el README. Las otras 7 estan esparcidas
en core/config.py y hay que leerlo para descubrirlas.

Sección 5: Data Flows

Pregunta que responde: "Como fluyen los datos a traves del sistema?"

claude "Documenta los 3 data flows principales de este proyecto.
Para cada uno:
1. Trigger (que lo inicia)
2. Paso a paso (que modulos toca, en orden)
3. Side effects (DB writes, API calls, emails)
4. Resultado final
Usa formato de texto con flechas, no diagramas."

Output esperado:

## Data Flows

### Flow 1: Crear una Orden

POST /api/v1/orders {user_id, items} → routes/orders.py: valida input (Pydantic) → services/order_service.py: create_order() → repositories/user_repo.py: verificar usuario existe → repositories/product_repo.py: verificar stock (por cada item) → Calcula total + tax → services/payment_service.py: charge() → core/stripe_client.py: Stripe API call → repositories/payment_repo.py: guardar transaccion → repositories/order_repo.py: crear orden en DB → repositories/product_repo.py: decrementar stock → services/notification.py: enviar email confirmacion → SendGrid API call (async, no bloquea) ← Response: {order_id, status: "confirmed", total}

Side effects: DB write (3 tablas), Stripe charge, email

### Flow 2: Autenticacion

POST /api/v1/auth/login {email, password} → routes/auth.py: valida input → services/auth_service.py: authenticate() → repositories/user_repo.py: buscar por email → core/security.py: verify_password(hash, plain) → core/security.py: create_jwt_token(user_id) ← Response: {access_token, token_type: "bearer"}

Side effects: ninguno (read-only + token generation)

### Flow 3: Webhook de Stripe

POST /api/v1/payments/webhook {stripe_event} → middleware/stripe_webhook.py: verificar signature → routes/payments.py: handle_webhook() → services/payment_service.py: process_webhook() → Si event == "charge.refunded": → repositories/order_repo.py: update status a "refunded" → services/notification.py: enviar email de refund ← Response: 200 OK (Stripe requiere respuesta rapida)

Side effects: DB write (si refund), email (si refund)

Sección 6: Entry Points y Como Empezar

Pregunta que responde: "Por donde empiezo si quiero hacer un cambio?"

claude "Genera una seccion 'Como empezar a contribuir' para un onboarding doc.
Incluye:
1. Como correr el proyecto localmente (paso a paso)
2. Como correr los tests
3. Por donde empezar si quieres agregar un nuevo endpoint
4. Por donde empezar si quieres fix un bug
5. Archivos que debes leer primero (top 5)"

Output esperado:

## Como Empezar

### Setup Local
```bash
git clone <repo-url>
cd proyecto
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Editar con tus credenciales
docker-compose up -d  # PostgreSQL + Redis
alembic upgrade head  # Migrations
python cli/manage.py seed  # Data de prueba
uvicorn main:app --reload

Correr Tests

pytest                    # Todos los tests
pytest tests/test_orders.py  # Un módulo
pytest -x                 # Parar en primer fallo
pytest --cov              # Con coverage

Agregar un Nuevo Endpoint

1. Crear route en api/v1/routes/<dominio>.py
2. Crear (o extender) service en services/<dominio>_service.py
3. Crear (o extender) repository en repositories/<dominio>_repo.py
4. Agregar modelo si es nuevo en models/<dominio>.py
5. Crear migration: alembic revision --autogenerate -m "add X"
6. Agregar tests en tests/test_<dominio>_service.py

Archivos que Debes Leer Primero

1. main.py — Entiende como arranca el server
2. api/v1/routes/orders.py — Ejemplo de route completo
3. services/order_service.py — Ejemplo de service completo
4. core/config.py — Toda la configuracion del proyecto
5. tests/conftest.py — Fixtures y setup de tests

---

## Generar el Onboarding Doc Completo con Claude Code

### Estrategia: sección por sección, no todo de una vez

El error mas comun es pedirle a Claude Code "genera un onboarding doc de todo el proyecto" en un solo prompt. El resultado sera superficial e impreciso. La estrategia correcta es generar sección por sección, validar cada una, y luego ensamblar.

```bash
# Paso 1: Project Overview (5 min)
claude "Genera la seccion Project Overview de un onboarding doc
para este proyecto. Formato markdown. Incluye: que hace, stack,
tamano, estado, para quien es."

# Paso 2: Architecture Overview (10 min)
claude "Genera la seccion Architecture Overview. Incluye: diagrama
de layers, estructura de directorios, entry points, dependencias
externas."

# Paso 3: Key Patterns (10 min)
claude "Genera la seccion Key Patterns. Analiza el codigo e identifica:
patterns arquitecturales, naming conventions, error handling patterns,
testing patterns."

# Paso 4: Gotchas (15 min — la seccion mas valiosa)
claude "Identifica gotchas del proyecto. Busca: dependencias circulares,
side effects no obvios, configuracion no documentada, inconsistencias,
TODOs criticos, codigo confuso."

# Paso 5: Data Flows (10 min)
claude "Documenta los 3 data flows principales. Para cada uno: trigger,
paso a paso con modulos, side effects, resultado final."

# Paso 6: Como Empezar (5 min)
claude "Genera la seccion 'Como Empezar': setup local, correr tests,
como agregar un endpoint, archivos que leer primero."

# Paso 7: Ensamblar
claude "Tengo estas 6 secciones de un onboarding doc. Ensamblalas
en un solo documento markdown coherente. Agrega una tabla de
contenido al inicio y revisa que no haya inconsistencias entre
secciones."

Tiempo total: ~55-60 minutos para un onboarding doc profesional de un codebase de 5K-10K lineas.

Revisar y refinar

Después de que Claude Code genera cada sección, tu trabajo es:

1. Verificar precision: El layer diagram refleja la realidad?
2. Agregar opinion: Claude Code es neutral. Tu agrega "esto me parece riesgoso" o "esto es confuso".
3. Agregar contexto: Claude Code no sabe por que se tomaron ciertas decisiones. Si lo averiguaste (git blame, preguntar al equipo), agregalo.
4. Eliminar ruido: Si una sección tiene información obvia o irrelevante, eliminala.

# Refinar una seccion especifica
claude "La seccion de Gotchas que generaste menciona 'los tests usan
SQLite pero produccion usa PostgreSQL'. Agrega un ejemplo concreto:
cual query especifica podria fallar por esta diferencia?"

Ejemplo Completo: Onboarding Doc

Para que veas como se ve el producto final, aquí esta un onboarding doc completo de un proyecto de ejemplo:

# Onboarding Doc: E-Commerce API

**Generado:** 2026-04-01
**Autor:** [Tu nombre] (con asistencia de Claude Code)
**Proyecto:** E-Commerce REST API
**Tiempo de onboarding:** 1.5 horas

---

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

---

## 1. Project Overview

API REST para gestion de e-commerce. Maneja usuarios,
productos, ordenes, pagos (Stripe), y notificaciones (SendGrid).

- **Stack:** Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL, Redis
- **Tamano:** 47 archivos, ~8,200 LOC, 23 dependencias
- **Estado:** Activo (~15 commits/semana, 4 contributors)
- **Consumidores:** Web app (React), Mobile (React Native), Admin dashboard

## 2. Architecture Overview

3 layers con dependencia unidireccional:

api/ (Presentacion) → services/ (Negocio) → repositories/ (Datos)

Entry points: main.py (HTTP), cli/manage.py (admin), worker.py (jobs)

## 3. Key Patterns

- Repository pattern para DB access
- Service layer para business logic
- Exception hierarchy desde core/exceptions.py:AppError
- Factories para test data
- Pydantic models para input validation en routes

## 4. Gotchas

⚠️ create_order() no es atomica (Stripe charge + DB write no transaccional)
⚠️ Redis es OBLIGATORIO (rate limiter lo requiere, no hay fallback)
⚠️ Tests con SQLite ≠ Produccion con PostgreSQL (jsonb queries no testeadas)
⚠️ Import circular notification ↔ order_service (lazy import hack)
⚠️ 7 de 12 env vars no estan documentadas en README

## 5. Data Flows

Flow principal (crear orden):
POST /orders → validate → check stock → charge Stripe
→ create in DB → decrease stock → send email → 201 Created

## 6. Como Empezar

1. Clone + venv + pip install
2. docker-compose up (PostgreSQL + Redis)
3. alembic upgrade head + seed
4. uvicorn main:app --reload
5. Leer: main.py → routes/orders.py → services/order_service.py

Este es un ejemplo condensado. Tu versión completa tendra 3-5 paginas con mas detalle en cada sección.

Hacer la Documentación Útil Para Otros

Principio: escribe para el developer que llega manana

No escribes para ti. Escribes para alguien que:

• ✅ Sabe programar en Python
• ✅ Conoce FastAPI (o puede aprenderlo rápido)
• ❌ No ha visto este codebase jamas
• ❌ No sabe por que se tomaron ciertas decisiones
• ❌ No sabe donde estan las trampas

Tips practicos

1. Usa lenguaje directo, no corporativo:

❌ "El sistema utiliza una arquitectura basada en el patron
    de repositorio para abstraer la capa de persistencia."

✅ "Los DB queries estan en repositories/. Nunca hagas queries
    directamente desde un route — siempre pasa por un service
    que llama al repository."

2. Incluye los "por que", no solo los "que":

❌ "Redis es una dependencia del proyecto."

✅ "Redis es OBLIGATORIO — el rate limiter lo usa y no hay fallback.
    Si Redis no esta corriendo, todos los requests retornan 500."

3. Pon ejemplos de código cuando sean utiles:

❌ "Los errores se manejan con excepciones custom."

✅ "Los errores heredan de AppError:
    class OrderNotFoundError(AppError):
        status_code = 404
        message = 'Order not found'
    El handler global en main.py los atrapa automaticamente."

4. Mantenlo actualizado:

# Cada vez que hagas un cambio significativo al codebase,
# pide a Claude Code que actualice el onboarding doc:
claude "Acabo de agregar un nuevo service (services/shipping_service.py)
que maneja calculo de envio. Actualiza la seccion Architecture
Overview del onboarding doc para incluir este nuevo modulo."

Comparacion: Documentación con Claude Code vs Manual

Cuando la documentación manual es mejor:

• ✅ Cuando necesitas capturar contexto humano: "lo hicimos así porque el CEO pidio este feature en 2 dias"
• ✅ Cuando necesitas opinion subjetiva: "esta parte del código es un desastre y deberia refactorizarse"
• ✅ Cuando el codebase es tan legacy que Claude Code no puede parsearlo bien

Cuando Claude Code es mejor:

• ✅ Para el 80% del onboarding doc (estructura, patterns, data flows)
• ✅ Para mantener el doc actualizado conforme el código cambia
• ✅ Para descubrir gotchas que un humano podria pasar por alto
• ✅ Para ser exhaustivo sin ser tedioso

Trade-off: La mejor documentación combina ambos: Claude Code genera el 80% (estructura, precision, cobertura) y tu agregas el 20% (contexto, opinion, priorizacion).

Conexión con Proyecto

En el Proyecto del Módulo: Onboarding a Codebase Open-Source (proyecto de este módulo):

• Produciras un onboarding doc completo como uno de los entregables principales
• Usaras la estructura de 6 secciones para organizar tus hallazgos del proyecto open-source
• La sección de Gotchas sera especialmente relevante porque proyectos open-source tienen trampas no documentadas
• La tecnica de generar sección por sección con Claude Code es exactamente como produciras tu entregable
• El onboarding doc es la evidencia tangible de que entendiste el codebase — no basta con "lo explore"

Todo lo que aprendes aquí se convierte en tu entregable principal del proyecto.

Troubleshooting

Problema 1: Claude Code genera documentación demasiado generica

Causa: El prompt no especifica el nivel de detalle esperado ni incluye ejemplos. Solución: Agrega contexto al prompt y pide especificidad:

# En vez de:
claude "Documenta la arquitectura de este proyecto."

# Usa:
claude "Documenta la arquitectura de este proyecto para un onboarding doc.
Nivel de detalle: un developer senior que sabe Python y FastAPI
pero nunca ha visto este codebase. Incluye:
- Diagrama de layers con nombres de directorios reales
- Regla de dependencia entre layers
- Los 3 entry points con que hace cada uno
No incluyas explicaciones de que es FastAPI o SQLAlchemy."

Problema 2: Las secciones del doc se contradicen entre si

Causa: Generaste cada sección en un prompt separado y Claude Code no tuvo contexto cruzado. Solución: Después de generar todas las secciones, haz un paso de integración:

claude "Revisa este onboarding doc completo y identifica
inconsistencias entre secciones. Por ejemplo: la seccion
de Architecture dice X pero la seccion de Data Flow implica Y.
Lista todas las inconsistencias que encuentres."

Problema 3: La sección de Gotchas esta vacia o es trivial

Causa: Claude Code no sabe que buscar si no le das criterios especificos. Solución: Pide categorias especificas de gotchas:

claude "Busca gotchas en estas categorias especificas:
1. Dependencias circulares (analiza todos los imports)
2. Side effects ocultos (funciones que hacen mas de lo que sugiere su nombre)
3. Configuracion hardcodeada o no documentada
4. Discrepancias entre tests y produccion
5. Codigo muerto o features a medio implementar
6. Excepciones que se tragan silenciosamente (except: pass)"

Problema 4: El doc es demasiado largo y nadie lo va a leer

Causa: Incluiste demasiado detalle en cada sección. Solución: Crea dos versiones — una TL;DR y una completa:

claude "A partir de este onboarding doc completo, genera una
version TL;DR de maximo 1 pagina. Incluye solo: stack,
diagrama de layers (3 lineas), top 5 gotchas, y los 3 comandos
para correr el proyecto. Pon un link al doc completo."

Problema 5: No sabes que tan actualizado esta el doc después de 2 semanas

Causa: El codebase cambio pero el doc no. Solución: Crea un checklist de validación:

claude "Compara este onboarding doc con el estado actual del codigo.
Identifica secciones que estan desactualizadas:
- Archivos nuevos que el doc no menciona?
- Dependencias que cambiaron?
- Patterns que ya no se usan?
- Entry points nuevos?"

Ejercicios

Ejercicio 1: Project Overview de httpx (Fácil)

Clona httpx y genera la sección "Project Overview" del onboarding doc usando Claude Code. Incluye: que hace, stack, tamano, estado, consumidores.

git clone https://github.com/encode/httpx.git
cd httpx

claude "Genera la seccion Project Overview de un onboarding doc
para este proyecto. Incluye: que hace, stack tecnologico,
tamano aproximado (archivos y lineas), estado (actividad en git),
y quien lo usa (consumidores)."

## Project Overview

**Que es:** Library HTTP para Python, compatible con sync y async.
Reemplazo moderno de `requests` con soporte nativo para HTTP/2,
async/await, y type hints.

**Stack:** Python 3.8+, httpcore (transporte), certifi (SSL),
idna (internacionalizacion de dominios), sniffio (async detection).

**Tamano:** ~40 archivos core, ~15,000 lineas de codigo,
~200 archivos de tests, 5 dependencias directas.

**Estado:** Activo y maduro. ~500 contributors, 12K+ stars.
Releases regulares. Ultima release: [fecha reciente].

**Consumidores:** Developers Python que necesitan un HTTP client.
Usado como dependencia por FastAPI (para TestClient), Starlette,
y cientos de proyectos open source.

Ejercicio 2: Sección de Gotchas de httpx (Fácil)

Usando el mismo proyecto httpx, genera la sección "Gotchas" del onboarding doc. Pide a Claude Code que busque especificamente: dependencias no obvias, comportamiento sorprendente, y configuración implicita.

claude "Analiza httpx y genera la seccion 'Gotchas' para un onboarding doc.
Busca:
1. Comportamiento que no es obvio leyendo la documentacion
2. Diferencias entre sync Client y async AsyncClient
3. Configuracion por defecto que podria sorprender
4. Edge cases en el manejo de redirects, timeouts, o encoding
5. Cosas que cambiaron entre versiones recientes"

## Gotchas

⚠️ Client y AsyncClient NO comparten implementacion.
No es que AsyncClient sea un wrapper de Client.
Son implementaciones separadas que usan transports diferentes.

⚠️ Los redirects estan limitados a 20 por defecto.
Si tu API tiene mas de 20 redirects encadenados, falla
silenciosamente con TooManyRedirects.

⚠️ Timeout por defecto es 5 segundos.
Diferente de requests (que no tiene timeout por defecto).
Si no especificas timeout, requests con APIs lentas fallan.

⚠️ El Client debe cerrarse explicitamente.
Si no usas `with Client() as client:`, las conexiones
quedan abiertas. Hay un __del__ pero no es garantizado.

⚠️ HTTP/2 no esta habilitado por defecto.
Necesitas `Client(http2=True)` y la dependencia h2 instalada.

Ejercicio 3: Data Flow de una Request HTTP (Medio)

Genera la sección "Data Flows" del onboarding doc de httpx. Documenta el flujo completo de un client.get("https://example.com") desde la llamada del usuario hasta la respuesta.

claude "Documenta el data flow de una request HTTP en httpx.
Traza client.get('https://example.com') paso a paso:
1. Que metodo/funcion se ejecuta primero
2. Como se construye el Request object
3. Como se procesa la autenticacion (si hay)
4. Como se envia via el transport
5. Como se construye el Response object
6. Que retorna al usuario
Incluye los archivos y funciones especificos por los que pasa."

## Data Flow: client.get(url)

Side effects: conexion TCP (se mantiene en pool),
SSL handshake (primera vez), DNS lookup.

Ejercicio 4: Onboarding Doc Sección por Sección (Medio)

Elige un proyecto Python que no conozcas (sugerencias: rich, typer, pydantic). Genera las 6 secciones del onboarding doc usando la tecnica de "sección por sección" descrita en esta capsula. Ensambla el documento final. Mide cuanto tiempo te tomo.

# Ejemplo con rich
git clone https://github.com/Textualize/rich.git
cd rich

# Seccion 1: Project Overview (5 min)
claude "Genera la seccion Project Overview del onboarding doc."

# Seccion 2: Architecture Overview (10 min)
claude "Genera la seccion Architecture Overview con diagrama
de layers y estructura de directorios."

# Seccion 3: Key Patterns (10 min)
claude "Genera la seccion Key Patterns: patterns arquitecturales,
naming conventions, error handling."

# Seccion 4: Gotchas (15 min)
claude "Genera la seccion Gotchas: busca dependencias no obvias,
comportamiento sorprendente, edge cases."

# Seccion 5: Data Flows (10 min)
claude "Genera la seccion Data Flows: documenta el flujo de
console.print('Hello, World!') paso a paso."

# Seccion 6: Como Empezar (5 min)
claude "Genera la seccion Como Empezar: setup, tests, como agregar
un nuevo renderizable."

# Ensamblar (5 min)
claude "Ensambla estas 6 secciones en un onboarding doc markdown
coherente. Agrega tabla de contenido y revisa inconsistencias."

Ejercicio 5: Mejorar un Onboarding Doc Existente (Difícil)

Toma el onboarding doc que generaste en el Ejercicio 4. Ahora mejoralo:

1. Agrega 3 opiniones personales (cosas que te parecieron bien o mal del codebase)
2. Agrega 2 gotchas que Claude Code no encontro pero tu si (leyendo el código)
3. Crea una versión TL;DR de 1 página
4. Valida que el doc siga siendo preciso comparando con el código actual

# Paso 1: Agregar opiniones personales
# Esto NO lo haces con Claude Code — lo escribes tu:

# Ejemplo de opiniones:
# "El sistema de renderizado de rich es elegante: cada objeto
#  implementa __rich_console__() y el console los renderiza
#  polimorficamente. Sin embargo, la cantidad de clases es
#  abrumadora — hay 40+ renderizables y no esta claro cual
#  usar en cada caso."

# Paso 2: Gotchas que tu encontraste
# Lee el codigo manualmente y busca cosas que Claude Code no menciono.
# Ejemplo: "El modulo _inspect.py usa eval() en algunos casos
#  para renderizar objetos. Esto podria ser un riesgo de seguridad
#  si se usa con input no confiable."

# Paso 3: Version TL;DR
claude "A partir de este onboarding doc completo de rich,
genera una version TL;DR de maximo 30 lineas. Incluye:
stack, arquitectura en 1 parrafo, top 3 gotchas, y como
correr el proyecto en 3 comandos."

# Paso 4: Validar precision
claude "Compara este onboarding doc con el codigo actual de rich/.
Hay secciones desactualizadas? Archivos que el doc no menciona?
Patterns que cambiaron?"

Ejercicio 6: Onboarding Doc como Herramienta de Team (Difícil)

Imagina que tu onboarding doc sera leido por 5 developers nuevos en los proximos 6 meses. Toma tu doc del Ejercicio 4 y:

1. Agrega una sección "Preguntas Frecuentes" con las 5 preguntas que un developer nuevo haria
2. Agrega una sección "Changelog del Doc" para trackear actualizaciones
3. Crea un script que verifica automáticamente si el doc esta desactualizado

# Paso 1: Preguntas Frecuentes
claude "Basandote en este onboarding doc, genera una seccion
'Preguntas Frecuentes' con las 5 preguntas que un developer
nuevo probablemente preguntaria. Incluye respuestas concisas."

# Paso 2: Changelog
# Agrega manualmente al final del doc:
# ## Changelog
# | Fecha | Autor | Cambio |
# |-------|-------|--------|
# | 2026-04-05 | [Tu nombre] | Creacion inicial |

# Paso 3: Script de validacion
claude "Escribe un script Python que:
1. Lee el onboarding doc (ONBOARDING.md)
2. Extrae los nombres de archivos mencionados
3. Verifica que esos archivos existen en el proyecto
4. Reporta archivos mencionados que no existen (doc desactualizado)
5. Reporta archivos nuevos en src/ que el doc no menciona (gaps)
Debe ser ejecutable con: python validate_onboarding.py"

#!/usr/bin/env python3
"""Valida que el onboarding doc refleje el estado actual del proyecto."""

import re
from pathlib import Path


def extract_mentioned_files(doc_path: str) -> set[str]:
    """Extrae nombres de archivos mencionados en el doc."""
    content = Path(doc_path).read_text()
    # Busca patrones como archivo.py, dir/archivo.py
    pattern = r'[\w/]+\.py'
    return set(re.findall(pattern, content))


def get_project_files(project_dir: str) -> set[str]:
    """Lista archivos Python del proyecto."""
    project_path = Path(project_dir)
    return {
        str(f.relative_to(project_path))
        for f in project_path.rglob("*.py")
        if "test" not in str(f) and "__pycache__" not in str(f)
    }


def validate(doc_path: str, project_dir: str) -> None:
    """Compara doc con proyecto y reporta discrepancias."""
    mentioned = extract_mentioned_files(doc_path)
    actual = get_project_files(project_dir)

    # Archivos mencionados que no existen
    missing = mentioned - actual
    if missing:
        print("⚠️ Archivos en doc que NO existen en proyecto:")
        for f in sorted(missing):
            print(f"  - {f}")

    # Archivos nuevos no mencionados
    new_files = actual - mentioned
    if new_files:
        print("\n📝 Archivos en proyecto NO mencionados en doc:")
        for f in sorted(new_files):
            print(f"  - {f}")

    if not missing and not new_files:
        print("✅ Onboarding doc esta actualizado.")


if __name__ == "__main__":
    validate("ONBOARDING.md", "src/")

Resumen

En esta capsula aprendiste:

• La documentación es EL output del onboarding, no un extra. "Ya lo entiendo" es efimero; un doc es permanente y compartible.
• Un onboarding doc profesional tiene 6 secciones: Project Overview, Architecture, Key Patterns, Gotchas, Data Flows, Como Empezar.
• La sección de Gotchas es la mas valiosa y la que ningun README contiene. Solo la puede escribir alguien que exploro el codebase.
• La estrategia correcta es generar sección por sección con Claude Code, no pedir todo en un prompt. Esto da mas control y precision.
• El mejor onboarding doc combina 80% generado por Claude Code (estructura, precision) con 20% humano (opinion, contexto, priorizacion).
• La documentación debe ser mantenida. Un doc desactualizado es peor que ningun doc porque genera falsa confianza.
• Escribes para el developer que llega manana: lenguaje directo, ejemplos concretos, opiniones utiles.

Proxima capsula: Proyecto del Módulo — donde aplicas todo (exploracion, mental model, documentación) a un codebase open-source real.

Recursos Adicionales

1. "Docs for Developers" — Jared Bhatti et al. Guia practica sobre como escribir documentación tecnica efectiva. Los capitulos sobre "writing for your audience" y "documentation types" complementan directamente esta capsula.

2. "Living Documentation" — Cyrille Martraire El concepto de documentación que se genera y valida automáticamente desde el código. Inspiracion para el script de validación del Ejercicio 6.

3. Diátaxis Framework — https://diataxis.fr/ Framework para organizar documentación tecnica en 4 tipos: tutorials, how-to guides, reference, explanation. El onboarding doc es un hibrido de reference y explanation.

4. "The Documentation System" — Divio — https://documentation.divio.com/ Versión simplificada de Diataxis con ejemplos concretos. Útil para entender que tipo de documentación es un onboarding doc (y que tipo NO es).

5. Claude Code Documentation — https://docs.anthropic.com/en/docs/claude-code Referencia oficial de Claude Code. La sección sobre context management es relevante para generar documentación de proyectos grandes.

6. "A Practical Guide to Writing Technical Specs" — Stack Overflow Blog Aunque es sobre specs, no onboarding docs, las tecnicas de escritura clara y estructurada aplican directamente.