Codebase Compass

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

1. Identify primary entrypoints (API handlers, workers, CLI, UI boot) and list them.
2. Pick 3 critical user journeys and map them end-to-end (code + dependencies).
3. Generate a dependency graph (modules/services) and annotate ownership/SLAs.
4. Create a "safe change menu": docs fixes, logging, config typos, small refactors with tests.
5. 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.