codemap-usage

Using the Codebase Map

The codebase map (CODEBASE_MAP.md) is a structural index of the project designed for LLM navigation during agentic coding. It is NOT documentation — every line answers: what is this, what does it touch, and why should you care when making changes.

Before Making Any Change

1. Read the file's map entry — Check its dependencies, exports, and side effects
2. Check inbound dependencies — Find what other files import this one. These are your blast radius.
3. Respect side-effect warnings — Files marked with side effects have hidden behavior (callbacks, event listeners, global state mutations) that won't be visible in the direct call chain
4. Read annotations — Human-written descriptions and gotchas contain critical context that code alone doesn't reveal

How to Read the Map

Dependencies Section (Most Important)

**Dependencies:**
- <- `src/controllers/user.ts` (imports this)     ← INBOUND: will break if you change this file's interface
- -> `internal:./auth/service` (uses: AuthService) ← OUTBOUND: this file depends on AuthService
- -> `external:express` (uses: Router)             ← EXTERNAL: library dependency

Inbound dependencies (<-) tell you blast radius — how many files break if you change this file's exports. Outbound dependencies (->) tell you what this file needs — if those change, this file may break.

Side Effects Section

Files with a Side Effects section have behavior that executes implicitly:

• Lifecycle callbacks (before_save, useEffect, @PostConstruct)
• Event listeners/subscribers
• Background job enqueuing
• Global state mutations

These are the #1 source of bugs during agentic coding. The LLM can't see behavior that triggers outside the direct call chain.

Annotations

• Annotation: Human-curated one-liner about the file's purpose and impact
• Gotcha: Non-obvious behavior that could cause bugs
• Domain notes: Business context not obvious from code

Files marked "Needs annotation" lack human context — treat them with extra caution.

Commands

• /codemap:generate — Generate or regenerate the full codebase map
• /codemap:annotate — Add annotations to unannotated files interactively
• /codemap:status — Check map freshness, annotation coverage, file counts

Two-Layer Architecture

• Layer A (auto-generated): File paths, exports, imports, signatures, side effects. Regenerated on every /codemap:generate run. Disposable.
• Layer B (human annotations): Stored in CODEBASE_MAP.annotations.yml. Preserved across regenerations. Removed files have annotations moved to orphaned section, never deleted.

When the Map is Stale

If the session-start hook reports the map is stale, prompt the user to regenerate before making changes. A stale map may have outdated dependency information that leads to missed blast radius.