The user needs a map, not a tour. They're disoriented in the codebase and want to understand how the thing they're looking at connects to everything around it.
What to produce
Build a context map anchored on whatever code is currently in focus (the file being discussed, the function just edited, or the module the user asked about). The map should answer: what is this, what does it talk to, and why does it exist?
Structure
-
One-sentence orientation — What this module/file is in plain terms and why it exists in the system.
-
Ancestry — Walk up the call chain or module hierarchy. Who owns this? What triggers it? Show the path from entrypoint to here, 2-3 levels up max.
-
Sibling map — What are the peer modules at this same level of abstraction? List them with one-line descriptions. This answers "what else lives here?"
-
Key connections — Inbound callers and outbound dependencies. Not every import — just the ones that matter for understanding the module's role. Use arrows or a simple ASCII diagram if it helps.
-
Domain vocabulary — If this area uses domain-specific terms (e.g., "tenant", "workspace", "pipeline stage"), define the 3-5 most important ones in the context of this codebase, not generic definitions.
How to research
- Read the current file and its imports
- Check the parent directory's structure (
lsthe containing folder) - Grep for usages of the main exports to find callers
- Glance at sibling files to understand the neighborhood
- Read any local README or CLAUDE.md for domain context
What NOT to do
- Don't explain implementation details or line-by-line code
- Don't suggest changes or refactors — this is orientation, not a code review
- Don't produce a wall of text — keep the map scannable
- Don't guess at architecture if you haven't read the code — investigate first