ADR 是什么？什么时候应该编写架构决策记录？

摘要：如果你做出了一项会显著影响工程师开发软件方式的技术决策，就应该写一份架构决策记录。

架构决策记录（Architecture Decision Record，ADR）是一种用于记录重要技术决策的文档。它通常会说明决策背景、可选方案、最终选择，以及采用该方案可能带来的影响和后果。

对于研发团队来说，ADR 的价值在于保留关键技术上下文，帮助团队理解“为什么这样设计”，并减少重复讨论、知识流失和架构分歧。

在海外某大型流媒体平台，一些团队会使用 ADR 来记录重要技术决策。其中，一个负责为内容创作者提供工具和数据能力的团队，会用 ADR 记录与系统设计和工程最佳实践相关的决定。

这些决策通常会先通过征求意见稿（Request for Comments，RFC）或工程会议进行讨论。团队达成共识后，再使用 ADR 将最终结论固定下来。

使用架构决策记录有哪些好处？

自从开始使用 ADR 后，团队发现它带来了许多明显收益。

帮助新成员快速了解技术决策背景

未来加入团队的成员，可以通过阅读历史 ADR，快速了解过去做过哪些技术决策、为什么这样决定，以及这些决策产生了什么影响。

例如，2019 年，某创作者业务团队的 Web 工程师决定采用 React Hooks。

这项决定最初在一次双周 Web 工程会议中提出，随后在应用程序的一小部分中进行了试验。经过验证后，团队正式决定不再新增类组件，而是统一采用函数组件。

如果没有 ADR，这类决策往往只能依靠口头传递。随着时间推移和人员变化，新成员很难理解团队为什么采用当前方式，也可能重新引入已经被放弃的模式。

ADR 可以帮助新成员迅速补齐上下文，减少重复讨论和无效试错。

降低系统所有权移交成本

在敏捷开发模式下，组织会根据用户需求和业务变化不断调整团队结构。

组织架构发生变化时，某个系统的所有权也可能从一个团队转移到另一个团队。过去，这类移交经常伴随着大量背景信息和历史知识的丢失。新团队需要花费很长时间重新理解系统，从而影响交付效率。

引入 ADR 后，这一问题得到了明显缓解。

系统的新负责人只需要阅读相关 ADR，就能快速了解系统架构经历了哪些变化、每次变化的原因是什么，以及当时为什么选择当前方案。

ADR 无法替代完整的系统文档，但它能够保留一类极其重要的信息：

系统为什么会变成今天这样。

帮助不同团队统一工程实践

ADR 还可以帮助不同团队在技术标准和工程最佳实践上达成一致。

这种一致性能够带来多方面收益，包括：

• 减少重复劳动；
• 提高代码和方案的复用程度；
• 避免同一问题出现多个相互竞争的解决方案；
• 减少平台团队或基础设施团队需要支持的技术方案数量。

例如，一个地区的工程团队可以阅读、引用并采用由另一个地区团队编写的 React Hooks ADR，而不必重新进行同样的技术讨论和验证。

ADR 不只是单个团队的历史记录，也可以成为跨团队传播工程实践的重要载体。

什么时候应该写 ADR？

你可能会想：

ADR 听起来很有价值。它既能帮助团队形成决策，也能为未来的团队成员和现在的自己保留决策记录。但究竟应该在什么时候写一份 ADR？

原则上，每当团队作出一项具有较大影响的技术决策时，都应该编写 ADR。

当然，不同团队对“较大影响”的定义可能不同，因此每个团队都需要先对判断标准达成一致。

下面列出几种常见场景，以及判断是否应该编写 ADR 的思路。

场景一：补充记录已经形成的架构决策

有时候，一项决策早已作出，或者某种隐性的技术标准已经自然形成，但它从未被正式记录下来。

因此，并不是所有人都知道这项决策的存在，尤其是后来加入团队的新成员。

这就像那个经典问题：

如果森林里有一棵树倒下，但周围没有人听见，它是否真的发出了声音？

同样，如果团队已经作出某项决策，却从未留下记录，它还能算作一项真正的团队标准吗？

识别这类未记录决策的一种常见方式，是观察代码评审中出现的分歧。

例如，当某位工程师引入一种与现有做法相冲突的代码模式、框架或第三方库时，评审人员可能会说：“我们团队并不这样做。”

如果这项约定从未被记录下来，那么问题并不完全在提交者，而在于团队一直依赖隐性知识。

此时，可以使用下面的判断思路：

• 我是否遇到了一个问题？是。
• 是否已经存在一个公认的解决方案？是。
• 这个解决方案是否已经被记录？没有。

那么，就应该补写一份 ADR。

通过补充 ADR，团队可以把隐性规则转变为显性标准，避免以后继续依赖口头传递。

场景二：提出一项重大架构变更

在系统生命周期中，团队经常需要作出一些会显著影响系统设计、维护方式和扩展能力的决策。

