Exploring a codebase is easier when the search has a destination. Start with the user-visible behavior, then trace inward until you find the data and decision that control it.
Search in layers
1. Find the surface
Look for the route, component, command, or error message a user encounters. This gives the investigation a concrete starting point.
2. Find the source of truth
Ask where the value comes from:
- a content file;
- a database query;
- an environment variable;
- a remote response;
- a derived calculation.
3. Find the boundary
The boundary is where one representation becomes another: Markdown becomes HTML, JSON becomes a typed object, or a request becomes a domain operation. Most useful fixes happen at boundaries.
Keep a tiny map
page -> collection query -> frontmatter schema -> markdown fileThis map is intentionally small. Add a node only when it changes the next action.
| If you find | Ask next |
|---|---|
| A duplicated label | Which one is canonical? |
| A nullable value | Who handles the empty state? |
| A broad catch block | What error is being hidden? |
| A conversion helper | Are all callers using it? |
Search is not a race to find a filename. It is a way to reduce the number of plausible explanations.
When the behavior is understood, stop searching and make the smallest complete change.