# Mapping The Codebase

> Maps how a region of code fits together — its callers, owners, and boundaries — before it is changed. Use when code whose structure and callers have not been established for this task is about to be planned, changed, or debugged, or when asked how a change travels through the codebase. Skip only when a current boundary record covers the region and its inputs.

- Skill: `augments-labs/mapping-the-codebase` (Agent Skill)
- Install (CLI): `npx get-skill add augments-labs/mapping-the-codebase`
- Raw SKILL.md: https://api.skillmd.com/api/skills/augments-labs/mapping-the-codebase/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: augments-labs (https://skillmd.com/u/augments-labs)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/augments-labs/mapping-the-codebase

---


# 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

1. 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.
2. Pin the repository or working state and the identity of every external
   input the reading depends on.

## Step 2: Map

1. Start at the containing module and its neighbors: responsibilities,
   runtime entry points, callers, collaborators, data between them.
2. 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.
3. Use the domain's vocabulary, never "service / handler / util".
4. 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

1. Write the boundary record to
   `.sdlc-skills/evidence/{{YYYY-MM-DD}}-{{topic}}/boundary-record.md` unless
   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).
2. Past the limit, or once a pinned input has changed, revalidate the
   affected claims before relying on them.
3. 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.

