Immutable. This exact content is served forever at /api/v1/blob/d83d6d055b83ca23.
---
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:
```bash
# 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:
```markdown
# 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:
```mermaid
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](./src/lib/core/WorkingMemory.ts)"
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