ADR 简介

• 标题：此次设计决策的标题，一般是简单概括性的决策任务描述，比如“EDR-1：用户状态设计”

• 元数据：一般包括编写时间、修改时间、版本信息、文件编号、决策者等等，能够体现 ADR 文档的可追溯性以及版本化特性，直观的展示此次设计决策的基本信息，也是展示项目演进历程的窗口，通过这些信息能够

• 上下文/背景：需要记录此次技术设计决策背后的背景和上下文信息，以便其他人可以理解决策的场景和原因，甚至能体会决策者所作出的权衡取舍，更加容易理解这个 ADR 文档

• 决策过程：这部分是 ADR 文档的核心，需要包含整个决策的过程以及最后形成的结论，一般可以从考虑的选项以及他们的对比（对比包括优缺点、风险和其他重要考虑因素）、做出决策的具体理由和权衡（为什么选择了某个选项而不是其他选项）

• 状态：记录此次决策的状态，也可以视为此文档的状态，我们需要遵守特定的流程来更改此状态，即状态的迁移需要审核和评审。状态可以根据实际情况来定，推荐的选项为：proposed 提议，accepted通过/生效，deprecated废除 等

• 影响：记录此次设计决策实施之后会带来的后果和影响，包括它将如何影响系统的其他部分、成本、效率等方面，这样读者也能对设计的影响范围形成初步的概念，在后续其他的设计中有的放矢，降低互相冲突对立的设计产生的概率

• ADR 保证设计决策的稳定性和质量：形成 ADR 的过程就是决策者梳理上下文和后续影响，做出符合当前系统设计的决策的过程，ADR 从提议到通过的过程是团队内部评审架构设计以及对此次设计达成共识的过程，所以实施 ADR 能让团队的架构设计决策在流程上更规范，确保团队设计质量的稳定性，而且还能使团队的设计决策更加优秀，设计的结果更接近团队认知的上限，换句话说，ADR 可以保证系统架构决策的质量和透明度。

• ADR 可以成为团队沟通和提升的新工具：ADR 有助于团队在未来理解和维护系统架构，并为新成员提供了一个快速了解系统架构的方式，还可以促进知识共享和学习，它为团队成员提供了一个交流和反思的机会，从而促进知识和经验的分享和学习。通过分享决策的上下文、原因和结果，团队成员可以从彼此的经验中学习，提高自己的技能和认识。

实施 ADR 的行动方案

• 确定 ADR 的结构和格式：指定ADR的结构和格式可以确保所有团队成员都能够理解和遵守ADR的内容和规范，是实施 ADR 的前提。推荐：使用 Markdown 格式，结构至少包含上文的主要内容部分，制定团队专用的 ADR 模版来保持统一

• 确定 ADR 的记录范围：ADR应该仅记录关键的、长期的和重要的架构决策，对于较小的或者不重要的决策，可以使用其他方式进行记录

• 选择合适的编写及管理工具：ADR 需要版本化、轻量化，应该以简洁、清晰的方式编写，避免使用专业术语或者过于复杂的句子结构，这可以确保其他人能够轻松理解ADR的内容，同时 ADR 最好放在对团队来说触手可及的地方，有些团队将 ADR 放在代码仓库中一起维护，这也不失为一种行之有效的方案

• 确定 ADR 责任人：每个设计决策都需指定一个责任人，由他来负责 ADR 的起草和维护，在不同的场景下，发起评审会议，邀请干系人参与评审，并维护最终结果。同时，他也需要识别 ADR 内容和实际开发中的匹配度，确保系统是按照 ADR 开发的，或者 ADR 能够及时根据开发过程中设计的变化而变

• 评审 ADR 的有效性：每个责任人都要在特定事件发生时，或者固定的间隔之后，评审此时 ADR 的有效性，及时维护到最新的状态，确保内容的时效性。一般来说，特定的事件包括系统架构发生重大变化、安全漏洞或其他重大问题解决之后和上下文依赖部分发生巨大变化等

• 确保ADR的安全性：ADR可能包含敏感信息，因此应该确保ADR的安全性，这可以通过限制ADR的访问权限或者使用加密方式进行存储来实现，需要根据实际情况来制定相应的安全策略，不可忽视