Proyecto del Módulo: Exploración de Codebase con Explore

Descripción del proyecto

Este proyecto pone a prueba todo lo que aprendiste en el módulo: usar el Explore subagent para investigar un codebase real respondiendo preguntas específicas. No vas a modificar nada — solo investigar, analizar, y documentar. Es la prueba de que puedes usar Explore como herramienta de investigación profesional.

La diferencia con el proyecto del Módulo 1 (Onboarding) es que ahora tienes Explore como herramienta dedicada y tres patrones de exploración (top-down, dependency-following, feature-tracing). El Módulo 1 te enseñó a hacer onboarding general. Este proyecto te pide investigación profunda y dirigida.

El proyecto simula un escenario real: te asignan a un equipo con un codebase existente y tu tech lead te da 5 preguntas específicas que necesita respondidas antes de planificar el próximo sprint. Tienes que responderlas usando Explore, documentar tus hallazgos, y entregar un reporte que cualquier miembro del equipo pueda leer y entender.

Este proyecto conecta directamente con el Módulo 3 (Entender Arquitectura Existente), donde tus hallazgos de exploración se convierten en dependency maps y flow diagrams formales.

---

Objetivo del Proyecto

Demostrar dominio del Explore subagent respondiendo preguntas específicas sobre un codebase real usando los tres patrones de exploración.

Al completar este proyecto:

• ✅ Habrás usado Explore para investigar un codebase de 5K+ líneas
• ✅ Habrás aplicado los tres patrones (top-down, dependency-following, feature-tracing)
• ✅ Habrás usado búsqueda semántica para encontrar código por significado
• ✅ Habrás producido un reporte de investigación profesional
• ✅ Habrás medido la eficiencia de Explore vs investigación manual

---

Especificaciones Técnicas

Codebase Sugerido

Usa uno de estos proyectos open-source en Python (todos tienen el tamaño y complejidad correctos):

Proyecto	Líneas	Descripción	Por qué es bueno para este proyecto
httpx	~15K	HTTP client async	Múltiples layers, async patterns, middleware
typer	~8K	CLI framework	Architecture clara, dependency injection
rich	~20K	Terminal formatting	Muchos componentes, rendering pipeline
fastapi	~12K	Web framework	Routing, middleware, dependency injection

Recomendación: httpx o typer. Ambos tienen buena documentación pero suficiente complejidad para que la investigación sea interesante.

Setup

# Clonar el proyecto elegido
git clone https://github.com/encode/httpx.git
cd httpx

# Abrir Claude Code en el proyecto
claude

# Verificar que Explore funciona
> "Usa Explore para describir la estructura de este proyecto"

Herramientas necesarias

• Claude Code con acceso a Explore subagent
• Terminal / editor de texto para documentar
• Git para clonar el proyecto

---

Las 5 Preguntas de Investigación

Tu tech lead necesita estas 5 preguntas respondidas. Cada una requiere un patrón de exploración diferente:

Pregunta 1: Estructura General (Top-Down)

"¿Cuál es la arquitectura general del proyecto? Describe las capas principales, los componentes clave, y cómo se organizan los archivos."

Requisitos de la respuesta:

• Estructura de directorios de primer nivel con propósito de cada carpeta
• Identificación de capas (si existen): API, lógica, datos, utils
• Componentes principales con 1 frase descriptiva cada uno
• Diagrama simple (ASCII o mermaid) de la arquitectura

Patrón: Top-Down, niveles 1-2

Pregunta 2: Flujo Principal (Feature-Tracing)

"¿Cómo funciona el flujo principal del proyecto? Traza el camino desde que un usuario inicia una acción hasta que obtiene un resultado."

Para httpx: "¿Cómo se ejecuta un request HTTP desde httpx.get(url) hasta recibir la respuesta?" Para typer: "¿Cómo se procesa un comando CLI desde que el usuario lo escribe hasta que se ejecuta?"

Requisitos de la respuesta:

• Trace completo paso a paso: archivo → función → qué hace
• Datos que fluyen en cada paso (input → output)
• Al menos 5 pasos en el trace
• Identificación de dónde ocurren transformaciones de datos

Patrón: Feature-Tracing

Pregunta 3: Sistema de Dependencias (Dependency-Following)

"¿Cuáles son los 3 módulos más conectados del proyecto? Para cada uno, ¿de qué depende y quién depende de él?"

Requisitos de la respuesta:

• Identificación de los 3 módulos con más conexiones
• Para cada uno: dependencias salientes (imports) y dependientes entrantes (quién lo importa)
• Señales de alerta: ¿hay dependencias circulares? ¿módulos god object?
• Mini dependency map (texto o mermaid)

Patrón: Dependency-Following

Pregunta 4: Búsqueda Semántica (Semántica vs Grep)

"Encuentra dónde se implementa manejo de errores en el proyecto. Compara lo que encuentras con grep vs lo que encuentras con Explore."

Requisitos de la respuesta:

