ADR 落地 8 个月，我们把线上事故根因里的"为什么这样设计"问句减了 63%

一、现象与背景：事故复盘会上，最贵的一句话是"我也不知道当初为什么这么写"

2024 年 Q3，我们团队（4 个后端、2 个前端、1 个 SRE、我）负责一个日均 1200 万 PV 的商家后台。一次 P1 事故复盘，我翻出 2023 年 11 月那份原始方案文档，发现里面只写了一句话："库存扣减走同步 RPC。"

复盘会上 SRE 问："为什么没走 MQ 削峰？" 后端 lead 答："……当时好像是为了强一致性，具体谁拍的我忘了。" 我答："我印象里是业务方要求'扣了就要立刻扣成，不能延迟'，但我没写下来。"

那次事故直接损失约 40 万元（订单回滚 + 客诉补偿），但更贵的是：复盘 3 小时里，有 1.5 小时在考古"当初为什么"。我们拉了 2023 年 8 月到 2024 年 11 月共 14 起 P2 及以上事故的复盘文档做统计，发现平均有 38% 的时间花在追溯"设计意图"上，其中 9 起事故的根因链条里，至少有一环是"无人能解释当初为何这样选型"。

这就是我们决定推 ADR（Architecture Decision Record，架构决策记录）的起点。

二、根因：决策是易失品，文档不是

先讲清楚 ADR 到底是什么，以及为什么它能解这个问题。

ADR 本质上是一个只追加、不修改的决策日志。每条记录四段：

Context（背景）：当时面对什么问题、有哪些约束；
Decision（决策）：我们选了什么；
Consequences（后果）：这个决策带来什么好处、什么代价、什么后续动作；
Status（状态）：proposed / accepted / superseded by ADR-xxx。

关键机制是 supersede（取代）而不是 delete（删除）。当新决策推翻旧决策时，旧 ADR 不删，只把状态改成 superseded by ADR-042，新 ADR 里再写清楚为什么推翻。这样决策的时间线就变成了一条不可变链——它把"为什么"从人脑里搬到了文件系统里。

为什么我们之前一直吃亏？因为传统方案文档的默认假设是"文档 = 当前状态"，所以它会被改。一个迭代过去，文档里的"同步 RPC"可能已经被悄悄换成了"异步 + 补偿"，但没人记得是哪个 PR 改的、谁拍的板。而 ADR 的默认假设是"文档 = 历史"，所以它不被改——这正好和 git 的 commit 模型同构。

三、具体做法：一份 60 字节的模板 + 三条纪律

我们没用任何工具，就是仓库里一个 adr/ 目录 + 一份模板。

模板（adr/_template.md）：

# ADR-XXX: <一句话决策，动词开头>

- Status: proposed | accepted | superseded by ADR-XXX
- Date: YYYY-MM-DD
- Deciders: @person1, @person2

## Context
<当时的问题、约束、数据。≤5 行。>

## Decision
<我们选了什么。一句话说清。>

## Consequences
- 好处: ...
- 代价: ...
- 后续: ...

三条纪律（写在 README，写进 onboarding）：

触发式而非例行式。不是每个变更都要写 ADR，只有满足以下任一条件才写：
- 引入了新的技术栈 / 中间件 / 第三方服务；
- 推翻了某个已有 ADR；
- 做了"反直觉"的选型（别人可能会问"为什么不选更主流的"）；
- 涉及跨团队契约（接口、数据格式、SLA）。
8 个月下来我们写了 47 条 ADR，平均每周 1.1 条——没有变成官僚负担，关键是触发条件够窄。
5 分钟写完，超过 10 分钟说明你在写设计文档。ADR 不是 RFC，不画架构图、不写伪代码。我见过最反例的一条 ADR 写了 2000 字，最后被打回重写，砍到 180 字。
PR 合并前检查：如果这次 PR 触发了任一条件，必须附一条 ADR。这一步我们挂在 code review 的 checklist 里，reviewer 有否决权。

检索怎么做？ 我们没上搜索引擎，就是 grep -r "Status: accepted" adr/ + 一个 adr/INDEX.md 手维护的目录（每条 ADR 一行，含标题 + 状态）。47 条的规模，INDEX 手维护成本约 30 秒/条，远低于接工具的成本。规模到 200 条再考虑自动化。

