核心问题

一份可用的 ADR 应该长什么样？

真实场景

团队想写 ADR，但一写就变成长篇技术方案。最后没人愿意维护。

ADR 不应该又大又全，它应该短、准、能回答为什么。

常见误区

坏判断是：

ADR 要把所有技术细节都写进去。

技术细节可以放方案文档，ADR 只抓决策骨架。

工程视角

推荐结构：

标题：
状态：提议中 / 已接受 / 已废弃
背景：
约束：
选项：
决策：
代价：
后续动作：
重评条件：

每一项都服务于未来理解。

PM 可以怎么做

PM 可以负责把复杂讨论压缩成清晰结构：

  • 背景不要写流水账。
  • 选项不要只写赢家。
  • 代价要写得诚实。
  • 后续动作要能追踪。

Atlas Action

给团队建立一个 ADR 模板，限制在一到两页内。太长就拆成技术方案，ADR 只保留决策。

小结

好 ADR 不是大文档，而是决策快照。

它让未来的人知道：当时我们看见了什么，放弃了什么，选择承担什么。