Mapping the Codebase
Before you touch unfamiliar code, map who calls it, what it owns, and where its boundaries are.
When to use
- You're about to plan, change, debug, or extend a part of the codebase you don't know well.
- Skip only when a Step 3 boundary record for this region exists and is inside its freshness limit.
Step 1: Set the boundary
- Before reading anything, write the intended change, how far it could reach, and why the boundary you picked holds that reach. For a compatibility-sensitive change, never stop at direct callers.
- Pin the repository or working state and the identity of every external input the reading depends on.
Step 2: Map
- Start at the containing module and its neighbors: responsibilities, runtime entry points, callers, collaborators, data between them.
- As risk warrants, trace: generated code and build inputs; persistent state and migrations; public contracts and consumers; configuration, deployment, operational paths; the toolchain and the commands that build, run, and check it; tests, CI, proof surfaces; ownership and change history. Give an evidence-based reason for each surface on that list you leave out.
- Use the domain's vocabulary, never "service / handler / util".
- Attach each conclusion to current files, symbols, searches, commands, or revisions. Separate what you observed from what you inferred. Mark what is stale or unavailable.
Step 3: State the boundaries
- Write the boundary record to
.sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/boundary-record.mdunless the user names another path: what the region owns, what it delegates, where its seams are, which downstream obligations a change must preserve, what Step 1.2 pinned, and a freshness limit (a revision or date). - Past the limit, or once a pinned input has changed, revalidate the affected claims before relying on them.
- If implementation finds a caller or surface the map never covered, stop editing and return to Step 1 with it: recheck that the boundary holds the change's reach, map the surface from the code, and update the record before the next edit. Never extend the map from memory.
Gotchas
- A caller reached through configuration, reflection, a generated route, or a scheduler never appears in an import search, so a map built from imports draws a boundary that a runtime caller crosses.
- A capped search result, or one that skipped ignored, generated, or vendored paths, is not the full caller set.