Español

Trace One Real Request End-To-End

Want to understand any codebase fast? Follow one real request from the entry point all the way to the database and back. A file tree tells you nothing. Reading random files tells you less. One real execution path is the thread everything else hangs on — and once you have it, every other file in the repo has a place on the map.

Why one trace beats a week of browsing

Codebases aren't organized for reading; they're organized for the framework's convenience and years of accumulated decisions. The README describes the architecture as someone once intended it. The trace shows the architecture as it actually runs: which layers exist, which ones get skipped, where validation really happens, where the ORM ends and raw SQL begins. One concrete path gives you three things at once:

• The layers — router → controller → service → repository (or whatever this team actually does), in the order they really execute.
• The conventions — naming, error handling, dependency injection — visible in context instead of as abstract style rules.
• An anchor — every new file you open can be placed relative to the path you already know.

How to run the trace

1. Pick one boring, real request. "Get user profile" or "list orders" — something that touches the router, business logic, and the data store. Skip auth flows and webhooks on day one; they're full of special cases.
2. Find the entry point. Grep for the URL path or route name. In most web frameworks that lands you in a route table or a decorated handler.
3. Walk it with your editor, not your eyes. Go to Definition (F12 in VS Code) and Find All References (Shift+F12) follow calls precisely where scrolling guesses. GitHub's web UI does jump-to-definition too, if you can't clone yet.
4. Or walk it with a debugger. Set one breakpoint at the handler and step through — in Python, pdb's step, next, and where commands show the live call stack at every hop, which is the trace with zero guesswork.
5. Write it down. Ten lines: file → function → file → function, down to the query and back to the serialized response. That document is your map.

Rules of thumb

Power-user: feed the trace to your agent

The closer on the reel is the real payoff: give your coding agent that trace and it stops guessing. AI assistants read code the same way you do on day one — lots of plausible files, no ground truth about which path executes. A written trace fixes that:

• Put it in the project's context file (CLAUDE.md, AGENTS.md, or your tool's equivalent). Ten lines of "a request to /orders flows through routes.py → OrderService.list() → OrderRepo.query()" outperforms a paragraph of architecture prose, and it's exactly the kind of can't-infer-from-code context the Claude Code docs recommend keeping there.
• Ask the agent to extend the map, not redraw it. "Trace POST /orders the same way and diff it against the GET path" is a bounded task with a verifiable output.
• Refresh it when it lies. A trace that no longer matches the code is worse than none — re-walk it after big refactors, or have the agent re-verify it.

Onboarding a teammate? Hand them the trace document and one hour. It compresses weeks of "where does this actually happen?" into a single afternoon.

Resources

• Traces — OpenTelemetry concepts — the formal version of this tip: a trace is the path of a request through your application
• Code navigation — VS Code docs — Go to Definition, Find All References, and friends
• pdb — The Python Debugger — step, next, where: walking the live call stack
• Navigating code on GitHub — jump-to-definition and find-references in the browser
• Claude Code best practices — asking codebase questions and keeping persistent context in CLAUDE.md