Architecture.md Builder Create production-quality ARCHITECTURE.md files that serve as definitive maps of any codebase, following matklad's canonical guidelines with modern AI-agent documentation patterns. When to Use This Skill Creating architecture documentation for a new or existing repository Auditing a codebase to understand its structure Onboarding documentation for developers and AI agents User asks to "document the architecture", "create architecture.md", or "map this codebase" Core Principles (matklad's Guidelines) The canonical ARCHITECTURE.md follows these principles: Bird's eye overview - Problem being solved, high-level approach Coarse-grained codemap - Modules and relationships (country-level, not state-level) Named entities - Important files, types, modules by name (no links, use symbol search) Architectural invariants - Constraints, what is NOT done, absence patterns Layer boundaries - Transitions between systems Cross-cutting concerns - Issues spanning multiple modules See references/matklad-guidelines.md for detailed explanations. Workflow Phase 1: Research Best Practices (Optional) If unfamiliar with architecture documentation patterns, use Exa search:
Search for exceptional architecture.md examples
python3 ~/.claude/skills/exa-search/scripts/exa_search.py \ "architecture.md documentation best practices" \ --category github -n 10
Find matklad's original guidelines
python3 ~/.claude/skills/exa-search/scripts/exa_research.py \ "matklad ARCHITECTURE.md guidelines rust-analyzer" Phase 2: Codebase Exploration Launch 2-4 parallel exploration agents to map the codebase thoroughly: Use the Task tool with subagent_type=Explore for each major system area: 1. Core/Engine - Entry points, main abstractions, data structures 2. Transport/API - HTTP, WebSocket, message handling 3. Database/Persistence - Schema, migrations, queries 4. Frontend/UI - Components, state management, routing Agent prompts should ask: What are the key abstractions and types? How does data flow through this system? What are the main files and their line counts? What patterns are used consistently? What invariants does the code enforce? Target output: ~10-15k words of analysis per agent covering the full system. Phase 3: Draft ARCHITECTURE.md Create the document following this structure:
Architecture Brief intro: what this document is for, who it's for.
Bird's Eye View
What problem does this solve?
What is the core paradigm/approach?
Key design principles (3-5 bullets) [ASCII diagram showing major components]
High-Level Data Flow [Mermaid flowchart showing data flow]
Codemap
System 1 (path/)
Description, key files with line counts, key abstractions table.
System 2 (path/)
...
Architectural Invariants Rules that are ALWAYS true. Code patterns that are NEVER violated.
Cross-Cutting Concerns Issues that span multiple modules (auth, logging, error handling).
Layer Boundaries Diagram showing layers and their interfaces.
Key Files Reference | File | Lines | Purpose | |
|
|
| | ... | ... | ... |
Common Questions FAQ format: "Where do I find X?" → Answer See references/document-structure.md for detailed section guidance. See assets/architecture-template.md for a starting template. Phase 4: Verification Launch 2-3 review agents to verify accuracy: Use the Task tool with subagent_type=Explore to verify: 1. General accuracy - Do descriptions match actual code? 2. Line counts - Are they roughly accurate? 3. File references - Do all referenced files exist? Verification checklist: All referenced files exist Line count estimates within 20% of actual ASCII/Mermaid diagrams render correctly Document answers "where's the thing that does X?" No stale information from previous versions Phase 5: Apply Corrections Update the document based on review findings: Correct line counts Add missing files to structures Fix any inaccurate descriptions Update counts (e.g., "11 modules" → "13 modules") Quality Guidelines Diagrams ASCII diagrams for component relationships: ┌─────────────┐ ┌─────────────┐ │ Frontend │────▶│ Backend │ └─────────────┘ └─────────────┘ Mermaid diagrams for data flows: flowchart TB A [Input] --> B [Process] B --> C [Output] Line Counts Include approximate line counts for key files: Helps readers gauge complexity Use wc -l to verify Round to nearest 10 or 50 Named Entities Reference files, types, and modules by name without links: Good: "See WorkingMemory.ts for the immutable memory implementation" Bad: "See WorkingMemory " Why: Symbol search (Cmd+T, osgrep) is more reliable than links that rot. Invariants Document what the code NEVER does: "WorkingMemory never mutates in place" "API keys never reach the browser" "All database queries use prepared statements" Target Length Small projects: 200-400 lines Medium projects: 400-700 lines Large projects: 700-1000 lines Maximum: ~1200 lines (split into linked docs if larger) Output Single file: ARCHITECTURE.md in project root Optionally update CLAUDE.md or README.md with a reference to the new architecture document. Example Usage User: "Create an architecture.md for this repo" 1. Launch 3 exploration agents targeting core, transport, and frontend 2. Synthesize findings into ARCHITECTURE.md following the template 3. Launch 2 review agents to verify accuracy 4. Apply corrections 5. Commit and optionally update CLAUDE.md Resources references/matklad-guidelines.md - Canonical guidelines with rationale references/document-structure.md - Detailed section guidance assets/architecture-template.md - Starting template