Marcos Silva
33 lines
2.2 KiB
Markdown
33 lines
2.2 KiB
Markdown
---
|
|
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.
|