SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场architecture-md-builder

architecture-md-builder

编程与开发

查看项目

更新于 10-16 02:42

技能介绍

用途

Architecture.md Builder 用于创建生产质量的 ARCHITECTURE.md 文件，作为任意代码库的权威地图。它遵循 matklad 的规范指南，并结合了面向现代 AI 代理的文档模式。

适用场景包括：

  • 为新建或已有仓库创建架构文档
  • 审计代码库以理解其结构
  • 为开发者和 AI 代理提供上手文档
  • 用户要求“记录架构”“创建 architecture.md”或“为这个代码库绘制地图”

核心原则（matklad 指南）

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

  • 鸟瞰式概览：说明正在解决的问题与高层方法
  • 粗粒度代码地图：描述模块及其关系（国家级，而非州级）
  • 命名实体：按名称引用重要文件、类型和模块（不使用链接，依赖符号搜索）
  • 架构不变量：约束条件、不做的事情、缺失模式
  • 层级边界：系统之间的转换
  • 横切关注点：跨越多个模块的问题

详细解释见 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 个并行探索代理来全面绘制代码库：

针对每个主要系统区域，使用 Task 工具并设置 subagent_type=Explore：

  1. Core/Engine — 入口点、主要抽象、数据结构
  2. Transport/API — HTTP、WebSocket、消息处理
  3. Database/Persistence — schema、迁移、查询
  4. Frontend/UI — 组件、状态管理、路由

代理提示应询问：

  • 关键抽象和类型有哪些？
  • 数据如何流经该系统？
  • 主要文件及各自行数是多少？
  • 一致使用了哪些模式？
  • 代码强制执行了哪些不变量？

目标输出：每个代理约 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 个审查代理来验证准确性：

使用 Task 工具并设置 subagent_type=Explore 来验证：

  1. 总体准确性 — 描述是否与实际代码相符？
  2. 行数 — 是否大致准确？
  3. 文件引用 — 所有引用的文件是否存在？

验证清单：

  • 所有引用的文件均存在
  • 行数估计与实际相差在 20% 以内
  • ASCII/Mermaid 图表可正确渲染
  • 文档能回答“做 X 的东西在哪里？”
  • 没有来自旧版本的过时信息

阶段 5：应用修正

根据审查发现更新文档：

  • 修正行数
  • 将缺失文件加入结构
  • 修正任何不准确的描述
  • 更新计数（例如“11 modules” → “13 modules”）

质量指南

图表

组件关系使用 ASCII 图表：

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

数据流使用 Mermaid 图表：

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

行数

为关键文件包含大致行数：

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

命名实体

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

  • 好：“See WorkingMemory.ts for the immutable memory implementation”
  • 差：“See WorkingMemory”
  • 原因：符号搜索（Cmd+T、osgrep）比会失效的链接更可靠。

不变量

记录代码从不做的事情：

  • “WorkingMemory never mutates in place”
  • “API keys never reach the browser”
  • “All database queries use prepared statements”

目标长度

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

输出

  • 单一文件：项目根目录下的 ARCHITECTURE.md
  • 可选：更新 CLAUDE.md 或 README.md，添加对新架构文档的引用

使用示例

用户：“Create an architecture.md for this repo”

  1. 启动 3 个探索代理，分别针对 core、transport 和 frontend
  2. 按模板将发现综合为 ARCHITECTURE.md
  3. 启动 2 个审查代理验证准确性
  4. 应用修正
  5. 提交，并可选更新 CLAUDE.md

资源

  • references/matklad-guidelines.md — 带理由的规范指南
  • references/document-structure.md — 详细章节指导
  • assets/architecture-template.md — 起始模板