map-project

Map a project for agentic coding

Produce the durable files an agent needs to be oriented in a repo — built from the real code, lean, layered, and non-duplicating. The goal: a fresh agent opens the repo and already knows the architecture, the boundaries, where things live, how to run/test, the domain vocabulary, and the central data model.

The target file set (what "fully mapped" means)

File	Purpose	Loads
CLAUDE.md (repo root)	Always-on orientation: what the app is, architecture, where things live, how to add a feature, run/test commands, roadmap, standing rules	every session
.claude/rules/<area>.md (path-scoped)	The boundary + do/don'ts for one layer/package; one per major area	only when matching files are touched
.claude/rules/docs-sync.md (global)	"If you change X → also update Y" so docs never drift	every session
.claude/agents/<name>.md	Authored subagents (reviewers/workers), memory: project	when spawned
.claude/skills/<name>/SKILL.md	Domain workflows the agent can invoke	on demand
.claude/commands/<name>.md	Saved multi-step prompts (optional)	when invoked
.context/GLOSSARY.md	Domain + project vocabulary a newcomer won't know	reference
.context/<DATA_CONTRACT>.md	The central object/schema: fields, lifecycle, invariants	reference

(Use .context/ or docs/ — match what the repo already uses.)

Method — do these in order

1. Explore first; never write from assumptions. Run scripts/scan.py (prints the layer map, each package's classes + __all__, and run/test hints), then read: the entry points, the package/layer layout, each layer's public surface, the central data model, the run/test commands, and any existing README / CLAUDE.md / docs and their house style. Every claim you write must trace to a real file:line.
2. Decide the split. Identify the architecture (e.g. layered / hexagonal / feature-sliced) and the natural areas. One path-scoped rule per area; map each area's directory glob.
3. Generate — grounded and lean.
   • CLAUDE.md: < 200 lines. If one exists, improve it, don't overwrite. Cover: what the app is · architecture (and how it's enforced, e.g. a gate test) · where things live · how to add a feature · run/test commands · roadmap links · standing rules.
   • rules: each gets paths: frontmatter, the layer boundary, concrete do/don'ts, and real file pointers. They complement CLAUDE.md — don't restate it wholesale and never contradict it.
   • agents: focused; restrict tools; memory: project; read-only unless they must edit.
   • GLOSSARY.md: the domain terms (and project-specific terms) an outsider needs to read the code.
   • data-contract doc: the central object/schema — fields, who edits it, the create→validate→persist→run→read lifecycle, and invariants.
   • docs-sync.md: a table mapping each kind of change to the doc(s) that must update in the same commit.
4. Wire it. Point CLAUDE.md at the rules/context docs so they're discoverable; make docs-sync cover every doc you created.
5. Validate. Frontmatter parses; paths globs match real directories; agents have name + description; commands/run-lines actually work; nothing duplicates or contradicts across files.

See references/templates.md for ready skeletons of every file above.

Quality bar (check before finishing)

• CLAUDE.md < 200 lines, accurate tree + run/test commands
• every major area has a path-scoped rule (loads only when touched)
• subagents are scoped, tool-restricted, memory: project
• glossary covers terms a newcomer won't know
• the central data model / schema is documented
• a docs-sync rule keeps it all from drifting
• nothing duplicates or contradicts across files
• every claim is grounded in real code, not assumed

Notes

• Lean is the point. CLAUDE.md and global rules load every session — keep them short; push depth into path-scoped rules (load on match) and skills (load on demand).
• Respect existing conventions. If the repo already has a CLAUDE.md style, rules format, or a docs/ vs .context/ choice, match it.
• Gold-standard example: Salvus_MASW/salvus_sw — a fully-mapped repo (lean CLAUDE.md + per-layer rules + subagents + .context/{GLOSSARY, SIMULATION_JOB}). Mirror its shape for sibling repos.