Exploracion Sistematica — Que Preguntar y en Que Orden

Descripción de la capsula

En la capsula anterior viste los numeros: el onboarding manual cuesta $15K-$30K por developer y toma semanas. Viste como Claude Code puede responder preguntas sobre un codebase en segundos. Pero hay un problema: si haces preguntas al azar, obtienes respuestas al azar. Entiendes fragmentos pero no el sistema. Es como leer una enciclopedia abriendo paginas al azar — aprendes datos sueltos pero no construyes comprension.

Esta capsula te da el método que transforma esas preguntas sueltas en un framework sistematico. Las 5 preguntas iniciales — estructura, entry points, data flow, patterns, tech debt — no son una lista arbitraria. Estan ordenadas de lo mas general a lo mas específico, y cada respuesta te da el contexto que necesitas para la siguiente pregunta. Es la diferencia entre explorar un edificio empezando por el plano de planta vs empezando por el bano del tercer piso.

Al final de esta capsula tendras un framework de exploracion completo que puedes aplicar a cualquier codebase. Sabras exactamente que preguntar, en que orden, y por que ese orden importa. Y tendras los prompts de Claude Code listos para copiar y usar desde manana.

Por Que el Orden Importa

La trampa de la exploracion random

Cuando un developer entra a un codebase nuevo sin método, la exploracion tipica se ve así:

1. Abre el archivo que suena mas interesante (payment_service.py)
2. Ve imports de 5 modulos -> abre uno al azar (stripe_client.py)
3. Ve una clase compleja -> se pierde en los detalles
4. Recuerda que queria entender pagos -> vuelve a payment_service.py
5. Ve un decorador desconocido -> busca su definicion
6. 30 minutos despues: entiende el decorador pero perdio el hilo
7. Abre otro archivo interesante (auth_middleware.py)
8. Repite el ciclo

Después de 2 horas, tienes conocimiento fragmentado: sabes que Stripe se usa para pagos, que hay JWT para auth, y que un decorador cachea resultados. Pero no puedes responder preguntas basicas: "como esta organizado el proyecto?" o "como fluyen los datos?"

La exploracion sistematica

Con método, la exploracion se ve así:

1. Estructura: que carpetas hay, como esta organizado     (2 min)
2. Entry points: donde empieza la ejecucion, como entran requests (3 min)
3. Data flow: como viajan los datos de entrada a salida    (5 min)
4. Patterns: que convenciones y disenos se repiten         (5 min)
5. Tech debt: donde estan los problemas y riesgos          (5 min)

En 20 minutos tienes un mental model coherente. No fragmentos — un mapa. Puedes explicar el proyecto a otro developer. Puedes identificar donde profundizar.

La analogia del GPS

Imagina que llegas a una ciudad nueva. Hay dos formas de conocerla:

Random: Caminas por calles al azar. Descubres un restaurant bueno, un parque bonito, un callejon raro. Después de 3 horas, conoces fragmentos desconectados.

Sistematico: Primero miras el mapa (estructura). Identificas los puntos cardinales y avenidas principales (entry points). Entiendes como fluye el trafico (data flow). Notas que hay un barrio historico y uno moderno (patterns). Identificas zonas en construccion (tech debt). Después de 30 minutos con el mapa, conoces la ciudad mejor que después de 3 horas caminando al azar.

El método sistematico no es mas lento — es dramaticamente mas rápido y produce mejor comprension.

Las 5 Preguntas Iniciales

Estas son las 5 preguntas que debes hacer cada vez que entras a un codebase nuevo, en este orden exacto. Cada pregunta construye sobre la respuesta de la anterior.

Pregunta 1: Estructura

Que preguntas: Como esta organizado este proyecto? Que carpetas hay y que hace cada una?

Por que es primero: Necesitas el mapa antes de explorar el territorio. Sin entender la organización, cada archivo que abras sera un dato aislado sin contexto.

Prompt para Claude Code:

claude

> Acabo de clonar este proyecto y nunca lo he visto. Describeme 
  la estructura de directorios: que carpetas principales hay, que 
  contiene cada una, y que patron de arquitectura sigue el proyecto.

Output esperado:

Estructura del proyecto (FastAPI API para e-commerce):

