Back to Details

architecture-md-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture.md Builder

ARCHITECTURE.md 构建指南

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.
遵循matklad的标准规范，结合现代AI Agent文档编写模式，创建可用于生产环境的ARCHITECTURE.md文件，作为任意代码库的权威结构地图。

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"
  • 为新代码仓库或已有代码仓库创建架构文档
  • 审计代码库以理解其结构
  • 为开发者和AI Agent编写入职文档
  • 用户提出“记录架构”“创建architecture.md”或“梳理此代码库结构”等需求

Core Principles (matklad's Guidelines)

核心原则（matklad 规范）

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.
标准的ARCHITECTURE.md需遵循以下原则：
  1. 全局概览 - 解决的问题、整体实现思路
  2. 粗粒度代码映射 - 模块及相互关系（类似国家级别视角，而非州级细节）
  3. 命名实体标注 - 重要文件、类型、模块的名称（无需链接，使用符号搜索）
  4. 架构约束规则 - 必须遵守的限制、禁止的实现方式、刻意规避的模式
  5. 分层边界定义 - 系统间的过渡关系
  6. 跨模块关注点 - 涉及多个模块的通用问题
详见
references/matklad-guidelines.md
获取详细说明。

Workflow

工作流程

Phase 1: Research Best Practices (Optional)

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

If unfamiliar with architecture documentation patterns, use Exa search:
bash
undefined
若不熟悉架构文档编写模式，可使用Exa搜索：
bash
undefined

Search for exceptional architecture.md examples

搜索优质的architecture.md示例

python3 ~/.claude/skills/exa-search/scripts/exa_search.py
"architecture.md documentation best practices"
--category github -n 10
python3 ~/.claude/skills/exa-search/scripts/exa_search.py
"architecture.md documentation best practices"
--category github -n 10

Find matklad's original guidelines

查找matklad的原始规范

python3 ~/.claude/skills/exa-search/scripts/exa_research.py
"matklad ARCHITECTURE.md guidelines rust-analyzer"
undefined
python3 ~/.claude/skills/exa-search/scripts/exa_research.py
"matklad ARCHITECTURE.md guidelines rust-analyzer"
undefined

Phase 2: Codebase Exploration

阶段2：代码库探索

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.
启动2-4个并行探索Agent，全面梳理代码库结构：
使用Task工具，设置subagent_type=Explore，针对各主要系统区域进行探索：

1. 核心/引擎 - 入口点、核心抽象、数据结构
2. 传输层/API - HTTP、WebSocket、消息处理
3. 数据库/持久层 - schema、迁移脚本、查询语句
4. 前端/UI - 组件、状态管理、路由
Agent提示语应包含：
  • 核心抽象和类型有哪些？
  • 数据如何在系统中流转？
  • 主要文件及其行数是多少？
  • 系统中持续使用了哪些设计模式？
  • 代码强制执行了哪些约束规则？
目标输出： 每个Agent生成约10-15000字的分析内容，覆盖系统全貌。

Phase 3: Draft ARCHITECTURE.md

阶段3：编写ARCHITECTURE.md草稿

Create the document following this structure:
markdown
undefined
按照以下结构创建文档：
markdown
undefined

Architecture

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]
  • 解决的核心问题是什么？
  • 核心实现范式/思路是什么？
  • 关键设计原则（3-5条）
[展示主要组件的ASCII图表]

High-Level Data Flow

高层级数据流

[Mermaid flowchart showing data flow]
[展示数据流的Mermaid流程图]

Codemap

代码映射

System 1 (
path/
)

系统1（
path/
）

Description, key files with line counts, key abstractions table.
描述、带行数的关键文件、核心抽象表格。

System 2 (
path/
)

系统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

关键文件参考

FileLinesPurpose
.........
文件行数用途
.........

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.
FAQ格式：“我在哪里可以找到X？” → 答案

详见`references/document-structure.md`获取各章节的详细指导。
详见`assets/architecture-template.md`获取初始模板。

Phase 4: Verification

阶段4：验证

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
启动2-3个审核Agent，验证文档准确性：
使用Task工具，设置subagent_type=Explore，进行以下验证：

1. 整体准确性 - 描述是否与实际代码一致？
2. 行数统计 - 是否大致准确？
3. 文件引用 - 所有引用的文件是否存在？
验证检查清单：
  • 所有引用的文件均存在
  • 行数估算与实际值误差在20%以内
  • ASCII/Mermaid图表可正常渲染
  • 文档可回答“实现X的代码在哪里？”这类问题
  • 无来自旧版本的过期信息

Phase 5: Apply Corrections

阶段5：修正优化

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")
根据审核结果更新文档：
  • 修正行数统计
  • 在结构中添加遗漏的文件
  • 修正不准确的描述
  • 更新计数信息（如“11个模块” → “13个模块”）

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]
ASCII图表用于展示组件关系：
┌─────────────┐     ┌─────────────┐
│  Frontend   │────▶│   Backend   │
└─────────────┘     └─────────────┘
Mermaid图表用于展示数据流：
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
为关键文件添加大致行数：
  • 帮助读者评估复杂度
  • 使用
    wc -l
    命令验证
  • 四舍五入到最近的10或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.
直接引用文件、类型和模块的名称，无需添加链接：
  • 推荐：“查看
    WorkingMemory.ts
    了解不可变内存的实现”
  • 不推荐：“查看WorkingMemory”
原因：符号搜索（Cmd+T、osgrep）比容易失效的链接更可靠。

Invariants

约束规则

Document what the code NEVER does:
  • "WorkingMemory never mutates in place"
  • "API keys never reach the browser"
  • "All database queries use prepared statements"
记录代码绝对不会违反的规则：
  • “WorkingMemory 绝不会原地修改数据”
  • “API密钥绝不会传输到浏览器端”
  • “所有数据库查询均使用预编译语句”

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)
  • 小型项目：200-400行
  • 中型项目：400-700行
  • 大型项目：700-1000行
  • 最大限制：约1200行（若超出，需拆分为多个关联文档）

Output

输出结果

Single file: 
ARCHITECTURE.md
in project root
Optionally update 
CLAUDE.md
or 
README.md
with a reference to the new architecture document.
单个文件：项目根目录下的
ARCHITECTURE.md
可选择性更新
CLAUDE.md
或
README.md
，添加对新架构文档的引用。

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
用户：“为这个仓库创建architecture.md”

1. 启动3个探索Agent，分别针对核心层、传输层和前端进行探索
2. 整合探索结果，按照模板生成ARCHITECTURE.md
3. 启动2个审核Agent验证准确性
4. 应用修正内容
5. 提交代码，并可选择性更新CLAUDE.md

Resources

参考资源

  • references/matklad-guidelines.md
    - Canonical guidelines with rationale
  • references/document-structure.md
    - Detailed section guidance
  • assets/architecture-template.md
    - Starting template
  • references/matklad-guidelines.md
    - 带有设计思路的标准规范
  • references/document-structure.md
    - 各章节详细指导
  • assets/architecture-template.md
    - 初始模板