map

/map — Codebase Architecture Generator

Generate docs/codebase-architecture.md (the map) and .claude/CLAUDE.md (the scaffold) for any project.

Hard Rules

1. Reference source, don't duplicate it. Use file:line pointers. Only inline a snippet when it's a one-liner with no source location yet.
2. Tables over prose. Scannable, dense.
3. Project vocabulary. Use the project's own names for layers, patterns, concepts.
4. ASCII diagrams. No Mermaid, no images.
5. Conditional sections. Include what's relevant, skip what isn't.
6. Convention notes inline. Naming patterns, formatting rules, "when to use A vs B" — attach to the relevant section, not a separate section.
7. Working directory context. Always specify where to run commands and what paths are relative to.

Process

Step 1: Detect

Check for docs/codebase-architecture.md and .claude/CLAUDE.md.

• Both exist → offer to audit (check stale file:line refs, missing files, undocumented additions)
• Missing → proceed to bootstrap

Step 2: Explore

Use subagents to scan config files, auto-detect the stack, and build a complete picture of the codebase — entry points, processing layers, state, file inventory, communication patterns, key types.

Step 3: Ask targeted questions

Focus on what exploration couldn't answer:

• What is this project? (one sentence)
• What are the 3-5 most common tasks a developer does in this codebase?
• Any key architectural decisions that aren't obvious from the code?
• Any gotchas or landmines you've hit?

Step 4: Generate architecture doc

Write docs/codebase-architecture.md using the section catalog below.

Step 5: Generate CLAUDE.md scaffold

Write .claude/CLAUDE.md:

• Use auto memory to remember to reference the architecture doc when searching, and to update it when making changes.
• Keep the architecture doc lean. Only the most essential, high-level info goes in the architecture doc. The CLAUDE.md is where the "wisdom" lives — detailed recipes, patterns, gotchas, and other insights that don't fit the architecture doc's format.
• Update frequency: When to update the architecture doc vs when to just update CLAUDE.md with new recipes, patterns, or gotchas.
• Auto-filled: Project name + one-line description, validation commands with working directory context, key stack/integration callouts
• Empty wisdom sections: Architecture Principles, Learned Patterns, Gotchas — each with a comment showing the expected format (one-line example with file:line ref)
• Excluded: Generic advice, stack-specific skill references, personal workflow preferences

Step 6: User reviews and commits

Present both files. User refines. Commit when approved.

---

Architecture Doc — Section Catalog

Authoring Guidelines for the architecture doc itself:

• Keep it lean. Only the most essential, high-level info goes in the architecture doc. The CLAUDE.md is where the "wisdom" lives — detailed recipes, patterns, gotchas, and other insights that don't fit the architecture doc's format.
• Use file:line refs. Don't reproduce info that's already in the source. Point at it with file:line.

Required: Header

One sentence + key tech + storage/persistence approach.

Required: Commands

Build, test, lint, format, REPL — whatever the project actually uses. Include working directory context.

Required: File Inventory

Tables grouped by domain concern (not directory structure). Every source file gets a one-line Role. Within each group, list subsystem enumerations (union types, enum-like constants) and note shared/reused components.

Conditional: Data Flow

When: Layered processing (web apps, event systems, pipelines, CLI with middleware).

Cover: Entry points, processing layers, output channels, both request and push directions, naming conventions at boundaries, sync vs async patterns.

Conditional: State Shape

When: Non-trivial state (game servers, real-time, complex frontend, stateful services).

Format: Compact key-type tables with file:line refs. Do NOT reproduce struct definitions — point at source. Cover: init location, key collections, polymorphic maps (flag explicitly), construction/transformation sites, derived vs stored state.

Conditional: Event/API Surface

When: External-to-internal mapping layer (REST endpoints, LiveView events, GraphQL resolvers, CLI subcommands, message handlers).

Cover: Category groupings by domain, surface → internal format mapping, naming conventions, when to use pattern A vs B, push/subscription events.

Conditional: Module Relationships

When: Composition root pattern, dependency graph, or non-obvious module coupling.

Cover: Composition roots, dependency direction, inline "why" notes for non-obvious coupling, boundary enforcement patterns.

Conditional: Common Task Guide

When: Repeatable patterns exist for extending the codebase. This is the highest-value section.

For each recipe: numbered steps with file:line refs, a Verify step (the command to run), and a canonical example to follow. Identify recipes from recent commits, test patterns, repeated file-edit patterns, and framework conventions. Include as many recipes as warranted.