src/
+-- api/              -> Endpoints HTTP (organizados por recurso)
|   +-- v1/           -> Version 1 de la API
|   |   +-- products.py   -> CRUD de productos
|   |   +-- orders.py     -> Gestion de ordenes
|   |   +-- users.py      -> Registro y perfil
|   |   +-- auth.py       -> Login, tokens
|   +-- deps.py       -> Dependencies compartidas (DB session, auth)
+-- models/           -> Modelos SQLAlchemy (ORM)
+-- schemas/          -> Pydantic schemas (validacion entrada/salida)
+-- services/         -> Logica de negocio
+-- repositories/     -> Acceso a base de datos
+-- core/             -> Configuracion, seguridad, middleware
+-- migrations/       -> Alembic (migraciones de DB)
tests/                -> Tests con pytest
docker-compose.yml    -> Setup de desarrollo (PostgreSQL, Redis)
pyproject.toml        -> Dependencias y config

Patron: Layered Architecture con Service Layer + Repository Pattern

Que obtienes: Un mapa mental del proyecto. Ahora sabes que es un proyecto FastAPI, usa layers (api -> services -> repositories), tiene versionado de API, y usa Docker para desarrollo.

Pregunta 2: Entry Points

Que preguntas: Donde empieza la ejecución? Como entran los requests al sistema?

Por que es segundo: Ya conoces la estructura (pregunta 1). Ahora necesitas saber por donde "entra" la información al sistema. Sin esto, no puedes trazar flujos de datos.

Prompt para Claude Code:

> Cual es el entry point de esta aplicacion? Como se levanta? 
  Como se registran los endpoints? Muestrame el flujo desde 
  el arranque hasta que un endpoint esta listo para recibir requests.

Output esperado:

Entry point: src/main.py

Flujo de arranque:
1. main.py crea la instancia de FastAPI()
2. Registra middleware:
   - CORSMiddleware (origenes permitidos desde config)
   - RequestLoggingMiddleware (custom, en core/middleware.py)
   - ErrorHandlerMiddleware (custom, maneja excepciones globales)
3. Incluye routers:
   - app.include_router(products.router, prefix="/api/v1/products")
   - app.include_router(orders.router, prefix="/api/v1/orders")
   - app.include_router(users.router, prefix="/api/v1/users")
   - app.include_router(auth.router, prefix="/api/v1/auth")
4. Evento de startup:
   - Conecta a PostgreSQL (via SQLAlchemy async)
   - Conecta a Redis (para cache y rate limiting)
   - Corre health check
5. Se ejecuta con: uvicorn src.main:app --host 0.0.0.0 --port 8000

Los routers usan Depends() para inyectar:
- get_db() -> session de base de datos
- get_current_user() -> usuario autenticado (JWT)

Que obtienes: Sabes exactamente donde empieza todo (main.py), como se conectan los pieces (routers, middleware, startup events), y como se ejecuta. Ahora puedes trazar cualquier flujo de datos desde su origen.

Pregunta 3: Data Flow

Que preguntas: Como viajan los datos desde que entran al sistema hasta que salen?

Por que es tercero: Ya conoces la estructura (pregunta 1) y los entry points (pregunta 2). Ahora puedes trazar como fluyen los datos a traves de las capas que identificaste. Sin las dos preguntas anteriores, este análisis no tendria contexto.

Prompt para Claude Code:

> Toma el flujo mas importante de esta aplicacion — la creacion 
  de una orden (o el flujo principal si no hay ordenes). Traza 
  paso a paso como los datos viajan desde el request HTTP hasta 
  que se persisten. Incluye validaciones, transformaciones, y 
  manejo de errores en cada paso.

Output esperado:

Flujo: POST /api/v1/orders (crear orden)

1. REQUEST ENTRY (api/v1/orders.py:create_order)
   Input: OrderCreateSchema {
     product_ids: list[int],
     quantities: list[int], 
     shipping_address_id: int
   }
   -> Pydantic valida: tipos correctos, listas no vacias
   -> Depends(get_current_user) verifica JWT y extrae user_id

2. SERVICE LAYER (services/order_service.py:create_order)
   -> Valida que todos los product_ids existen (via product_repo)
   -> Verifica stock disponible para cada producto
   -> Calcula precio total (producto.price * quantity por cada item)
   -> Aplica descuentos si hay cupon activo (via coupon_service)
   -> Crea instancia de OrderModel con status="pending"

3. REPOSITORY LAYER (repositories/order_repo.py:create)
   -> session.add(order)
   -> session.add_all(order_items)  # items individuales
   -> session.commit()
   -> session.refresh(order)