• Resultado de grep -rn "error\|exception\|raise" src/ (cuenta de resultados)
• Resultado de Explore: "¿Dónde y cómo se manejan errores en este proyecto?"
• Comparación: qué encontró Explore que grep no encontró
• Al menos 2 ejemplos de código que maneja errores sin usar las palabras "error" o "exception"

Patrón: Búsqueda semántica + grep combinados

Pregunta 5: Investigación Abierta

"Encuentra algo interesante, inesperado, o preocupante en el codebase que no se haya preguntado arriba."

Requisitos de la respuesta:

• Un hallazgo original (no repetir respuestas anteriores)
• Explicación de por qué es interesante, inesperado, o preocupante
• Evidencia (archivos y funciones específicas)
• Recomendación de acción (si aplica)

Patrón: Cualquiera o combinación

---

Formato del Reporte

Tu entregable es un documento markdown con esta estructura:

# Reporte de Investigación: [Nombre del Proyecto]

**Investigador:** [Tu nombre]
**Fecha:** [Fecha]
**Codebase:** [URL del repo]
**Herramienta:** Claude Code con Explore subagent

---

## Pregunta 1: Estructura General

### Respuesta
[Tu respuesta con diagrama]

### Método
[Qué patrón usaste, qué prompts diste a Explore]

### Prompts utilizados

[Prompts exactos que usaste]

---

## Pregunta 2: Flujo Principal

### Respuesta
[Trace completo paso a paso]

### Método
[Feature-tracing, prompts usados]

---

[... Preguntas 3-5 ...]

---

## Métricas

| Métrica | Valor |
|---------|-------|
| Tiempo total de investigación | [X minutos] |
| Número de prompts a Explore | [X] |
| Número de comandos grep | [X] |
| Estimación tiempo manual | [X horas] |
| Factor de aceleración | [Xh manual / Xmin con Explore] |

---

## Reflexión

[2-3 párrafos sobre qué aprendiste del codebase
y sobre el proceso de investigación con Explore]

---

Validaciones y Proceso

Antes de empezar

• Proyecto clonado y accesible
• Claude Code abierto en el directorio del proyecto
• Explore subagent funcionando (verifica con un prompt simple)
• Documento de reporte creado con estructura base

Durante la investigación

• Cada pregunta usa el patrón correcto
• Documenta los prompts exactos que usas (no solo las respuestas)
• Si un prompt no funciona, documenta el intento fallido y la corrección
• Cronometra cada pregunta por separado

Al terminar

• Las 5 preguntas tienen respuestas completas
• Cada respuesta incluye evidencia (archivos, funciones, líneas)
• La sección de métricas está completa
• La reflexión tiene sustancia (no es genérica)

---

Criterios de Éxito

Tu proyecto está completo cuando:

• ✅ Las 5 preguntas tienen respuestas documentadas con evidencia
• ✅ Cada respuesta identifica el patrón de exploración usado
• ✅ Los prompts exactos están documentados (reproducibilidad)
• ✅ La comparación grep vs Explore (Pregunta 4) tiene datos concretos
• ✅ El hallazgo original (Pregunta 5) es genuinamente interesante
• ✅ Las métricas de tiempo están completas
• ✅ El reporte es legible por cualquier developer del equipo

---

Rúbrica de Evaluación (100 puntos)

Calidad de Investigación (50 puntos)

• (10 pts) Pregunta 1: Estructura general completa con diagrama
• (10 pts) Pregunta 2: Trace de flujo con 5+ pasos detallados
• (10 pts) Pregunta 3: Dependency map de 3 módulos con análisis
• (10 pts) Pregunta 4: Comparación grep vs Explore con datos concretos
• (10 pts) Pregunta 5: Hallazgo original con evidencia y recomendación

Uso de Patrones (25 puntos)

• (5 pts) Top-Down aplicado correctamente (Pregunta 1)
• (5 pts) Feature-Tracing aplicado correctamente (Pregunta 2)
• (5 pts) Dependency-Following aplicado correctamente (Pregunta 3)
• (5 pts) Búsqueda semántica vs grep demostrada (Pregunta 4)
• (5 pts) Elección de patrón justificada en cada pregunta

Documentación (25 puntos)

• (5 pts) Prompts exactos documentados (reproducibilidad)
• (5 pts) Métricas de tiempo completas y creíbles
• (5 pts) Reporte legible y bien estructurado
• (5 pts) Evidencia concreta (archivos, funciones, líneas específicas)
• (5 pts) Reflexión con insights genuinos

Extra Credit (hasta +10 puntos)

• (+5 pts) Investigación incluye un sexto hallazgo adicional
• (+3 pts) Diagrama mermaid generado por Claude Code incluido
• (+2 pts) Comparación de eficiencia con un compañero que investigó manualmente

---

Ejemplo de Implementación Mínima

Este es un ejemplo abreviado de cómo se ve una respuesta a la Pregunta 2 (Flujo Principal) para el proyecto httpx:

## Pregunta 2: Flujo Principal

### Respuesta

