架构决策记录（ADR）规范

ADR（Architecture Decision Record）记录重要架构决策的上下文、决策、后果和被否决的替代方案。它是"为什么选这个方案"的固结快照，防止决策知识随人流失、防止团队重复讨论已否决的方案。

1. 为什么需要 ADR

git 提交历史记录"做了什么"，spec 描述"系统长什么样"，但两者都不回答"为什么选 A 不选 B"。ADR 填补这一层：

ADR 的核心价值不在"补历史"，而在"从今天起停止丢失决策上下文"——记录被否决的方案（反事实），避免后人重新提出已被否决的路径。

2. 何时创建 ADR

2.1 决策触发条件

满足以下任一条件即创建 ADR：

• 决策有长期影响，约束未来开发
• 影响多个组件或模块
• 存在可行的替代方案之间的权衡
• 改变既有架构模式
• 解决重大技术挑战（非普通 bug）

2.2 不创建 ADR 的场景

• bug 修复，不改变架构
• 同结构重构（如重命名、提取函数）
• 配置变更
• 文档更新
• 既有模式内的次要功能
• 临时实验或 workaround

判断标准：如果移除这个决策会让未来的开发者困惑，就写 ADR。

3. ADR 模板

每份 ADR 按以下结构编写。Status 一旦 Accepted 即不可修改内容，变更靠新 ADR 取代。

# ADR-XXX: [决策标题]

**状态**：Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**日期**：YYYY-MM-DD
**决策者**：[人名 | 团队讨论]

## 上下文

### 问题陈述
[解决什么问题？当前情况？]

### 约束
[硬件、内存、安全、兼容性、预算、时间]

## 决策

[清晰、无歧义的选择声明]

### 选择理由
[引用测量和证据，不写形容词]

## 替代方案

### 方案 1：[名称]
**优点**：[具体收益]
**缺点**：[具体代价]
**未选原因**：[基于证据的解释]

### 方案 2：[名称]
（同结构，至少 2 个替代方案）

## 后果

### 正面
- [具体收益，附证据]

### 负面
- [具体代价，为何可接受]

### 风险与缓解
- **风险**：[描述]  **概率**：低/中/高  **缓解**：[具体行动]

## 验证

### 如何验证
[命令、检查项或标准，确认决策被遵循]

### 违反时的后果
[忽略此决策的具体后果]

## 相关决策
- **依赖**：ADR-XXX
- **相关**：ADR-XXX
- **取代**：ADR-XXX（如适用）

4. 防借口表

AI 和人都会找借口跳过文档。遇到以下想法时，按"必须做的"执行：

5. 验证门

ADR 标记为 Accepted 前必须通过以下 4 个门。任一未通过即不得接受。

5.1 完整性门

• 问题陈述说明 WHAT 和 WHY
• 决策是清晰无歧义的声明
• 至少 2 个替代方案，各有优缺点
• 每个否决方案有"未选原因"
• 后果含正面和负面
• 风险有具体缓解

失败条件：任一未勾选，无例外。

5.2 证据门

• 主张有量化支撑，非形容词（"省 5KB RAM" 非"省内存"）
• 约束是验证的，非假设（"ESP8266 有 40KB RAM" 非"内存有限"）
• 权衡尽可能量化（"代码量增加约 10%" 非"略多"）
• 有实现引用（文件路径或代码示例）

失败条件：任一模糊主张无证据。去测量。

5.3 清晰门

• 不熟悉项目的人能理解核心权衡
• 术语首次使用时解释
• 代码示例展示模式，不只描述
• 负面后果诚实，不最小化

失败条件：以从未见过代码库的视角读，有不清楚的就重写。

5.4 一致性门

• 不与既有 Accepted ADR 矛盾
• 取代时旧 ADR 只改状态，不改内容
• 相关 ADR 交叉引用
• 文件名遵循 ADR-XXX-kebab-case-title.md
• 已加入 docs/adr/README.md 索引

失败条件：与既有 ADR 矛盾却未取代，或不在索引中。

6. 命名与索引

6.1 文件命名

格式：ADR-XXX-kebab-case-title.md
位置：docs/adr/

示例：
  ADR-001-choose-database.md
  ADR-002-rest-over-graphql.md
  ADR-003-local-first-architecture.md

规则：

