English

Rastrea una petición real de punta a punta

¿Quieres entender cualquier codebase rápido? Sigue una petición real desde el punto de entrada hasta la base de datos y de vuelta. El árbol de archivos no te dice nada. Leer archivos al azar te dice menos. Una ruta de ejecución real es el hilo del que cuelga todo lo demás — y una vez que la tienes, cada archivo del repo encuentra su lugar en el mapa.

Por qué un rastreo vale más que una semana de lectura

Los codebases no están organizados para leerse; están organizados según la conveniencia del framework y años de decisiones acumuladas. El README describe la arquitectura como alguien la imaginó alguna vez. El rastreo muestra la arquitectura como realmente se ejecuta: qué capas existen, cuáles se saltan, dónde ocurre de verdad la validación, dónde termina el ORM y empieza el SQL crudo. Una ruta concreta te da tres cosas a la vez:

• Las capas — router → controller → service → repository (o lo que este equipo haga en realidad), en el orden en que de verdad se ejecutan.
• Las convenciones — nombres, manejo de errores, inyección de dependencias — visibles en contexto y no como reglas abstractas de estilo.
• Un ancla — cada archivo nuevo que abras puede ubicarse respecto a la ruta que ya conoces.

Cómo hacer el rastreo

1. Elige una petición real y aburrida. "Obtener perfil de usuario" o "listar pedidos" — algo que toque el router, la lógica de negocio y el almacén de datos. Evita flujos de autenticación y webhooks el primer día; están llenos de casos especiales.
2. Encuentra el punto de entrada. Busca con grep la ruta URL o el nombre de la ruta. En la mayoría de los frameworks web eso te lleva a una tabla de rutas o a un handler decorado.
3. Recórrela con tu editor, no con la vista. Go to Definition (F12 en VS Code) y Find All References (Shift+F12) siguen las llamadas con precisión donde el scroll solo adivina. La interfaz web de GitHub también tiene jump-to-definition, si aún no puedes clonar.
4. O recórrela con un debugger. Pon un breakpoint en el handler y avanza paso a paso — en Python, los comandos step, next y where de pdb muestran la pila de llamadas viva en cada salto: el rastreo sin adivinar.
5. Escríbelo. Diez líneas: archivo → función → archivo → función, hasta la consulta y de vuelta a la respuesta serializada. Ese documento es tu mapa.

Reglas prácticas

Nivel avanzado: dale el rastreo a tu agente

El cierre del reel es la verdadera ganancia: dale ese rastreo a tu agente de código y deja de adivinar. Los asistentes de IA leen el código igual que tú en tu primer día — muchos archivos plausibles, cero certeza sobre qué ruta se ejecuta. Un rastreo escrito lo arregla:

• Ponlo en el archivo de contexto del proyecto (CLAUDE.md, AGENTS.md o el equivalente de tu herramienta). Diez líneas de "una petición a /orders fluye por routes.py → OrderService.list() → OrderRepo.query()" rinden más que un párrafo de prosa arquitectónica, y es exactamente el tipo de contexto que no se infiere del código y que la documentación de Claude Code recomienda mantener ahí.
• Pídele al agente extender el mapa, no redibujarlo. "Rastrea POST /orders de la misma forma y compáralo con la ruta GET" es una tarea acotada con salida verificable.
• Actualízalo cuando mienta. Un rastreo que ya no coincide con el código es peor que ninguno — vuelve a recorrerlo tras refactors grandes, o pide al agente que lo re-verifique.

¿Onboarding de un compañero nuevo? Entrégale el documento del rastreo y una hora. Comprime semanas de "¿dónde pasa esto en realidad?" en una sola tarde.

Recursos

• Traces — conceptos de OpenTelemetry — la versión formal de este tip: un trace es la ruta de una petición a través de tu aplicación
• Code navigation — documentación de VS Code — Go to Definition, Find All References y más
• pdb — el debugger de Python — step, next, where: recorrer la pila de llamadas viva
• Navegar código en GitHub — jump-to-definition y find-references en el navegador
• Buenas prácticas de Claude Code — preguntas sobre el codebase y contexto persistente en CLAUDE.md

Read this article in English