architecture-md

ARCHITECTURE.md 生成器

生成高质量的 ARCHITECTURE.md 文件，帮助新手快速了解代码库的整体结构。 本项目基于 matklad 的文章：最大的贡献者瓶颈不在于编写代码，而在于弄清楚应该在哪里修改代码。ARCHITECTURE.md 正是为了弥合这一差距。

核心原则

1. 简短且稳定 —— 只描述不太可能频繁变化的内容。不必与代码保持同步，每年回顾几次即可。
2. 先从全局着手 —— 从要解决的问题开始，而非解决方案。
3. 用代码地图代替散文 —— 针对每个模块，回答“执行 X 的代码在哪里？”和“这个模块做什么？”
4. 只命名，不链接 —— 列出重要文件、模块和类型的名称。不要添加超链接（链接会过时），并鼓励通过符号搜索定位代码。
5. 不变量弥足珍贵 —— 明确指出哪些内容是刻意缺失的。重要不变量往往体现在缺失之处，阅读代码无法推断出来。
6. 标明边界 —— 层与层之间的 API 边界会约束其背后的所有实现方案。通过随机阅读代码来寻找边界并不容易。
7. 最后介绍横切关注点 —— 完成代码地图后，再介绍那些无处不在、又无处可寻的内容（错误处理、测试、配置）。

工作流

步骤 1：探索代码库

使用 tree、glob 和读取工具了解项目：

• 阅读 README、package.json/Cargo.toml/pyproject.toml，了解项目的用途
• 运行 tree -L 2 -d（或类似命令）查看目录结构
• 找出入口点（主文件、index 文件、bin 目录）
• 阅读模块边界处的关键文件，了解各层结构

步骤 2：识别架构

梳理以下内容：

• 要解决的问题 —— 这个项目做什么？输入和输出是什么？
• 粗粒度模块 —— 每个顶层目录/包负责什么？
• 数据流 —— 数据如何在系统中流动？输入 -> ??? -> 输出
• API 边界 —— 哪些模块是公共接口，哪些是内部实现？
• 架构不变量 —— 结构强制执行了哪些规则？哪些内容是刻意缺失的？
• 横切关注点 —— 错误处理、测试策略、配置、可观测性

步骤 3：编写 ARCHITECTURE.md

遵循下面的模板。大多数项目的文档总长度应控制在约 300 行以内。

模板

# Architecture

[One paragraph: what this project does at the highest level. What problem it solves.]

## Bird's Eye View

[How data flows through the system at the coarsest level.
Input -> Processing stages -> Output.
Keep this to 1-3 paragraphs.]

## Code Map

[Brief intro: "This section describes the high-level structure of the codebase.
Pay attention to **Boundary** and **Invariant** callouts."]

### `path/to/module-a/`

[What this module does in 1-3 sentences. Key types: `ImportantType`, `AnotherType`.]

**Boundary:** [If this is an API boundary, say so and what it means.]

**Invariant:** [What's deliberately absent or enforced. E.g., "This module never does I/O"
or "Nothing here depends on the HTTP layer."]

### `path/to/module-b/`

[Repeat for each significant module.]

### `path/to/module-c/`

[...]

## Cross-Cutting Concerns

### Error Handling

[How errors are handled across the codebase. Is it Result-based? Exceptions?
Do errors propagate or get caught at boundaries?]

### Testing

[Testing strategy. Where do tests live? What kinds of tests exist?
What are the important test boundaries?]

### [Other concerns as applicable]

[Configuration, observability/logging, code generation, build system, etc.
Only include sections that are genuinely cross-cutting.]

规则

应包含的内容

• 目录/模块的用途（各用 1-3 句话）
• 重要类型、trait、接口和函数的名称（方便符号搜索）
• 各层之间的 API 边界
• 架构不变量，尤其是刻意缺失的内容
• 系统层面的数据流
• 影响多个模块的横切关注点

应省略的内容

• 各个模块的实现细节（应写在内联文档中）
• 指向特定文件或代码行的链接（会过时）
• 随常规 PR 变化的内容
• 穷尽的 API 文档（属于 rustdoc/typedoc/javadoc 的范畴）
• 设置说明（应写在 README 中）
• 贡献指南（应写在 CONTRIBUTING.md 中）

风格规则

• 在代码地图中使用带反引号路径的 ### \path/to/module/`` 标题
• 使用 Boundary: 和 Invariant: 前缀标注（加粗标签，不使用块引用）
• 每个模块的描述控制在 1-3 句话
• 类型名称使用反引号：“Key types: FooBar, BazQux”
• 使用现在时和主动语态
• 优先使用具体表述：“解析 CLI 参数”，而不是“处理输入”

质量检查清单

完成前，请确认：

• 新手能否仅凭本文档找到“负责执行 X 的内容”？
• 是否清楚标明了 API 边界？
• 是否指出了架构不变量（尤其是不存在的内容）？
• 每个章节是否足够稳定，能在 6 个月内无需更新？
• 是否直接写出了重要类型/模块的名称（而非仅提供链接）？
• 是否在代码地图之前提供了整体概览？
• 是否涵盖了横切关注点？
• 代码地图的顺序是否与数据流或依赖方向一致？
• 是否控制在约 300 行以内？（越短，越有可能被阅读和维护）

参考示例

请参阅 references/example.md，其中提供了一个完整的 ARCHITECTURE.md 示例，展示了上述所有模式，并以一个假想的 TypeScript 项目为例。