4. POST-CREATION (services/order_service.py:_post_create)
   -> Descuenta stock (via product_repo.decrement_stock)
   -> Envia evento a Redis (para notificaciones async)
   -> Log de auditoria (via audit_service)

5. RESPONSE (api/v1/orders.py)
   -> Retorna OrderResponseSchema (incluye items, precio total, status)

ERRORES POSIBLES:
- 422: Pydantic validation (product_ids vacio, tipos incorrectos)
- 404: Producto no encontrado
- 409: Stock insuficiente
- 401: Token JWT invalido o expirado
- 500: Error de DB (handled por ErrorHandlerMiddleware)

Que obtienes: Entiendes como los datos se transforman a traves del sistema. Ves la cadena completa: request -> validación -> lógica de negocio -> persistencia -> side effects -> response. Este es el conocimiento que mas tiempo toma adquirir manualmente.

Pregunta 4: Patterns

Que preguntas: Que design patterns y convenciones se usan consistentemente?

Por que es cuarto: Ya entiendes la estructura (1), los entry points (2), y el data flow (3). Ahora puedes identificar los patterns porque tienes suficiente contexto para reconocer que es un pattern vs que es un caso aislado.

Prompt para Claude Code:

> Que design patterns y convenciones se usan en este proyecto? 
  Incluye: patterns de arquitectura, naming conventions, como se 
  manejan errores, como se organizan tests, y cualquier convencion 
  que un developer nuevo deberia seguir. Nota si hay inconsistencias.

Output esperado:

DESIGN PATTERNS:

1. Repository Pattern
   - Cada entidad tiene su repositorio en repositories/
   - Interface: create(), get(), get_by_id(), update(), delete(), list()
   - Ejemplo: UserRepository, ProductRepository, OrderRepository

2. Service Layer
   - Logica de negocio en services/
   - Los endpoints NUNCA acceden a repositorios directamente
   - Ejemplo: OrderService valida stock antes de crear orden

3. DTO Pattern (via Pydantic)
   - schemas/ contiene Create, Update, Response por entidad
   - Naming: {Entity}CreateSchema, {Entity}ResponseSchema
   - Response schemas NUNCA exponen campos sensibles (password, tokens)

4. Dependency Injection (FastAPI nativo)
   - Depends(get_db) para session de DB
   - Depends(get_current_user) para autenticacion
   - Depends(get_pagination) para parametros de paginacion

NAMING CONVENTIONS:
- Archivos: snake_case (user_service.py, product_repo.py)
- Clases: PascalCase (UserService, OrderCreateSchema)
- Funciones: snake_case (create_order, get_by_email)
- Constantes: UPPER_SNAKE (MAX_PAGE_SIZE, DEFAULT_TIMEOUT)

ERROR HANDLING:
- Custom exceptions en core/exceptions.py
- NotFoundError, ConflictError, PermissionError
- ErrorHandlerMiddleware los convierte a HTTP responses

TESTING:
- tests/ mirror de src/ (tests/services/test_order_service.py)
- Fixtures compartidas en conftest.py
- Factory pattern para crear test data (tests/factories/)

INCONSISTENCIAS DETECTADAS:
- reports/ module no sigue service->repository pattern
- 2 endpoints en users.py acceden a DB directamente (sin service)

Que obtienes: Las "reglas del juego" del proyecto. Cuando hagas tu primer cambio, sabras que patterns seguir, que naming usar, y donde estan las inconsistencias que debes evitar replicar.

Pregunta 5: Tech Debt

Que preguntas: Donde estan los problemas, riesgos, y deuda tecnica?

Por que es último: Necesitas entender como funciona el sistema (preguntas 1-4) antes de poder evaluar que esta mal. Sin ese contexto, no puedes distinguir entre "esto es tech debt" y "esto es una decisión de diseno intencional."

Prompt para Claude Code:

> Identifica tech debt y posibles problemas en este codebase. Busca: 
  TODOs pendientes, codigo duplicado, patterns inconsistentes, 
  dependencias desactualizadas, code smells, y cualquier cosa que 
  un developer nuevo deberia saber para evitar sorpresas.

Output esperado:

TECH DEBT IDENTIFICADO:

1. TODOs PENDIENTES (9 encontrados):
   - services/payment.py:45  "# TODO: agregar retry logic para Stripe"
   - services/email.py:12    "# TODO: hacer async"
   - models/user.py:8        "# TODO: migrar a UUID como PK"
   - api/v1/products.py:67   "# TODO: agregar paginacion real"
   ... (5 mas)