例如，随着业务需求不断变化，团队可能需要对 API 进行重大调整，而这项调整又要求使用方进行迁移。

为了就方案和实现方式达成一致，团队通常会进行系统设计评审、架构评审，或者撰写 RFC。

但当这些讨论完成后，还需要回答一个问题：

最终决定应该如何被正式记录下来？

可以使用下面的判断思路：

• 我是否遇到了一个问题？是。
• 是否存在一个显而易见、没有争议的完美方案？没有。
• 我是否已经提出了一个候选解决方案？是。
• 这项变更是否影响较大？是。

那么，应该先编写一份 RFC。

RFC 的作用，是帮助团队讨论不同方案、收集反馈，并推动形成共识。

接下来再判断：

• RFC 是否已经形成最终结论？是。

那么，就应该编写一份 ADR。

RFC 记录的是讨论过程和备选方案，ADR 记录的则是最终决策及其后果。两者的作用不同，但可以相互衔接。

场景三：记录影响较小但可能长期存在的决定

在日常开发中，团队也会作出很多影响较小、甚至看起来微不足道的决定。

单独看，每项决定似乎都不值得专门记录。但如果大量小决定长期处于未记录状态，往往会产生隐性成本。

这种成本可能表现为：

• 其他工程师重新研究同一个问题；
• 不同团队采用功能相似的第三方库；
• 代码库中出现多种互相竞争的模式；
• 长期积累后，需要投入大量精力进行统一迁移。

虽然未记录决策的成本很难精确衡量，但它确实会不断积累。

好消息是，记录这类决定并不需要花费太多时间。ADR 可以非常简短，不必写成一篇长篇设计文档。

可以使用下面的判断思路：

• 我是否遇到了一个问题？是。
• 是否存在一个显而易见的完美方案？没有。
• 我是否已经找到一个可行方案？是。
• 这项变更是否影响很大？没有。

那么，仍然可以写一份 ADR。

即使决定本身不大，只要它可能成为团队未来反复遵循的技术标准，就值得留下记录。

ADR 应该写多长？

很多团队迟迟不愿采用 ADR，是因为他们担心这会增加大量文档工作。

但 ADR 并不需要很长。

一份有效的架构决策记录，通常只需要回答几个核心问题：

• 我们面临什么问题？
• 当时有哪些可选方案？
• 最终选择了什么？
• 为什么作出这一选择？
• 这项决定会带来哪些积极或消极后果？

对于影响较小的决策，几段文字可能就足够了。

在实践中，团队可以借助 PingCode Wiki 统一沉淀 ADR、RFC、架构评审结论和相关技术文档，并将这些内容与需求、开发任务、缺陷和版本关联起来。这样既能保留决策背景，也能让团队在后续开发、系统交接和技术复盘中快速找到完整上下文。

ADR 的价值不在于篇幅，而在于它能否让未来的读者快速理解当时的背景和判断。

RFC 与 ADR 有什么区别？

RFC 和 ADR 经常被混淆，但它们解决的问题并不相同。

RFC 更适合用来推动讨论。它通常会列出问题背景、多个候选方案、开放问题和需要征求的意见。

ADR 则用于记录已经作出的决定。

可以简单地理解为：

• RFC 回答：“我们应该怎么做？”
• ADR 回答：“我们最终决定怎么做，以及为什么。”

并不是每一份 ADR 都必须先有 RFC。

如果某项决定非常明确，或者团队已经通过会议、实验和代码评审形成共识，那么可以直接编写 ADR。

同样，并不是每一份 RFC 最终都会形成 ADR。有些 RFC 可能被否决、搁置，或者没有形成明确结论。

如何判断一项技术决策是否值得记录？

如果你仍然不确定是否应该写 ADR，可以问自己以下几个问题：

• 这项决定会影响多少工程师？
• 它会持续影响多长时间？
• 它是否会改变团队开发、测试、部署或维护软件的方式？
• 未来是否可能有人再次提出同样的问题？
• 如果不记录，新成员是否很难理解当前做法？
• 如果这项决定出错，回退或迁移成本是否较高？
• 它是否会成为多个团队需要遵循的标准？

如果其中多个问题的答案是“是”，那么这项决定通常值得写入 ADR。

结论：什么时候应该编写架构决策记录？

架构决策记录的目的，并不是增加文档负担，而是帮助团队保存最重要的技术上下文。

ADR 可以帮助新成员更快理解系统，降低所有权移交成本，促进跨团队协作，并减少重复讨论和相互冲突的技术方案。

你不需要等到一项决策足够宏大，才开始记录。

无论是补充已经形成但从未写下来的隐性标准，记录重大架构变更，还是固化一个可能长期影响团队的小决定，ADR 都能发挥价值。

判断标准其实很简单：

如果你作出了一项会影响工程师未来如何开发软件的技术决策，就应该写一份 ADR。