ADR 是什么：为什么技术决策需要被记录
摘要
ADR 是 Architecture Decision Record，通常指架构决策记录。它用简短文档记录一次重要技术决策的背景、选项、取舍和结果。ADR 的价值不是写文档本身，而是保存上下文，让未来的人知道当初为什么这样选。
技术决策会被遗忘
系统里有很多看起来奇怪的设计。
为什么不用另一个框架？为什么这个字段不能删？为什么发布流程分两步？为什么某个模块没有抽象？
如果没有记录，后来的人只能猜。
猜测会带来误解。
他们可能以为前人随便做，或者重复讨论已经比较过的方案。
ADR 要解决的，就是技术决策上下文丢失的问题。
ADR 记录什么
一份 ADR 不需要很长。
它通常记录几件事：
- 背景：当时遇到什么问题。
- 约束：时间、人力、系统、风险有哪些限制。
- 选项：比较过哪些方案。
- 决策：最后选择什么。
- 后果：接受了什么代价，未来什么时候重新评估。
这些内容足够让后来的人理解决策环境。
ADR 不是论文，而是给未来维护者看的路标。
记录取舍比记录结论更重要
很多文档只写结论。
“我们选择方案 A。”
但真正有价值的是：为什么不是 B？为什么不是 C？当时我们接受了什么缺点？
技术决策很少是完美答案。
它通常是在约束下选择一个更合适的方案。
如果只记录结论，未来的人会看不见取舍。
记录取舍，才是 ADR 的核心价值。
ADR 适合记录哪些决策
不是每个小改动都需要 ADR。
适合记录的，通常是影响较大、未来难以逆转、涉及团队共识或长期维护的决策。
比如技术栈选择、数据存储方案、认证方式、发布流程、重要接口设计、模块边界。
如果一个决策未来有人可能问“为什么这样做”，它就值得记录。
ADR 的数量不必多，但关键决策要留下。
ADR 要保持简短
ADR 太长，就没人愿意写，也没人愿意读。
好的 ADR 应该简短、具体、可检索。
一页能说清，就不要写十页。
重点不是完整描述整个系统，而是记录这一次决策。
如果需要更多背景，可以链接到设计文档、需求文档或代码。
ADR 是决策索引，不是所有文档的替代品。
ADR 会帮助团队学习
时间久了，ADR 会形成团队的决策历史。
你能看到团队如何处理风险，如何权衡速度和质量，如何在不同阶段选择不同方案。
这对新人理解系统很有帮助。
也能帮助团队复盘：哪些决策后来证明有效，哪些决策需要调整。
ADR 不只是记录过去，也帮助未来做更好的决定。
结论
ADR 是什么？它是架构决策记录，用来保存重要技术决策的背景、选项、取舍和后果。
技术系统会变化，人员会流动，记忆会消失。
ADR 让后来的人不必重新猜测过去，也让团队能从自己的决策历史中学习。
评论
发表评论