2. CODIGO DUPLICADO:
   - Logica de paginacion copiada en 4 endpoints
     (products.py, orders.py, users.py, reviews.py)
     -> Deberia ser un dependency o utility compartido
   - Validacion de permisos repetida en 3 services
     -> Deberia ser un decorator o middleware

3. PATTERNS INCONSISTENTES:
   - reports/ accede a DB directamente (no usa repository)
   - 2 endpoints en users.py bypasean el service layer
   - Algunos responses usan dict, otros usan schemas

4. DEPENDENCIAS DESACTUALIZADAS:
   - SQLAlchemy 1.4.x (actual: 2.0) — migracion no trivial
   - pydantic v1 (actual: v2) — migracion significativa
   - fastapi 0.95 (actual: 0.110+)

5. SECURITY CONCERNS:
   - Rate limiting solo en auth endpoints (deberia ser global)
   - No hay validacion de tamano de upload en files endpoint
   - CORS acepta * en desarrollo (verificar produccion)

6. DEAD CODE:
   - utils/legacy_helpers.py — ningun archivo lo importa
   - models/deprecated_user.py — no referenciado
   - tests/test_old_auth.py — tests para sistema de auth removido

PRIORIDAD SUGERIDA:
Alta: #5 (security), #4 (pydantic v1 → v2)
Media: #2 (duplicacion), #3 (inconsistencias)
Baja: #1 (TODOs), #6 (dead code)

Que obtienes: Un mapa de riesgos. Sabes que NO tocar sin cuidado (security concerns), que areas necesitan mejoras (duplicacion), y que puedes ignorar por ahora (dead code). Este conocimiento previene que accidentalmente empeores el tech debt existente.

La Diferencia: Random vs Sistematico

Comparacion lado a lado

Por que la exploracion random falla

La exploracion random tiene tres problemas fundamentales:

1. Sesgo de lo interesante. Abres los archivos que suenan mas interesantes, no los mas importantes. payment_service.py suena emocionante, pero main.py te da mas información sobre el sistema.

2. Rabbit holes. Cada archivo te lleva a otro, que te lleva a otro. Nunca vuelves al nivel de big picture. Es como intentar entender un pais visitando un solo barrio en profundidad.

3. Sin framework de referencia. Sin saber la estructura general, cada dato que aprendes es un punto flotante sin conexión. Sabes que "se usa Stripe" pero no sabes en que capa, como se conecta con el resto, ni si es la unica forma de procesar pagos.

Prompts Avanzados para Cada Pregunta

Estructura — variaciones según contexto

Para un proyecto nuevo que acabas de clonar:

claude

> Acabo de clonar este proyecto y nunca lo he visto. Describeme 
  la estructura completa. Para cada directorio principal, dime:
  1. Que contiene
  2. Que responsabilidad tiene
  3. De que otros directorios depende

Para un proyecto donde ya llevas unos minutos:

> Ya vi que este proyecto usa FastAPI con SQLAlchemy. Profundiza 
  en la estructura: como se organizan los modulos dentro de cada 
  capa? Hay sub-modulos o packages internos que no sean obvios?

Para un monorepo o proyecto grande:

> Este proyecto tiene muchas carpetas. Antes de entrar en detalles, 
  dame un overview de los top-level directories. Cuales son los 
  componentes principales y como se relacionan entre si?

Entry Points — variaciones según tipo de proyecto

Para una API/web app:

claude

> Como entran los requests a esta aplicacion? Muestrame el flujo 
  desde que llega un HTTP request hasta que se ejecuta el handler. 
  Incluye middleware, autenticacion, y cualquier procesamiento previo.

Para una CLI tool:

> Cual es el entry point de esta herramienta de linea de comandos? 
  Como se registran los comandos? Muestrame el flujo desde que el 
  usuario ejecuta el comando hasta que se produce el output.

Para una libreria:

> Como se usa esta libreria? Cual es la API publica principal? 
  Que clases o funciones exporta y como se conectan entre si?

Data Flow — variaciones según complejidad

Flujo básico (CRUD):

claude

> Traza el flujo completo de la operacion mas comun de esta app 
  (probablemente un CRUD). Desde el request hasta la respuesta, 
  incluyendo cada archivo y funcion involucrada.

Flujo complejo (con side effects):

> Traza el flujo de la operacion mas compleja de esta app. 
  Ademas del flujo principal, incluye: side effects (emails, 
  notificaciones, logs), operaciones asincronas, y manejo 
  de errores en cada paso.

