codebase-domain-map

Codebase Domain Map

Overview

A repo-local, regeneratable snapshot of "what lives where" — two small files under .claude/project-snapshot/ that give domain/folder-level orientation in one read, instead of re-deriving the module map with find/grep every time. Read it first; it narrows where to look, then use normal search tools inside that narrowed scope for the actual line-level answer.

Applies to every repository you work in — not just ones where .claude/project-snapshot/ already exists, and independent of whatever any single project's own CLAUDE.md/rules happen to say about a "project snapshot." A project's own rules may instruct reading its own already-generated snapshot by that name — that project-local instruction is one instance of this general, portable technique, not the whole of it. This skill is a different, standing thing: it applies in any repository, including ones with no such rule at all. If the snapshot is missing in the current repo, the correct move is to generate it (Setup below), never to skip the technique because no project-local rule told you to use it here.

Red Flags — Do Not Skip

Thought	Reality
"This project has a rule about a 'project snapshot' for a different repo, so that concept doesn't apply here"	That rule and this skill are not the same thing — this skill is a portable technique usable in any repo, with or without a matching project rule. Don't let a same-sounding project rule stand in for checking whether this skill applies
"No .claude/project-snapshot/ here, so I can't use this"	Missing means generate it, not skip it — that's what the bundled script is for
"This is someone else's/an unfamiliar repo, not mine"	Unfamiliar is exactly the case this technique is for — familiarity is not a prerequisite
"It's faster to just grep now"	The setup is a single script run; skipping it to grep blind is the slower path on anything past a handful of files, and it's the default a fresh agent reaches for anyway — that's the failure this skill exists to prevent

What it narrows and what it doesn't: domain/app/folder granularity only — not line- or symbol-level results. After the snapshot points at a folder, still grep/read inside it for the actual content.

When to Use

• Before find/grep/Explore/a research subagent, whenever the task is "find where X lives," "which app owns Y," "locate the file for Z."
• Every dispatching agent, not just yourself: when delegating codebase research to a subagent, read the snapshot yourself first and pass the narrowed domain/path straight into the subagent's prompt (e.g. "auth domain: backend — apps/api/src/app/auth, frontend — apps/web/src/pages/auth"). A subagent prompt that says "find the code for X" without pre-narrowing via the snapshot makes the subagent blindly re-derive the domain map you already had for free.
• Not needed for a single well-known file path, or a repo small enough to read ls output directly.

Files

• .claude/project-snapshot/overview.md — per-project domain list and entry points, human-readable.
• .claude/project-snapshot/domains.tsv — flat scope\ttype\tname\tpath table; fastest to grep for a keyword across every project at once.

There is deliberately no full file listing: it goes stale fast and adds noisy diffs, and file-level lookups are covered by a glob, rg --files, or the IDE's file search.

Setup / Refresh

Generate or refresh via the bundled script — works for Nx-style (apps/+libs/), Go/Rust-style (cmd/, internal/, crates/), and flat repos alike; it auto-detects which container directories exist and falls back to top-level dirs otherwise:

bash <skill-dir>/scripts/update-project-snapshot.sh          # repo root = git toplevel (or cwd)
bash <skill-dir>/scripts/update-project-snapshot.sh /path/to/repo   # explicit root

Re-run it after adding new apps/packages/domains — a stale snapshot missing a new domain is worse than no snapshot (silent false negative: a search comes back "nothing here" instead of "wrong place to look"). Commit the generated files if the team shares the convention; keep them local otherwise.

Common Mistakes

Mistake	Fix
Grepping the whole repo before checking the snapshot	Read overview.md/grep domains.tsv first — it's one file, not a search
Dispatching a research subagent with "find X" and no narrowed path	Read the snapshot yourself, pass the resolved domain/path into the subagent's prompt
Treating the snapshot as line-level search	It's folder-level only — still grep/read inside the narrowed folder for the real answer
Never regenerating after adding a new app/domain	Re-run the script — a stale snapshot produces false negatives, not just staleness