ADR 格式
架构决策记录的标准 Markdown 结构。
为什么
在 Slack 线程和会议纪要里做的决策一周后就消失了。ADR 是一个简短的 Markdown 文件，能扛过团队换人、重组和仓库迁移。固定格式迫使作者明确写出上下文、决策和后果，而这正是半年后人们真正需要的部分。没有固定格式，每条 ADR 都变成自由散文，有用的字段（状态、被替代者）要么不一致要么缺失。
何时使用
任何有架构影响的决策——运行时、数据存储、框架、安全边界。耗时 15-30 分钟。纯外观或可逆选择可跳过。
如何做
1. 创建 docs/adr/NNNN-短标题.md（NNNN = 零填充序号） - 序号单调递增；即使 ADR 被否决也不要复用编号 2. 按顺序填写标准字段： # NNNN. 标题 - Status: Proposed | Accepted | Deprecated | Superseded by [NNNN] - Date: YYYY-MM-DD - Context: 有哪些作用力、哪些约束 - Decision: 我们决定了什么（一句话，加粗） - Consequences: 正面、负面、中性影响 3. Context 至少 3 段；这是未来的你读得最多的字段 - 写出你考虑过的备选方案及各自被否决的原因 4. 先设 Status=Proposed，请求评审，签字后改为 Accepted - 永远不要删除 Accepted 的 ADR；用新 ADR 替代它并回链 5. 在实现该决策的同一个 PR 里提交 ADR
示例
# 0007. 主存储用 PostgreSQL 而非 MongoDB - Status: Accepted - Date: 2026-03-14 - Context: 计费模块需要事务和 join。MongoDB 没有多文档 ACID（除非用拖慢性能的变通）。 团队已在用 Postgres 做分析。考虑过：DynamoDB（否决——厂商锁定+无 join）、 MySQL（否决——JSON 支持更弱）。 - Decision: **采用 PostgreSQL 16 作为主事务存储。** - Consequences: + 完整 ACID、成熟工具、少运维一个存储。 - 必须预先定义 schema；不如文档存储灵活。 ~ 中性：读副本成本与 Mongo 副本集相当。
常见问题
- ⚠只写 Decision 不写 Context——未来读者看到"做了什么"却看不到"为什么"，无法判断决策是否仍成立。
- ⚠ADR 永远停在 Proposed——团队从不真正拍板，仓库里堆着半成品决策，没有事实来源。
- ⚠直接改旧的 Accepted ADR 而非替代它——你摧毁了架构演进的历史审计链。
最佳实践
- ✓在实现它的 PR 和 README 架构章节里都链接到 ADR——找不到的 ADR 只是个文件。
- ✓在专门的 30 分钟架构同步会上评审 ADR，而非埋在没人读上下文的通用站会里。
- ✓替代决策时加一行 'Supersedes'，让工具能自动渲染决策图。