El flujo de `httpx.get("https://example.com")` pasa por 7 pasos:

1. **httpx/_api.py:get()** — Función de conveniencia que crea
   un Client temporal y delega a client.get()

2. **httpx/_client.py:Client.get()** — Llama a self.request()
   con method="GET"

3. **httpx/_client.py:Client.request()** — Construye el Request
   object, aplica auth y redirects

4. **httpx/_client.py:Client._send()** — Maneja transport
   selection y connection pooling

5. **httpx/_transports/default.py:HTTPTransport.handle_request()**
   — Usa httpcore para la conexión TCP real

6. **httpcore — conexión TCP + TLS + HTTP/1.1 o HTTP/2**
   — Envía bytes, recibe bytes

7. **httpx/_models.py:Response** — Construye el Response object
   con status_code, headers, content

### Método
Patrón: Feature-Tracing
3 prompts a Explore, 12 minutos total

### Prompts utilizados
> "Usa Explore para rastrear el flujo completo de
   httpx.get('https://example.com'). Empieza desde
   la función get() y sigue cada llamada hasta la
   respuesta HTTP."

> "Profundiza en el paso de Client._send(). ¿Cómo
   selecciona el transport y maneja connection pooling?"

> "¿Qué transformaciones sufren los datos desde el
   raw HTTP response hasta el objeto Response que
   recibe el usuario?"

Este ejemplo:

• ✅ Trace completo con 7 pasos
• ✅ Cada paso identifica archivo y función
• ✅ Prompts documentados
• ❌ Le falta la métrica de tiempo estimado manual (eso es tu trabajo)

---

Errores Comunes

Error 1: Respuestas demasiado vagas

Ejemplo malo: "El proyecto tiene varios módulos que se conectan entre sí." Ejemplo bueno: "El módulo _client.py depende de _transports/, _models.py, y _auth.py. Es importado por _api.py (funciones de conveniencia) y _client.py de async."

Solución: Siempre incluye nombres de archivos, funciones, y líneas específicas.

Error 2: No documentar prompts fallidos

Si tu primer prompt no produce buena respuesta, documéntalo. La iteración es parte del proceso.

Buena práctica:

# Intento 1 (demasiado vago):
> "¿Cómo funciona httpx?"
# Resultado: descripción genérica, no útil

# Intento 2 (específico):
> "Usa Explore para rastrear el flujo de httpx.get()
   desde la función pública hasta la conexión TCP"
# Resultado: trace detallado de 7 pasos ✅

Error 3: Usar solo un patrón para todo

Cada pregunta requiere un patrón diferente. Si usas solo top-down para las 5 preguntas, el reporte será superficial.

Error 4: No medir tiempo

Las métricas son parte del entregable. Sin ellas, no puedes demostrar el valor de Explore. Cronometra cada pregunta.

Error 5: Copiar output de Explore sin análisis

Explore te da datos. Tú interpretas. "Explore encontró 3 dependencias circulares" es dato. "Las 3 dependencias circulares están en el módulo de auth, lo cual sugiere que auth y sessions deberían separarse" es análisis.

Error 6: Elegir un proyecto demasiado simple

Un proyecto de 500 líneas no demuestra el valor de Explore. Necesitas al menos 5K líneas para que la herramienta brille vs investigación manual.

Error 7: No usar búsqueda semántica cuando es apropiada

La Pregunta 4 específicamente requiere comparar grep vs Explore. Si usas grep para todo, pierdes la oportunidad de demostrar la diferencia.

Error 8: Reporte que solo tú entiendes

El reporte debe ser legible por cualquier developer. Si asumes conocimiento que solo tú tienes, no cumple su propósito.

---

Recursos para el Proyecto

1. httpx - GitHub - HTTP client async para Python, excelente para este proyecto
2. typer - GitHub - CLI framework, alternativa más pequeña
3. rich - GitHub - Terminal formatting, alternativa más grande
4. Claude Code - Explore Docs - Referencia oficial del Explore subagent
5. Mermaid Live Editor - Para visualizar diagramas mermaid generados por Claude Code
6. Code Reading Techniques - Técnicas complementarias de lectura de código

---

Conexión con Siguiente Módulo

Lo que construiste aquí — hallazgos de exploración documentados — es el input del Módulo 3: Entender Arquitectura Existente. En el Módulo 3 vas a tomar estos hallazgos y convertirlos en representaciones formales:

• Tu respuesta a la Pregunta 1 (estructura) se convierte en un dependency map formal
• Tu respuesta a la Pregunta 2 (flujo) se convierte en un flow diagram documentado
• Tu respuesta a la Pregunta 3 (dependencias) se convierte en un grafo de dependencias con análisis de acoplamiento
• Tus hallazgos de la Pregunta 5 pueden revelar anti-patterns que documentarás formalmente

La transición es: "Ya puedes explorar y encontrar código eficientemente. Ahora convierte esos hallazgos en algo durable: dependency maps, diagramas de arquitectura, y flow analysis que cualquier miembro del equipo puede consultar."