architecture-md-builder

Architecture.md 构建器

创建高质量的 ARCHITECTURE.md 文件，作为任何代码库的权威地图，遵循 matklad 的规范指南和现代 AI Agent 文档模式。

适用场景

• 为新建或现有代码仓库编写架构文档
• 审查代码库以了解其结构
• 为开发者和 AI Agent 编写入门文档
• 用户要求“记录架构”“创建 architecture.md”或“绘制代码库地图”

核心原则（matklad 指南）

规范的 ARCHITECTURE.md 应遵循以下原则：

1. 鸟瞰式概览 - 要解决的问题和高层方案
2. 粗粒度代码地图 - 模块及其关系（国家级，而非州级）
3. 命名实体 - 按名称列出重要文件、类型和模块（不使用链接，使用符号搜索）
4. 架构不变量 - 约束、不会执行的操作、缺失模式
5. 层边界 - 系统之间的转换
6. 横切关注点 - 涉及多个模块的问题

详见 references/matklad-guidelines.md。

工作流

阶段 1：研究最佳实践（可选）

如果不熟悉架构文档模式，可使用 Exa 搜索：

# 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"

阶段 2：探索代码库

启动 2-4 个并行探索 Agent，全面绘制代码库地图：

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 提示词应询问：

• 关键抽象和类型有哪些？
• 数据如何流经此系统？
• 主要文件有哪些？它们的行数是多少？
• 哪些模式被一致地采用？
• 代码强制执行了哪些不变量？

**目标输出：**每个 Agent 生成约 10-15k 字的分析，涵盖整个系统。

阶段 3：起草 ARCHITECTURE.md

按照以下结构创建文档：

# 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

详见 references/document-structure.md，了解各部分的详细说明。 可从 assets/architecture-template.md 模板开始编写。

阶段 4：验证

启动 2-3 个审查 Agent，核实内容准确性：

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?

验证清单：

• 所有引用的文件都存在
• 行数估算与实际值的偏差在 20% 以内
• ASCII/Mermaid 图表可正确渲染
• 文档能回答“执行 X 的内容在哪里？”
• 没有沿用旧版本中的过时信息

阶段 5：应用修正

根据审查结果更新文档：

• 修正行数
• 在结构中补充遗漏的文件
• 修正任何不准确的描述
• 更新数量（例如，将“11 个模块”改为“13 个模块”）

质量指南

图表

使用 ASCII 图表表示组件关系：

┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│   Backend   │
└─────────────┘     └─────────────┘

使用 Mermaid 图表表示数据流：

flowchart TB
    A[Input] --> B[Process]
    B --> C[Output]

行数

列出关键文件的大致行数：

• 帮助读者评估复杂度
• 使用 wc -l 验证
• 四舍五入到最接近的 10 或 50

命名实体

通过名称引用文件、类型和模块，不使用链接：

• 正确：“参阅 WorkingMemory.ts，了解不可变内存的实现”
• 错误：“参阅 WorkingMemory”

原因：符号搜索（Cmd+T、osgrep）比容易失效的链接更可靠。

不变量

记录代码绝不会执行的操作：

• “WorkingMemory 绝不会原地修改”
• “API 密钥绝不会到达浏览器”
• “所有数据库查询都使用预处理语句”

目标长度

• 小型项目：200-400 行
• 中型项目：400-700 行
• 大型项目：700-1000 行
• 最大值：约 1200 行（更长时拆分为互相链接的文档）

输出

单个文件：项目根目录下的 ARCHITECTURE.md

也可选择在 CLAUDE.md 或 README.md 中添加对新架构文档的引用。

使用示例

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

资源

• references/matklad-guidelines.md - 含理由说明的规范指南
• references/document-structure.md - 各部分的详细说明
• assets/architecture-template.md - 起始模板