Flujo de datos entre servicios:

> Como se comunican los diferentes servicios en este proyecto? 
  Hay llamadas sincronas, eventos, colas de mensajes? Muestra 
  un ejemplo de un flujo que involucre multiples servicios.

Patterns — variaciones según profundidad

Identificacion basica:

claude

> Que design patterns se usan en este proyecto? Dame ejemplos 
  concretos con archivos y lineas. Incluye patterns arquitecturales 
  y patterns de codigo.

Convenciones del equipo:

> Mas alla de los design patterns, que convenciones sigue este 
  equipo? Naming, estructura de archivos, como se organizan tests, 
  como se documentan funciones, como se manejan configuraciones.

Consistencia:

> Analiza si los patterns se aplican consistentemente en todo el 
  proyecto. Hay modulos que no siguen las convenciones generales? 
  Si hay inconsistencias, en que archivos estan?

Tech Debt — variaciones según urgencia

Scan general:

claude

> Identifica tech debt en este proyecto: TODOs, codigo duplicado, 
  dependencias desactualizadas, code smells, dead code. Prioriza 
  por impacto (que deberia arreglarse primero).

Enfocado en seguridad:

> Analiza este proyecto buscando problemas de seguridad: 
  inputs no validados, SQL injection posible, secrets hardcodeados, 
  autenticacion debil, CORS mal configurado, dependencias con 
  vulnerabilidades conocidas.

Enfocado en mantenibilidad:

> Que haria que este codebase sea dificil de mantener a largo plazo? 
  Busca: acoplamiento excesivo, falta de abstracciones, funciones 
  demasiado largas, responsabilidades mezcladas, falta de tests.

Adaptando las Preguntas a Diferentes Tipos de Proyectos

Las 5 preguntas son universales, pero los detalles cambian según el tipo de proyecto:

Para monorepos, agrega un "Paso 0" antes de las 5 preguntas:

claude

> Paso 0: Este es un monorepo. Cuantos packages/servicios contiene? 
  Cual es la relacion entre ellos? Hay dependencias compartidas?

Después aplica las 5 preguntas a cada package/servicio por separado.

El Framework Visual

Para que internalices el método, aquí esta el framework completo en una sola vista:

Tiempo total: 15-20 minutos. Resultado: mental model coherente del codebase completo.

Conexión con Proyecto

En el mini-proyecto del módulo (capsula 06):

• Aplicaras las 5 preguntas en secuencia a un codebase open-source real
• Documentaras las respuestas como parte de tu onboarding doc
• Mediras el tiempo total de las 5 preguntas
• Compararas con cuanto habrias tardado manualmente

En el proyecto integrador (Módulo 8):

• Las 5 preguntas seran el primer paso de tu migracion de proyecto legacy
• El onboarding doc que generes sera la base para planificar el refactoring
• La calidad de tu comprension determinara la calidad de la migracion

Todo lo que aprendes hoy se usa directamente en la capsula 04 (mental model) y en la capsula 05 (onboarding doc).

Troubleshooting

Problema 1: "Claude Code da respuestas demasiado largas para las preguntas de estructura"

Causa: El proyecto tiene muchos subdirectorios o Claude Code incluye detalles de archivos individuales.

Solución:

# Limita el scope:
> Describeme SOLO los directorios top-level de este proyecto 
  (no subdirectorios). Para cada uno, una linea describiendo 
  su responsabilidad.

Problema 2: "No encuentro un entry point obvio"

Causa: Algunos proyectos no tienen un main.py o app.py evidente. Puede ser una libreria, un package, o un proyecto con entry points multiples.

Solución:

# Pide ayuda para encontrar el entry point:
> No veo un main.py ni app.py obvio. Donde empieza la ejecucion 
  de este proyecto? Revisa pyproject.toml, setup.py, o Makefile 
  para encontrar como se ejecuta.

Problema 3: "Las 5 preguntas dan información incompleta para mi codebase"

Causa: Codebases muy especializados (machine learning, infrastructure, gaming) pueden necesitar preguntas adicionales.

Solución: Agrega preguntas especificas al dominio después de las 5 basicas:

# Para ML projects:
> Ademas de las preguntas generales: donde estan los modelos? 
  Como se entrenan? Donde estan los datasets? Como se hace 
  inference en produccion?

# Para infrastructure:
> Ademas de las preguntas generales: que recursos de cloud 
  se provisionan? Como se hace deploy? Que monitoring hay?

