ARCHITECTURE.md

创建 ARCHITECTURE.md

基于 matklad 的 ARCHITECTURE.md 指南，为项目生成高层架构文档。

核心原则

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

文档结构

按以下顺序组织 ARCHITECTURE.md：

1. 鸟瞰概览

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

2. 代码地图（Codemap）

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

规则：

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

示例片段：

## 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. 精简：删除一切可能频繁变动的细节

模板

# Architecture

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

## 概览

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

## Codemap

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

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

## 不变量

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

## 横切关注点

### 错误处理
[策略]

### 测试
[方式]

注意事项

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