• 编号零填充三位（001、002、003），保证字典序排序正确
• 标题用 kebab-case
• ADR 前缀大写
• 不可复用已废弃或已取代 ADR 的编号
• 编号无间隔（即使有 ADR 被取代，也不跳号）

6.2 索引文件

docs/adr/README.md 是所有 ADR 的导航枢纽，必须包含：

# 架构决策记录

| ADR | 标题 | 状态 | 日期 |
|-----|------|------|------|
| [ADR-001](ADR-001-choose-database.md) | 选择数据库 | Accepted | 2026-07-01 |
| [ADR-002](ADR-002-rest-over-graphql.md) | REST 而非 GraphQL | Superseded by ADR-005 | 2026-07-10 |

新增 ADR 时必须同步更新索引。

7. 工作流

7.1 新决策

1. 查阅 docs/adr/README.md，确认无既有相关 ADR
2. 分配下一个顺序编号
3. 按第 3 节模板编写，状态标 Proposed
4. 通过第 5 节 4 个验证门
5. 用户确认后，状态改 Accepted，记录日期
6. 更新 docs/adr/README.md 索引
7. 在实现该决策的代码处引用 ADR 编号

7.2 取代既有决策

决策变更时新建 ADR，不修改原 ADR 内容：

1. 创建新 ADR，状态标 Proposed
2. 在"相关决策"中引用原 ADR，说明取代理由
3. 原 ADR 状态改为 Superseded by ADR-XXX（只改状态，不改内容）
4. 新 ADR 通过 4 个验证门后标 Accepted
5. 更新 README 索引中两条记录的状态

7.3 已有项目首次引入

对已有项目首次引入 ADR，不必回溯全部历史——只做两件事：

前瞻（主要价值）：从今天起，每个重要架构决策写 ADR。

选择性回溯（仅限活决策）：只对满足全部三个条件的历史决策补 ADR：

• 至今仍主导系统现状
• 经常被新人或团队重新质疑
• 上下文还能 reconstruct（关键当事人或记录还在）

通常一个项目 3-5 个活决策。补写时显式标注"事后补录"，承认它不是当时的快照。已被取代、影响已消散的历史决策不值得补。

8. 代码审查集成

8.1 PR 检查项

• 改动已对照既有 ADR，无违反
• 引入新架构模式时已创建 ADR
• 实现 Accepted ADR 时已更新其状态
• 新增 ADR 已更新 README 索引

8.2 审查评论模式

VIOLATION: "此改动违反 ADR-004（静态缓冲分配）。
           见 docs/adr/ADR-004-static-buffer-allocation.md"

ALIGNED:   "此改动遵循 ADR-002（本地优先架构）。
           良好使用了本地存储接口。"

MISSING:   "此改动引入了新的架构模式（向量搜索）。
           请创建 ADR 记录该决策。"

9. 通用 ADR 分类

ADR 按以下通用分类归档，不绑定具体业务领域：

10. 快速参考

10.1 创建 checklist

• 已分配下一个顺序编号
• 文件名：ADR-XXX-kebab-case-title.md
• 状态、日期、决策者字段已填
• 上下文清晰说明问题
• 至少 2 个替代方案，各有优缺点和未选原因
• 后果含正面和负面
• 风险有缓解
• 代码示例已含
• 相关 ADR 已引用
• 已加入 docs/adr/README.md 索引
• 4 个验证门全通过

10.2 常见错误

• 写"应该用 X"却不解释为什么
• 跳过替代方案（"这是唯一方案"）
• 技术决策无代码示例
• 后果模糊（"会更好"）
• 隐藏负面后果
• 修改 Accepted ADR 而非新建取代
• 不更新 README 索引
• 用术语不定义
• 跳过量化（"更快" vs "减少 68.5%"）

11. 自检要求

输出 ADR 或配置前，逐项检查：

• 决策符合第 2 节触发条件？不是 bug 修复或配置变更？
• 模板字段完整（状态/日期/决策者/上下文/决策/替代方案/后果/验证）？
• 至少 2 个替代方案，各有未选原因？
• 防借口表（第 4 节）的每条都已自查，没有找借口跳过？
• 4 个验证门全通过（完整性/证据/清晰/一致）？
• 主张有量化证据，无形容词？
• 文件名遵循 ADR-XXX-kebab-case-title.md，编号零填充？
• 已更新 docs/adr/README.md 索引？
• 取代既有 ADR 时，原 ADR 只改状态不改内容？