# Create Architecture Doc

> 为项目创建 ARCHITECTURE.md 文档，描述高层架构、代码地图与架构不变量。当用户要求创建架构文档、ARCHITECTURE.md，或询问如何描述项目结构给新贡献者时使用。

- Skill: `zhang-siyang/create-architecture-doc` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhang-siyang/create-architecture-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhang-siyang/create-architecture-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Zhang-Siyang (https://skillmd.com/u/zhang-siyang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhang-siyang/create-architecture-doc

---


# 创建 ARCHITECTURE.md

基于 [matklad 的 ARCHITECTURE.md 指南](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html)，为项目生成高层架构文档。

## 核心原则

- **只写不常变的内容**：不要试图与代码同步，每年回顾两三次即可
- **保持简短**：每个经常贡献的人都要读它，越短越不容易因代码变化而失效
- **回答两个问题**：「做 X 的代码在哪？」和「我正在看的这段代码是做什么的？」

## 文档结构

按以下顺序组织 ARCHITECTURE.md：

### 1. 鸟瞰概览

用 1-3 段简要描述项目要解决的问题。不是使用说明，而是让读者理解「为什么存在这个项目」以及核心领域概念。

### 2. 代码地图（Codemap）

描述粗粒度模块及其相互关系。这是文档的核心部分。

规则：
- **命名**重要的文件、模块、类型，让读者用符号搜索找到它们
- **不要直接链接**代码（链接会过时），改为鼓励读者使用符号搜索
- 描述模块「做什么」，不要描述「怎么做」（实现细节放到内联文档或单独文档）
- 像国家地图，不是各省地图集
- 反思结构：代码地图中想放在一起的东西，在 `tree .` 输出中是否相邻？

示例片段：

```markdown
## Codemap

### `src/parsing/`
将源码文本转为具体语法树（CST）。解析器是手写递归下降，不使用生成器。
关键类型：`Parser`、`SyntaxNode`、`SyntaxToken`。

### `src/hir/`
高级中间表示。从 CST 降级得来，是大多数语义分析的基础。
关键类型：`Module`、`Function`、`TypeRef`。

### `src/server/`
LSP 服务器实现。将 IDE 功能暴露给编辑器。
入口：`main_loop`。
```

### 3. 架构不变量

显式列出架构约束，尤其是「不做某事」的约定——这些从代码中很难发现。

示例：
- "model 层不依赖 view 层"
- "所有数据库访问只通过 repository 层，handler 不直接操作数据库"
- "不使用全局可变状态"

### 4. 层与系统边界

指出层之间、系统之间的边界。边界隐含了其背后实现的信息，并约束所有可能的实现。但仅靠随机阅读代码很难发现边界——好的边界「测度为零」。

### 5. 横切关注点

在代码地图之后，单独列一节说明跨模块的共性事项：
- 错误处理策略
- 日志 / 可观测性
- 测试方式
- 配置管理
- 并发模型

## 工作流

1. **阅读项目**：浏览 `tree .`、`README`、`go.mod` / `package.json` 等，理解项目结构
2. **识别模块**：找出粗粒度模块（目录级别），理解各自职责
3. **梳理关系**：确定模块间的依赖与调用方向
4. **发现不变量**：找出架构约束，特别是「不做某事」的规则
5. **撰写文档**：按上述结构生成 ARCHITECTURE.md
6. **精简**：删除一切可能频繁变动的细节

## 模板

```markdown
# Architecture

本文档描述 [项目名] 的高层架构。

## 概览

[1-3 段：项目解决什么问题，核心领域概念]

## Codemap

### `dir/`
[该模块做什么，关键类型/入口]

### `dir2/`
[该模块做什么，关键类型/入口]

## 不变量

- [架构约束 1]
- [架构约束 2]

## 横切关注点

### 错误处理
[策略]

### 测试
[方式]
```

## 注意事项

- 放在仓库根目录，与 README 和 CONTRIBUTING 并列
- 不超过 1-2 页（屏幕页），越短越好
- 避免描述实现细节，那是代码注释的工作
- 不要加指向具体代码行的链接，用名称让读者自己搜索