architecture-md-builder

name	architecture-md-builder
description	Build comprehensive ARCHITECTURE.md files following matklad's canonical guidelines — bird's-eye views, ASCII/Mermaid diagrams, codemaps, invariants, and layer boundaries. Triggers on document the architecture, create ARCHITECTURE.md, map this codebase, architectural overview.

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:

1. Bird's eye overview - Problem being solved, high-level approach
2. Coarse-grained codemap - Modules and relationships (country-level, not state-level)
3. Named entities - Important files, types, modules by name (no links, use symbol search)
4. Architectural invariants - Constraints, what is NOT done, absence patterns
5. Layer boundaries - Transitions between systems
6. 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