| name | codebase-overview |
| description | Use to generate or refresh a codebase architecture overview — directory map, data flow, key component responsibilities — so future research reuses it instead of rediscovering the codebase. |
| allowed-tools | Read, Grep, Glob, Bash, Write |
| when_to_use | Use when starting on an unfamiliar codebase, when no overview exists yet, or after structural change since the last one was written. |
| argument-hint | [scope: full | frontend | backend (default: full)] |
| context | fork |
| agent | senior-engineer |
| effort | medium |
codebase-overview
- Reuse BOOT SEQUENCE signals from this session if already known; otherwise glob top-level dirs + manifest.
- Map each top-level source directory to a one-line purpose (skip node_modules/dist/build/.git/.next).
- Trace primary data flow: entry point → routing → key components/screens → data layer (API/store/DB).
- Flag performance-sensitive integration points by file:line — third-party script loading, router/navigation setup, large media/asset loading, analytics init.
- Write/update
PROJECT/.claude/codebase-overview.md with the findings — the reusable reference other tasks read instead of re-discovering. Record the architecture explicitly (pattern, boundaries, dependency direction, which layer owns transactions/errors/authz): detected-but-unrecorded is re-detected differently next session.
- Run
/arch-check once the map exists — it measures the tree against the architecture just recorded; a mixed pattern or an inverted dependency belongs in the overview as a known state, not as a surprise for the next feature.
- If root
CLAUDE.md lacks an architecture section, add ≤10 lines pointing to it (essentials inline, detail lazy-loaded from codebase-overview.md) — never let CLAUDE.md itself balloon past its existing budget.
- Never modify source files — documentation only.
Output
CODEBASE OVERVIEW: [project name] — written to PROJECT/.claude/codebase-overview.md
DIRECTORIES: [dir → one-line purpose]
DATA FLOW: [entry → routing → components → data layer]
KEY COMPONENTS: [component → responsibility — only non-obvious ones]
PERF-SENSITIVE: [file:line — why it matters]
CLAUDE.md: [updated | already covered | needs manual review — reason]