事故复盘时怎么用？ SRE 的复盘模板里加了一行："涉及的设计决策，请列出 ADR 编号。" 这条改动让"考古时间"从平均 1.5 小时降到平均 0.4 小时——因为现在你 grep ADR-023 就能拿到当时的 Context 和 Deciders，不用再 @ 三个前同事问"你还记得吗"。

四、踩过的坑（反直觉部分）

坑 1：第一周写了 12 条 ADR，全是垃圾。 我们一开始把"触发条件"设得太宽，连"选 TypeScript 5.4 而不是 5.3"都写了 ADR。结果 review 时没人看，因为信噪比太低。后来收紧到上面那四条，数量立刻降到合理区间。教训：ADR 的稀缺性就是它的价值，写多了等于没写。

坑 2：有人把 ADR 当"决策审批单"用，开始在里面写"需要谁批准"。 这完全跑偏了。ADR 是事后记录（retrospective），不是事前审批（prospective）。我们明确在 README 里写："ADR 不需要任何人 sign-off，写出来就是 accepted；如果你需要审批，那是 RFC 的事。" 把这两件事混在一起，是 ADR 项目最常见的死法。

坑 3：supersede 链断了两次。 第一次是 ADR-031 推翻了 ADR-018，但 ADR-018 的 Status 忘了改，还停在 accepted。后来有人 grep 到 ADR-018 是 accepted，照着做了，结果和 ADR-031 冲突，花了 2 天排查。第二次类似。我们的修复：在 CI 里加了一条检查——如果某条 ADR 的正文里出现了 superseded by ADR-XXX，就去检查被 supersede 的那条 Status 是否已更新，不一致就红。这条 CI 规则 12 行 bash，救了我们两次。

坑 4：新人在前两周完全不知道 ADR 的存在。 onboarding 文档里加了一行没用。后来改成：新人第一个 PR 必须读一条 ADR 并在 PR 描述里写"我读了 ADR-XXX，它解决了我现在的什么问题"。这条强制动作之后，新人的 ADR 触发率从 0 提到了 80%。

坑 5（最反直觉）：ADR 对"为什么不选 X"的价值，远大于"为什么选 Y"。 我们统计 47 条 ADR 被引用的次数（靠 grep "ADR-" 在所有 PR 描述和事故文档里出现），被引用最多的 5 条里，有 4 条的 Context 里明确写了"我们考虑过 A、B、C，不选的原因是……"。人们记不住你选了什么，但记得住你为什么不选别的——因为下次他们想做那个"别的"时，会先撞上这条 ADR。

五、结论与可复用清单

ADR 不是"更好的文档"，它是给决策加了一层不可变日志。对 5 人以下的团队，它可能 overkill；对 5–20 人、迭代周期 < 2 周、且有过"复盘会上考古设计意图"经历的团队，它几乎是零成本的高杠杆动作。

避坑清单（可直接抄）：

[ ] 模板控制在 5 段以内，正文 ≤ 300 字；超过就是设计文档，该去写 RFC；
[ ] 触发条件写进 README，且越少越好（我们 4 条是上限）；
[ ] ADR ≠ 审批，README 里第一行就写清楚；
[ ] CI 加一条 supersede 一致性检查，12 行 bash 起步；
[ ] 新人第一个 PR 强制读一条 ADR 并写感受；
[ ] Context 里必须写"考虑过什么、为什么不选"，这是被引用率最高的字段；
[ ] 规模 < 200 条时，手维护 INDEX.md，别上工具；
[ ] 复盘模板加一行"列出涉及 ADR 编号"，这是 ROI 最高的一个改动。

数据回收（8 个月）：

ADR 总数 47 条，平均 180 字/条，写一条平均耗时 6.5 分钟；
14 起事故复盘的"考古时间"从平均 1.5h 降到 0.4h（-73%）；
因"无人能解释设计意图"导致的返工，从月均 2.3 次降到 0.4 次（-83%）；
被引用次数 top5 的 ADR，全部包含"为什么不选 X"段落。

一句话总结：你不需要记得每一个决定，你需要的是一个不会忘的、改不掉的、能 grep 到的地方，替你记得。

赞 0 · 收藏 0 · 评论 0 · 浏览 0

暂无评论。