Problema 4: "Claude Code identifica tech debt que es intencional"

Causa: Lo que parece tech debt puede ser una decisión de diseno consciente.

Solución:

# Pide contexto adicional:
> Dijiste que reports/ no sigue el repository pattern. Es posible 
  que sea intencional? Revisa si hay comentarios, documentacion, 
  o commits que expliquen por que es diferente.

Problema 5: "Las respuestas de la pregunta 3 (data flow) son superficiales"

Causa: La pregunta puede ser demasiado amplia, o el flujo es complejo y Claude Code resume demasiado.

Solución:

# Divide en sub-preguntas:
> El flujo de crear orden tiene 5 pasos segun tu respuesta anterior. 
  Profundiza en el paso 2 (service layer): que validaciones exactas 
  se hacen? Que excepciones se lanzan? Mostrame el codigo relevante.

Ejercicios

Ejercicio 1: Ordenar las preguntas (Fácil)

Las siguientes preguntas estan desordenadas. Ordenalas según el framework de las 5 preguntas iniciales y explica por que ese orden es correcto:

• "Que TODOs pendientes tiene este proyecto?"
• "Como fluyen los datos desde el endpoint hasta la DB?"
• "Cual es la estructura de directorios?"
• "Que design patterns se usan?"
• "Donde esta el entry point?"

Ejercicio 2: Escribir prompts especificos (Fácil)

Para cada una de las 5 preguntas, escribe un prompt personalizado para un proyecto Django (en vez de FastAPI). Incluye terminologia de Django.

# Pregunta 1 — Estructura (adaptada a Django):
> Describeme la estructura de este proyecto Django. Que apps hay? 
  Como estan organizados los modelos, vistas, URLs, y templates? 
  Sigue el patron app-per-feature o tiene una estructura diferente?

# Pregunta 2 — Entry Points (adaptada a Django):
> Cual es el entry point? Donde esta el urls.py principal? 
  Como se registran las apps en INSTALLED_APPS? Muestrame 
  el flujo desde settings.py hasta que un URL pattern esta listo.

# Pregunta 3 — Data Flow (adaptada a Django):
> Traza el flujo de un POST request al formulario mas importante 
  de esta app: desde la URL, pasando por la view, el form, 
  el model, y hasta que se guarda en la DB. Incluye signals 
  si hay alguno involucrado.

# Pregunta 4 — Patterns (adaptada a Django):
> Que patterns usa este proyecto? CBVs o FBVs? Django REST Framework? 
  Hay mixins custom? Como se organizan los serializers? Que 
  convenciones de naming se siguen? Usa management commands?

# Pregunta 5 — Tech Debt (adaptada a Django):
> Que tech debt ves? Migraciones pendientes? Modelos con campos 
  deprecated? Views que no usan el ORM correctamente (N+1 queries)? 
  Settings hardcodeados que deberian estar en env vars?

Ejercicio 3: Exploracion real con las 5 preguntas (Medio)

Clona un proyecto open-source que nunca hayas visto y aplica las 5 preguntas en orden. Cronometra cada pregunta.

Proyectos sugeridos:

• httpx — HTTP client (mediano)
• typer — CLI framework (pequeno)
• rich — Terminal formatting (mediano-grande)

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

Registra tus resultados en este formato:

Proyecto: [nombre]
Fecha: [fecha]
Pregunta 1 (Estructura): [tiempo] — [hallazgo principal]
Pregunta 2 (Entry Points): [tiempo] — [hallazgo principal]
Pregunta 3 (Data Flow): [tiempo] — [hallazgo principal]
Pregunta 4 (Patterns): [tiempo] — [hallazgo principal]
Pregunta 5 (Tech Debt): [tiempo] — [hallazgo principal]
Total: [tiempo total]

Proyecto: httpx
Fecha: 2026-04-05
Pregunta 1 (Estructura): 2 min — Libreria organizada en httpx/ con 
  modulos por responsabilidad (_client.py, _transports/, _models.py).
  Tests comprehensivos en tests/. Docs en docs/.
Pregunta 2 (Entry Points): 2 min — API publica es httpx.Client (sync) 
  y httpx.AsyncClient (async). __init__.py exporta las clases principales.
  Tambien hay funciones convenience: httpx.get(), httpx.post(), etc.
Pregunta 3 (Data Flow): 4 min — httpx.get(url) crea un Client temporal,
  construye un Request object, lo pasa al transport layer (httpcore),
  httpcore maneja conexion/HTTP, retorna Response que httpx envuelve
  en httpx.Response con metodos convenience (.json(), .text, etc.)
