ADRArchitecture Decision Record架构决策记录是一份轻量级文档用于捕获关键架构决策及其背后的上下文与理由。它的核心价值不在于“记录了什么”而在于“为什么这样决定”——这恰恰是代码本身无法传达的信息。一、ADR 是什么定义与核心价值架构决策记录是一份描述团队针对软件架构重要方面所做选择的文档。每个 ADR 记录决策本身、做出决策的上下文以及预期后果。ADR 的核心理念可以概括为一句话记录“为什么”而不仅仅是“是什么”。ADR 结构最强大的方面之一是它关注决策的原因而不是团队如何实施决策。了解团队做出决策的原因可以使其他团队成员更容易采纳该决策并防止未来的架构师推翻它。1.1 要解决的核心问题软件团队在架构决策中普遍面临三种反模式反模式表现后果决策瘫痪因害怕做出错误选择而不做决策项目停滞问题累积无理由决策做了决策但不记录理由同一话题被反复讨论团队不理解为何如此记忆蒸发决策未记录在案成员遗忘或新成员不知道已做出的决策ADR 通过将决策、上下文和考虑因素以文档形式固化直接应对这三种反模式。其目标业务成果包括协调当前与未来的团队成员、为项目或产品设定战略方向、避免决策反模式。1.2 ADR 适合记录什么ADR 应覆盖所有影响项目或产品的重要架构决策包括结构如微服务、分层架构等模式选择非功能性需求安全性、高可用性、容错性策略依赖关系组件耦合方式接口API 设计与发布契约构建技术库、框架、工具与流程选择Google Cloud 的建议进一步给出了创建 ADR 的触发条件当遇到技术挑战且没有现成决策依据时当解决方案没有被记录在团队可访问的位置时当存在两个或更多工程选项且需要记录选择理由时。二、ADR 的标准结构一个典型的 ADR 应至少包含三个核心要素上下文Context、决策Decision、后果Consequences。在此基础上实践中常见以下扩展字段标题简短、描述性的名称状态Proposed / Accepted / Deprecated / Superseded日期决策做出时间上下文什么问题促使了这项决策背景和约束是什么决策提议或正在做什么改变后果这项改变使什么变得更容易或更困难Microsoft Azure Well-Architected Framework 还建议包含以下要素考虑过的选项评估了哪些替代方案权衡决策中接受的重要 trade-off置信度有时一个重要决策是在相对较低的置信度下做出的记录这一点对未来的重新评估很有价值状态追踪随着决策数量增长清晰的状态管理尤为重要需要强调的是ADR 应保持简洁、果断、切题且基于事实。避免将决策记录变成设计指南——如果还有更多理由或设计思路提供一个链接作为补充材料但决策本身必须清晰且可独立理解。三、ADR 的生命周期与治理原则3.1 不可变性原则ADR 最关键的一条规则是已接受的 ADR 不可修改。如果新的洞察需要不同的决策团队应提出新的 ADR新 ADR 接受后将取代supersede之前的 ADR并建立链接。这个“只追加”的日志特性保留了思考历程的完整记录使得“方向何时以及为何发生偏移”变得清晰可追溯。3.2 创建与采纳流程ADR 的典型创建流程如下识别决策团队确定某个架构决策需要记录并指定所有者起草 ADR所有者以“Proposed”状态提交 ADR准备接受审查评审与反馈团队成员审查内容所有者批准变更采纳一旦团队接受ADR 进入“Accepted”状态并变为不可变取代如需要新 ADR 取代旧 ADR两者互相链接3.3 治理与所有权ADR 需要明确的所有权和治理规则。一个实践中可参考的优先级顺序是CEO → CTO → CLO → 实施该 ADR 的团队 → 团队中最了解该决策的专家。除非 ADR 中有特别说明其他人没有治理权。每个 ADR 应始终有一个主要联系人、次要联系人和责任团队负责沟通、发布、维护、至少每年一次定期审查以及在必要时最终淘汰。四、案例分析从理论到实践案例一GitFlow 工作流决策AWS 示例AWS 规范性指南提供了一个清晰的 ADR 示例记录了一个打包解决方案的软件开发流程决策标题ABC 应用程序的软件开发生命周期方法状态Accepted日期2022 年 3 月 11 日上下文ABC 应用程序是一种打包的解决方案将使用部署包部署到客户环境中。团队需要一个能够控制功能、修补程序和发布管道的开发过程。决策使用改编版 GitFlow 工作流程。为简单起见不使用时hotfix/*和release/*分支因为 ABC 应用程序将被打包而非部署到特定环境。具体分支策略每个仓库必须有受保护的main分支用于标记发布版本每个仓库必须有受保护的develop分支用于所有进行中的开发工作后果正面适配 GitFlow 流程将帮助控制发布版本管理负面增加了分支管理的复杂度尽管通过省略 hotfix/release 分支已部分缓解这个 ADR 的价值在于它清晰地记录了“为什么选择改编版而非标准 GitFlow”——因为应用程序是打包交付的不需要额外的发布环境测试复杂度。案例二Timee 的 LADR 规模化实践日本公司 Timee 的 Android 团队在 2023 年引入了轻量级架构决策记录LADR。与标准 ADR 不同他们的 LADR 将记录范围扩展到了架构决策之外还包括案件上下文共享在实现前同步“为什么做”和“背景是什么”设计评审在实现开始前达成设计方针共识防止返工决策日志为未来留下“为什么最终是这样实现”的记录关键设计决策不是规格书LADR 只是“当时决策的日志”发布后即使规格变更过去的 LADR 也不更新——修改时创建新的 LADR 并链接将书写门槛降到极低必填项只有“Context上下文”写多少由作者自行决定“与其犹豫不如写一行就提交”规模化结果两年后Android 团队规模扩大了约 3 倍LADR 总数从 18 个增长到约 175 个。对全体成员的问卷调查显示评价项目全体平均10分制资深成员平均新成员平均满意度7.98.77.4效率化7.18.36.4沟通8.29.77.4课题解决效果7.88.77.2学习成长6.58.35.4推荐给其他团队7.28.36.6核心发现满意度平均 7.9 分说明即使在组织扩大后 LADR 仍保持高水平的支持。但新成员在“学习成长”和“效率化”两项上的评分明显低于资深成员5.4 vs 8.36.4 vs 8.3这提示文档存量增加本身并不自动等同于新成员的学习效率提升需要配套的引导机制。案例三微服务团队的 ADR 引入行动研究ECSA 2024 发表的一项行动研究与一家开发微服务系统但缺乏适当架构决策文档的公司合作通过七次访谈识别挑战后引入 ADR并观察了三个月。研究发现的挑战与 ADR 的效果挑战类型ADR 是否有效解决文档文化不足有效知识转移困难有效文档信息优先级不清有效分布式组件文档管理未解决核心结论ADR 显著改善了团队之间的协作。但研究也发现一个关键因素文档存储位置的选择对其实用性有巨大影响。实践者应仔细考虑哪些信息集中存储哪些信息存储在本地仓库中。对于分布式系统ADR 尚未能有效解决跨组件的决策协调问题——这是一个需要进一步研究的开放领域。五、ADR 的扩展实践5.1 决策即代码Fitness Functions一个值得关注的进阶实践是将 ADR 与自动化验证结合。Fitness Function是用编程代码编写的客观自动化检查用于验证决策是否被持续遵守。决策记录记录决策Fitness Function确保决策被执行例如决策我们使用事件溯源来满足审计要求Fitness Function在 CI 服务器上测试所有状态变更必须产生事件这种方式使决策变得可测试、可保障对质量保证、监管流程和治理目标有极大帮助。5.2 工具生态实践中已有多种 ADR 管理工具但大多数优先考虑简单性对结构化元数据、标签、验证以及决策模型的可复用性支持有限工具特点局限adr-toolsCLI轻量级版本控制友好不支持结构化元数据、高级验证adr-logNode.js自动扫描 Markdown ADR 生成目录不支持编辑、查看、可视化adr-viewerPython将 ADR 仓库转为可导航的静态网站不支持编辑和管理功能这些工具的共性局限提示当 ADR 数量增长到数十甚至上百个时导航和维护会变得困难需要更结构化的管理方式。六、实践建议从轻量开始降低门槛。Timee 的经验表明将必填项压缩到“Context”一项允许“写一行也行”可以显著降低心理障碍让 ADR 真正运转起来。ADR 应放在代码库附近。Google Cloud 的建议是将 ADR 存储在与决策相关的代码库附近的 Markdown 文件中以便需要时快速查阅。同时ECSA 研究提醒存储位置的选择对感知实用性有重大影响。不要隐藏后果。无论有意还是无意都应避免隐藏决策的后果。一个没有理由的记录会随着时间失去价值因为当情况变化时利益相关者无法评估决策是否仍然适用。接受低置信度决策的存在。有时一个架构上重要的决策是在相对较低的置信度下做出的。记录这一点对未来的重新评估很有价值。ADR 不能替代设计文档。保持 ADR 简洁和独立将详细的设计思路和扩展论证放在链接的补充材料中。ADR 的本质是对抗架构知识的蒸发。代码告诉你系统“是什么”但只有决策记录能告诉你系统“为什么是这样”。在团队规模扩大、人员流动、系统演进的过程中这个“为什么”往往比“是什么”更有价值。 ADR（Architecture Decision Record，架构决策记录）是一份轻量级文档，用于捕获关键架构决策及其背后的上下文与理由
ADRArchitecture Decision Record架构决策记录是一份轻量级文档用于捕获关键架构决策及其背后的上下文与理由。它的核心价值不在于“记录了什么”而在于“为什么这样决定”——这恰恰是代码本身无法传达的信息。一、ADR 是什么定义与核心价值架构决策记录是一份描述团队针对软件架构重要方面所做选择的文档。每个 ADR 记录决策本身、做出决策的上下文以及预期后果。ADR 的核心理念可以概括为一句话记录“为什么”而不仅仅是“是什么”。ADR 结构最强大的方面之一是它关注决策的原因而不是团队如何实施决策。了解团队做出决策的原因可以使其他团队成员更容易采纳该决策并防止未来的架构师推翻它。1.1 要解决的核心问题软件团队在架构决策中普遍面临三种反模式反模式表现后果决策瘫痪因害怕做出错误选择而不做决策项目停滞问题累积无理由决策做了决策但不记录理由同一话题被反复讨论团队不理解为何如此记忆蒸发决策未记录在案成员遗忘或新成员不知道已做出的决策ADR 通过将决策、上下文和考虑因素以文档形式固化直接应对这三种反模式。其目标业务成果包括协调当前与未来的团队成员、为项目或产品设定战略方向、避免决策反模式。1.2 ADR 适合记录什么ADR 应覆盖所有影响项目或产品的重要架构决策包括结构如微服务、分层架构等模式选择非功能性需求安全性、高可用性、容错性策略依赖关系组件耦合方式接口API 设计与发布契约构建技术库、框架、工具与流程选择Google Cloud 的建议进一步给出了创建 ADR 的触发条件当遇到技术挑战且没有现成决策依据时当解决方案没有被记录在团队可访问的位置时当存在两个或更多工程选项且需要记录选择理由时。二、ADR 的标准结构一个典型的 ADR 应至少包含三个核心要素上下文Context、决策Decision、后果Consequences。在此基础上实践中常见以下扩展字段标题简短、描述性的名称状态Proposed / Accepted / Deprecated / Superseded日期决策做出时间上下文什么问题促使了这项决策背景和约束是什么决策提议或正在做什么改变后果这项改变使什么变得更容易或更困难Microsoft Azure Well-Architected Framework 还建议包含以下要素考虑过的选项评估了哪些替代方案权衡决策中接受的重要 trade-off置信度有时一个重要决策是在相对较低的置信度下做出的记录这一点对未来的重新评估很有价值状态追踪随着决策数量增长清晰的状态管理尤为重要需要强调的是ADR 应保持简洁、果断、切题且基于事实。避免将决策记录变成设计指南——如果还有更多理由或设计思路提供一个链接作为补充材料但决策本身必须清晰且可独立理解。三、ADR 的生命周期与治理原则3.1 不可变性原则ADR 最关键的一条规则是已接受的 ADR 不可修改。如果新的洞察需要不同的决策团队应提出新的 ADR新 ADR 接受后将取代supersede之前的 ADR并建立链接。这个“只追加”的日志特性保留了思考历程的完整记录使得“方向何时以及为何发生偏移”变得清晰可追溯。3.2 创建与采纳流程ADR 的典型创建流程如下识别决策团队确定某个架构决策需要记录并指定所有者起草 ADR所有者以“Proposed”状态提交 ADR准备接受审查评审与反馈团队成员审查内容所有者批准变更采纳一旦团队接受ADR 进入“Accepted”状态并变为不可变取代如需要新 ADR 取代旧 ADR两者互相链接3.3 治理与所有权ADR 需要明确的所有权和治理规则。一个实践中可参考的优先级顺序是CEO → CTO → CLO → 实施该 ADR 的团队 → 团队中最了解该决策的专家。除非 ADR 中有特别说明其他人没有治理权。每个 ADR 应始终有一个主要联系人、次要联系人和责任团队负责沟通、发布、维护、至少每年一次定期审查以及在必要时最终淘汰。四、案例分析从理论到实践案例一GitFlow 工作流决策AWS 示例AWS 规范性指南提供了一个清晰的 ADR 示例记录了一个打包解决方案的软件开发流程决策标题ABC 应用程序的软件开发生命周期方法状态Accepted日期2022 年 3 月 11 日上下文ABC 应用程序是一种打包的解决方案将使用部署包部署到客户环境中。团队需要一个能够控制功能、修补程序和发布管道的开发过程。决策使用改编版 GitFlow 工作流程。为简单起见不使用时hotfix/*和release/*分支因为 ABC 应用程序将被打包而非部署到特定环境。具体分支策略每个仓库必须有受保护的main分支用于标记发布版本每个仓库必须有受保护的develop分支用于所有进行中的开发工作后果正面适配 GitFlow 流程将帮助控制发布版本管理负面增加了分支管理的复杂度尽管通过省略 hotfix/release 分支已部分缓解这个 ADR 的价值在于它清晰地记录了“为什么选择改编版而非标准 GitFlow”——因为应用程序是打包交付的不需要额外的发布环境测试复杂度。案例二Timee 的 LADR 规模化实践日本公司 Timee 的 Android 团队在 2023 年引入了轻量级架构决策记录LADR。与标准 ADR 不同他们的 LADR 将记录范围扩展到了架构决策之外还包括案件上下文共享在实现前同步“为什么做”和“背景是什么”设计评审在实现开始前达成设计方针共识防止返工决策日志为未来留下“为什么最终是这样实现”的记录关键设计决策不是规格书LADR 只是“当时决策的日志”发布后即使规格变更过去的 LADR 也不更新——修改时创建新的 LADR 并链接将书写门槛降到极低必填项只有“Context上下文”写多少由作者自行决定“与其犹豫不如写一行就提交”规模化结果两年后Android 团队规模扩大了约 3 倍LADR 总数从 18 个增长到约 175 个。对全体成员的问卷调查显示评价项目全体平均10分制资深成员平均新成员平均满意度7.98.77.4效率化7.18.36.4沟通8.29.77.4课题解决效果7.88.77.2学习成长6.58.35.4推荐给其他团队7.28.36.6核心发现满意度平均 7.9 分说明即使在组织扩大后 LADR 仍保持高水平的支持。但新成员在“学习成长”和“效率化”两项上的评分明显低于资深成员5.4 vs 8.36.4 vs 8.3这提示文档存量增加本身并不自动等同于新成员的学习效率提升需要配套的引导机制。案例三微服务团队的 ADR 引入行动研究ECSA 2024 发表的一项行动研究与一家开发微服务系统但缺乏适当架构决策文档的公司合作通过七次访谈识别挑战后引入 ADR并观察了三个月。研究发现的挑战与 ADR 的效果挑战类型ADR 是否有效解决文档文化不足有效知识转移困难有效文档信息优先级不清有效分布式组件文档管理未解决核心结论ADR 显著改善了团队之间的协作。但研究也发现一个关键因素文档存储位置的选择对其实用性有巨大影响。实践者应仔细考虑哪些信息集中存储哪些信息存储在本地仓库中。对于分布式系统ADR 尚未能有效解决跨组件的决策协调问题——这是一个需要进一步研究的开放领域。五、ADR 的扩展实践5.1 决策即代码Fitness Functions一个值得关注的进阶实践是将 ADR 与自动化验证结合。Fitness Function是用编程代码编写的客观自动化检查用于验证决策是否被持续遵守。决策记录记录决策Fitness Function确保决策被执行例如决策我们使用事件溯源来满足审计要求Fitness Function在 CI 服务器上测试所有状态变更必须产生事件这种方式使决策变得可测试、可保障对质量保证、监管流程和治理目标有极大帮助。5.2 工具生态实践中已有多种 ADR 管理工具但大多数优先考虑简单性对结构化元数据、标签、验证以及决策模型的可复用性支持有限工具特点局限adr-toolsCLI轻量级版本控制友好不支持结构化元数据、高级验证adr-logNode.js自动扫描 Markdown ADR 生成目录不支持编辑、查看、可视化adr-viewerPython将 ADR 仓库转为可导航的静态网站不支持编辑和管理功能这些工具的共性局限提示当 ADR 数量增长到数十甚至上百个时导航和维护会变得困难需要更结构化的管理方式。六、实践建议从轻量开始降低门槛。Timee 的经验表明将必填项压缩到“Context”一项允许“写一行也行”可以显著降低心理障碍让 ADR 真正运转起来。ADR 应放在代码库附近。Google Cloud 的建议是将 ADR 存储在与决策相关的代码库附近的 Markdown 文件中以便需要时快速查阅。同时ECSA 研究提醒存储位置的选择对感知实用性有重大影响。不要隐藏后果。无论有意还是无意都应避免隐藏决策的后果。一个没有理由的记录会随着时间失去价值因为当情况变化时利益相关者无法评估决策是否仍然适用。接受低置信度决策的存在。有时一个架构上重要的决策是在相对较低的置信度下做出的。记录这一点对未来的重新评估很有价值。ADR 不能替代设计文档。保持 ADR 简洁和独立将详细的设计思路和扩展论证放在链接的补充材料中。ADR 的本质是对抗架构知识的蒸发。代码告诉你系统“是什么”但只有决策记录能告诉你系统“为什么是这样”。在团队规模扩大、人员流动、系统演进的过程中这个“为什么”往往比“是什么”更有价值。