Marcos Paulo
2.2 KiB
name, description
| name | description |
|---|---|
| codebase-map | 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
- Read
FEATURE_MAP.mdif it exists. - 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. - 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.