架构决策记录(ADR)

定义

架构决策记录(Architecture Decision Record,ADR)是一种轻量级文档实践,由 Michael Nygard 于 2011 年在博客中提出:每当做出一个重要的架构决策,就写一篇短文档记录它,并与代码一起纳入版本库。

格式

经典模板包含四部分:上下文(Context,当时面临的约束与备选方案)、决策(Decision,选择了什么)、状态(Status,提议/已接受/已废弃/被取代)、后果(Consequences,决策带来的正负影响)。每条记录编号追加,决策被推翻时不删除旧记录,而是新增一条并标记取代关系,形成决策历史。

应用

ADR 通常以 Markdown 存放在仓库的 docs/adr/ 目录,配套工具有 adr-tools 等;许多开源项目与工程团队用它交接架构知识。

意义

它解决了"新人只看到结果、不知道当年为什么"的问题,成本低而收益持久,被 ThoughtWorks 技术雷达等广泛推荐。