摘要如果你做出了一项会显著影响工程师开发软件方式的技术决策就应该写一份架构决策记录。架构决策记录Architecture Decision RecordADR是一种用于记录重要技术决策的文档。它通常会说明决策背景、可选方案、最终选择以及采用该方案可能带来的影响和后果。对于研发团队来说ADR 的价值在于保留关键技术上下文帮助团队理解“为什么这样设计”并减少重复讨论、知识流失和架构分歧。在海外某大型流媒体平台一些团队会使用 ADR 来记录重要技术决策。其中一个负责为内容创作者提供工具和数据能力的团队会用 ADR 记录与系统设计和工程最佳实践相关的决定。这些决策通常会先通过征求意见稿Request for CommentsRFC或工程会议进行讨论。团队达成共识后再使用 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 并不需要很长。一份有效的架构决策记录通常只需要回答几个核心问题我们面临什么问题当时有哪些可选方案最终选择了什么为什么作出这一选择这项决定会带来哪些积极或消极后果对于影响较小的决策几段文字可能就足够了。在实践中团队可以借助PingCodeWiki 统一沉淀 ADR、RFC、架构评审结论和相关技术文档并将这些内容与需求、开发任务、缺陷和版本关联起来。这样既能保留决策背景也能让团队在后续开发、系统交接和技术复盘中快速找到完整上下文。ADR 的价值不在于篇幅而在于它能否让未来的读者快速理解当时的背景和判断。RFC 与 ADR 有什么区别RFC 和 ADR 经常被混淆但它们解决的问题并不相同。RFC 更适合用来推动讨论。它通常会列出问题背景、多个候选方案、开放问题和需要征求的意见。ADR 则用于记录已经作出的决定。可以简单地理解为RFC 回答“我们应该怎么做”ADR 回答“我们最终决定怎么做以及为什么。”并不是每一份 ADR 都必须先有 RFC。如果某项决定非常明确或者团队已经通过会议、实验和代码评审形成共识那么可以直接编写 ADR。同样并不是每一份 RFC 最终都会形成 ADR。有些 RFC 可能被否决、搁置或者没有形成明确结论。如何判断一项技术决策是否值得记录如果你仍然不确定是否应该写 ADR可以问自己以下几个问题这项决定会影响多少工程师它会持续影响多长时间它是否会改变团队开发、测试、部署或维护软件的方式未来是否可能有人再次提出同样的问题如果不记录新成员是否很难理解当前做法如果这项决定出错回退或迁移成本是否较高它是否会成为多个团队需要遵循的标准如果其中多个问题的答案是“是”那么这项决定通常值得写入 ADR。结论什么时候应该编写架构决策记录架构决策记录的目的并不是增加文档负担而是帮助团队保存最重要的技术上下文。ADR 可以帮助新成员更快理解系统降低所有权移交成本促进跨团队协作并减少重复讨论和相互冲突的技术方案。你不需要等到一项决策足够宏大才开始记录。无论是补充已经形成但从未写下来的隐性标准记录重大架构变更还是固化一个可能长期影响团队的小决定ADR 都能发挥价值。判断标准其实很简单如果你作出了一项会影响工程师未来如何开发软件的技术决策就应该写一份 ADR。