diegosouzapw /map — Codebase Architecture Generator
Generate docs/codebase-architecture.md (the map) and .claude/CLAUDE.md (the scaffold) for any project.
Hard Rules
- Reference source, don't duplicate it. Use
file:linepointers. Only inline a snippet when it's a one-liner with no source location yet. - Tables over prose. Scannable, dense.
- Project vocabulary. Use the project's own names for layers, patterns, concepts.
- ASCII diagrams. No Mermaid, no images.
- Conditional sections. Include what's relevant, skip what isn't.
- Convention notes inline. Naming patterns, formatting rules, "when to use A vs B" — attach to the relevant section, not a separate section.
- 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:linerefs, 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:
- 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:lineref) - 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
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.