Codebase Map
Build a fast, honest orientation to code you don't know yet, so you can work in it safely. Reconnaissance for comprehension: what the code is, where it starts, how it flows, and what not to touch. A map, not a tour — pointers over prose, evidence over guesses.
What The Map Captures
- What it is: one paragraph of purpose and domain, from the README and the code, not marketing.
- Entry points: where execution starts — server/main, routes, CLI, cron/queue workers, build entry. The "start here" files.
- Architecture sketch: the few layers or modules that matter and how data flows between them. Not a file tree.
- Domain glossary: the 5-15 recurring domain nouns and verbs, one line each — the ubiquitous language.
- Key seams: the stable interfaces where behavior is substituted or extended (see module-design).
- Risky / don't-touch: load-bearing, security-sensitive, or fragile code, and invariants not to regress. Mark it, do not fix it.
- How to run and test: build/dev/test/single-test commands, local setup, env vars — from repo evidence, not guesses.
- Known tradeoffs: existing TRADEOFF annotations, TODOs of record, documented debt.
Guardrails
- Read evidence; do not invent structure. Flag uncertainty rather than guessing.
- Comprehension, not critique: this is not an over-engineering audit.
- Respect Chesterton's Fence: unclear or load-bearing code is "risky", not "delete me".
- Keep it short and proportional (~80-150 lines). A map longer than the territory is useless.
- Distinct from project-onboarding (which writes a durable AGENTS.md for the agent; this orients a reader first and can feed it) and debug (which drives a known failure).
1---2name: codebase-map3description: Codebase Map4---56# Codebase Map78Build a fast, honest orientation to code you don't know yet, so you can work in it safely. Reconnaissance for comprehension: what the code is, where it starts, how it flows, and what not to touch. A map, not a tour — pointers over prose, evidence over guesses.910## What The Map Captures1112- What it is: one paragraph of purpose and domain, from the README and the code, not marketing.13- Entry points: where execution starts — server/main, routes, CLI, cron/queue workers, build entry. The "start here" files.14- Architecture sketch: the few layers or modules that matter and how data flows between them. Not a file tree.15- Domain glossary: the 5-15 recurring domain nouns and verbs, one line each — the ubiquitous language.16- Key seams: the stable interfaces where behavior is substituted or extended (see module-design).17- Risky / don't-touch: load-bearing, security-sensitive, or fragile code, and invariants not to regress. Mark it, do not fix it.18- How to run and test: build/dev/test/single-test commands, local setup, env vars — from repo evidence, not guesses.19- Known tradeoffs: existing TRADEOFF annotations, TODOs of record, documented debt.2021## Guardrails2223- Read evidence; do not invent structure. Flag uncertainty rather than guessing.24- Comprehension, not critique: this is not an over-engineering audit.25- Respect Chesterton's Fence: unclear or load-bearing code is "risky", not "delete me".26- Keep it short and proportional (~80-150 lines). A map longer than the territory is useless.27- Distinct from project-onboarding (which writes a durable AGENTS.md for the agent; this orients a reader first and can feed it) and debug (which drives a known failure).
yuri-semenenko