---
name: codebase-map
description: "Maintains FEATURE_MAP.md, a one-line-per-feature index of where things live in the codebase. Read it before searching for code to change so you can skip re-exploring; update it after a change adds, moves, or renames a feature's location."
---

# Codebase Map

`FEATURE_MAP.md` at the repo root caches the answer to one question: where does feature X live? A stale entry is worse than no entry — it sends you confidently to the wrong place instead of triggering a real search. Every rule below exists to keep the map cheap to build and safe to trust.

## Before searching for code to change

1. Read `FEATURE_MAP.md` if it exists.
2. Feature listed? Confirm the exact path in that entry still exists — a quick `ls`/glob, not a full read. If it does, go straight there; no exploratory search needed. If it doesn't, the entry is stale: delete it and fall through to step 3.
3. Not listed (or no map yet): search normally — grep for the concrete symbol, route, or keyword — then add or fix the entry once you find it.

## After implementing a change

Update the matching line, as part of the same change, whenever the change adds a feature or changes the path an entry points to (moved, renamed, split up). Edits that leave that path untouched need no update, no matter how much the file's contents changed.

## Format

One line per feature/flow. The path must be the single most specific real file or directory that answers "where do I start reading" — that's what step 2 checks, so it's what has to stay current. Don't split path and entry-point across separate fields: an unchecked field goes stale silently.

- Payment flow — `src/domain/payment/PaymentProcessor.ts` (`process()`)
- Auth / login — `src/auth/session.ts` (`issueSession()`)
- Email notifications — `src/messaging/email/` (multiple files, no single entry point)

Group under `##` headers (Domain, API, Frontend, Infra) only once the flat list gets hard to scan.

## Bootstrapping

No map yet? Build it once: skim top-level directories and manifests, list the major features/flows, one line each. A handful of entries covering the main flows beats an exhaustive file — let step 3 above fill in the rest lazily, as you touch each area.