Architecture Decision Record (ADR)

记录重要技术决策、上下文、取舍和后果的轻量文档形式。

#concept #growing #dev #architecture-decision-record

[!info] related notes

所属 MOC: Matt Pocock Skills MOC

建模语境: Ubiquitous Language

并列概念: Policy as Code

关系笔记: Matt Pocock Skills 的工程闭环

一句话定义

用短文档记录某个重要架构决策为什么做、替代方案是什么、以后会带来什么后果。

系统会记得代码，但不会自动记得“当时为什么这样做”。ADR 的作用就是把设计理由显式化，降低知识只留在人脑中的风险。

决定使用 monorepo 时，ADR 可以记录目标、拒绝的替代方案和会增加的维护成本，方便以后重新评估。

记录当时的上下文、候选方案、所选方案和已知后果，并标明是提议、已接受还是已被替代。这里的决策状态属于 ADR 正文约定，不是知识笔记 status 标签。

条件变化后用后续决策替代并互相引用，保留原决策为何曾经合理的证据。不要静默把历史选择改写成当前方案，也不要把 proposed 当作已经实施或部署。