Pregunta 4 (Patterns): 4 min — Transport abstraction (pluggable backends),
  context manager pattern (with Client()), builder pattern para requests,
  sync/async mirror (misma API, diferente implementacion).
Pregunta 5 (Tech Debt): 3 min — Baja deuda tecnica (proyecto bien 
  mantenido). Algunos TODOs menores. Complejidad en el manejo de 
  HTTP/2 vs HTTP/1.1. _decoders.py tiene logica compleja que podria
  simplificarse.
Total: 15 minutos

Estimacion manual equivalente: 3-5 horas de lectura de codigo
Factor de aceleracion: ~12-20x

Ejercicio 4: Detectar la exploracion random (Medio)

Un companero te describe su sesión de onboarding a un proyecto nuevo:

"Primero abri el archivo de configuración de Stripe porque me asignaron un bug de pagos. Vi que importaba de payment_processor.py así que abri ese. Vi un TODO sobre retry logic y me puse a investigar patterns de retry. Después de una hora investigue como implementar circuit breaker pattern porque me parecio interesante. Al final del dia, entendi bien el sistema de pagos pero no se como esta organizado el resto del proyecto."

Identifica: que hizo mal? Como le aplicarias el framework de las 5 preguntas?

# Antes de tocar Stripe, hacer las 5 preguntas:

# 1. Estructura
> Como esta organizado este proyecto? Que modulos hay?
# Resultado: "Ah, pagos es solo 1 de 8 modulos."

# 2. Entry points
> Como entran los requests? Donde esta el router principal?
# Resultado: "Los pagos se inician desde el checkout endpoint."

# 3. Data flow
> Como fluye un pago desde que el usuario hace click hasta que 
  se confirma? Incluye todos los servicios involucrados.
# Resultado: "Checkout -> payment_service -> stripe_client -> webhook handler."

# 4. Patterns
> Que patterns se usan para integraciones externas como Stripe?
# Resultado: "Usan adapter pattern. Stripe es intercambiable."

# 5. Tech debt
> Que problemas hay en el modulo de pagos especificamente?
# Resultado: "El TODO de retry logic es el unico tech debt critico."

# DESPUES de las 5 preguntas, ahora si: 
# profundizar en el bug especifico con contexto completo.

Ejercicio 5: Crear variaciones de prompts (Avanzado)

Para la Pregunta 3 (Data Flow), escribe 3 variaciones de prompts para diferentes niveles de profundidad:

1. Nivel superficie: Overview del flujo principal
2. Nivel intermedio: Flujo detallado con validaciones y errores
3. Nivel profundo: Flujo completo con código, side effects, y edge cases

# NIVEL SUPERFICIE (overview rapido, 1-2 min):
> Dame un overview de alto nivel: cuando un usuario crea una orden, 
  que servicios se involucran y en que orden? Solo nombres de 
  archivos y funciones principales, sin detalles de implementacion.

# Output esperado: "orders.py -> order_service.py -> product_repo.py 
# -> order_repo.py. Involucra validacion de stock y calculo de precio."


# NIVEL INTERMEDIO (detallado, 3-5 min):
> Traza el flujo completo de creacion de orden: desde el HTTP request 
  hasta el commit en la DB. Para cada paso incluye: que funcion se 
  llama, que validaciones se hacen, que errores pueden ocurrir, y 
  que transformaciones de datos suceden.

# Output esperado: Cada paso con validaciones, transformaciones, 
# y errores posibles. ~15-20 lineas de detalle.


# NIVEL PROFUNDO (completo, 5-10 min):
> Necesito entender en profundidad como funciona la creacion de 
  ordenes. Para cada paso del flujo, muestrame: el codigo relevante 
  (no todo el archivo, solo las lineas clave), los side effects 
  (emails, notificaciones, logs, eventos), los edge cases que 
  se manejan, y los que NO se manejan pero deberian. Tambien 
  incluye como se hace rollback si algo falla a mitad del proceso.

# Output esperado: Codigo real intercalado con explicacion.
# Edge cases documentados. Gaps en manejo de errores identificados.

Ejercicio 6: Framework personalizado (Avanzado)

Disena tu propia extension del framework de 5 preguntas agregando 2-3 preguntas adicionales especificas para tu dominio de trabajo. Para cada pregunta adicional, define:

