Codebase Compass
Navigate a large codebase by tracing real flows, not reading everything
Reduce "where do I start?" paralysis in large systems by generating an executable map: entrypoints, critical paths, ownership, and safe starter changes.
INGREDIENTS
PROMPT
Create a skill called "Codebase Compass". Ask me for: - Repo URL or a pasted directory tree - The top 3 user journeys we care about - The runtime entrypoint(s) (web server, worker, CLI, UI) Produce: - Entrypoints list + "first files to read" - 3 end-to-end flow maps with key functions/modules - Ownership + where logs/traces should appear - 5 "safe starter changes" with estimated effort Output in Markdown with short checklists.
How It Works
This recipe creates a "compass" for a repo: what runs first, what matters most, and how
requests/data move. It emphasizes hands-on tracing and small changes to build real context.
Triggers
- "This codebase is huge; I don't know where to begin."
- New team members spend weeks reading but not shipping
- PR reviews or bug fixes require repeated "who owns this?" questions
Steps
- Identify primary entrypoints (API handlers, workers, CLI, UI boot) and list them.
- Pick 3 critical user journeys and map them end-to-end (code + dependencies).
- Generate a dependency graph (modules/services) and annotate ownership/SLAs.
- Create a "safe change menu": docs fixes, logging, config typos, small refactors with tests.
- Add a "trace this request" walkthrough (commands + expected logs/traces).
Expected Outcome
- New engineers find their bearings quickly and ship meaningful changes sooner.
- Reviews and debugging become faster because entrypoints and flows are explicit.
Example Inputs
- "Show me the request flow for checkout → payment → receipt email."
- "Where do background jobs start and how do they get triggered?"
- "What's the smallest safe improvement I can ship this week?"
Tips
- Favor maps tied to real journeys over abstract diagrams no one uses.
- Keep the compass in the repo and update it when architecture changes.