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

architecture-md-builder