1. La pregunta
2. Por que la necesitas en tu contexto
3. Después de cual de las 5 preguntas originales la harias
4. El prompt que usarias con Claude Code

# Extensiones al framework de 5 preguntas para fintech

additional_questions = {
    "6_compliance": {
        "question": "Como maneja este sistema compliance y auditoria?",
        "why": "En fintech, cada transaccion debe ser auditable. "
               "Necesito saber donde estan los audit logs, como se "
               "rastrean las transacciones, y que regulaciones aplican.",
        "after": "Pregunta 4 (Patterns) — necesito conocer los "
                 "patterns generales para entender si compliance "
                 "esta integrado o es un add-on.",
        "prompt": "Como maneja este proyecto auditoria y compliance? "
                  "Hay audit logs? Como se rastrean transacciones? "
                  "Se registra quien hizo que y cuando? Hay "
                  "encriptacion de datos sensibles (PII, PCI)?"
    },
    "7_error_recovery": {
        "question": "Que pasa cuando algo falla a mitad de una transaccion?",
        "why": "En fintech, una transaccion parcial puede significar "
               "dinero perdido. Necesito saber que mecanismos de "
               "recovery existen.",
        "after": "Pregunta 3 (Data Flow) — necesito entender el "
                 "flujo completo para evaluar donde puede fallar.",
        "prompt": "Que mecanismos de error recovery hay para "
                  "transacciones financieras? Hay sagas, compensating "
                  "transactions, o idempotency keys? Que pasa si "
                  "el proceso falla a mitad de un pago?"
    },
    "8_testing_critical_paths": {
        "question": "Como se testean los flujos criticos (pagos, transfers)?",
        "why": "Los bugs en flujos de dinero son los mas costosos. "
               "Necesito saber que tan bien estan cubiertos por tests.",
        "after": "Pregunta 5 (Tech Debt) — para saber si la falta "
                 "de tests en areas criticas es tech debt conocido.",
        "prompt": "Que cobertura de tests tienen los flujos de pagos "
                  "y transferencias? Hay integration tests? Se testea "
                  "contra sandbox de Stripe/procesadores? Que edge "
                  "cases estan cubiertos y cuales no?"
    }
}

for key, question in additional_questions.items():
    number = key.split("_")[0]
    print(f"\nPregunta {number}: {question['question']}")
    print(f"  Por que: {question['why'][:80]}...")
    print(f"  Despues de: {question['after'][:60]}...")

Resumen

En esta capsula aprendiste:

• ✅ La exploracion random produce conocimiento fragmentado; la exploracion sistematica produce comprension coherente
• ✅ Las 5 preguntas iniciales son: estructura, entry points, data flow, patterns, tech debt — en ese orden
• ✅ El orden importa: cada pregunta necesita las respuestas anteriores como contexto
• ✅ Claude Code acepta prompts especificos y produce respuestas detalladas para cada pregunta
• ✅ Las 5 preguntas se adaptan a diferentes tipos de proyectos (APIs, librerias, CLIs, monorepos)
• ✅ El tiempo total del framework completo es 15-20 minutos — vs 1-2 semanas manualmente
• ✅ Los prompts se pueden variar en profundidad (superficie, intermedio, profundo) según la necesidad
• ✅ El framework es extensible: puedes agregar preguntas especificas a tu dominio

Proxima capsula: Crear el Mental Model — como convertir las respuestas de las 5 preguntas en un mental model coherente del codebase que puedas consultar y compartir.

Recursos Adicionales

1. Claude Code Documentation — Anthropic — Documentación oficial con ejemplos de análisis de código
2. The Art of Reading Code — Felienne Hermans — Libro sobre la ciencia de leer y entender código
3. Code Reading: The Open Source Perspective — Tecnicas sistematicas para leer codebases
4. Working Effectively with Legacy Code — Michael Feathers — El capitulo sobre "understanding the system" es directamente relevante
5. httpx — GitHub — Proyecto sugerido para practicar las 5 preguntas
6. Design Patterns — Refactoring.Guru — Referencia visual de design patterns para la pregunta 4
7. Technical Debt — Martin Fowler — Framework para pensar sobre tech debt (pregunta 5)
8. Software Architecture Patterns — O'Reilly — Referencia para identificar patterns arquitecturales

Siguiente capsula: Crear el Mental Model — como construir una representacion mental del codebase con Claude Code, incluyendo layers, modulos, dependencias, y data flow.

Módulo 1, Capsula 03 — Refactoring & Legacy Code with Claude Code Guide