架构决策记录(ADR) 是一个记录重要架构决策及其上下文和后果的文档。
架构决策(AD) 是解决重要需求的软件设计选择。
架构决策日志(ADL) 是为特定项目（或组织）创建和维护的所有 ADR 的集合。
架构重要需求( ASR) 是对软件系统架构具有可衡量影响的需求。
所有这些都属于架构知识管理（AKM）的主题。
简称：
- AD：架构决策
- ADL：架构决策日志
- ADR : 架构决策记录
- AKM：架构知识管理
- ASR：架构上重要的要求
如何开始使用 ADR？
要开始使用 ADR，请与您的队友讨论这些领域。
决策识别：
- AD的紧急程度和重要性如何？
- 是否必须现在制作，还是可以等到知道更多信息后再制作？
- 个人和集体经验，以及公认的设计方法和实践，都有助于决策识别。
- 理想情况下，维护一个补充产品待办事项列表的决策待办事项列表。
做决定：
- 存在许多决策技术，包括通用技术和特定于软件架构的技术，例如对话映射。
- 群体决策是一个活跃的研究课题。
决定制定和执行：
- AD用于软件设计；因此，它们必须传达给资助、开发和运营它的系统的利益相关者，并被他们接受。
- 架构上明显的编码风格和专注于架构问题和决策的代码审查是两种相关的实践。
- 在软件演进中对软件系统进行现代化改造时，还必须（重新）考虑 AD。
决策共享（可选）：
- 许多广告在项目中重复出现。
- 因此，在采用明确的知识管理策略时，过去决策的经验，无论好坏，都可以成为宝贵的可重用资产。
- 群体决策是一个活跃的研究课题。
决策文件：
- 存在许多用于决策捕获的模板和工具。
- 参见敏捷社区，例如 M. Nygard 的 ADR。
- 查看传统的软件工程和架构设计流程，例如 IBM UMF 以及 CapitalOne 的 Tyree 和 Akerman 建议的表格布局。
如何通过工具开始使用 ADR？
您可以随心所欲地开始使用带有工具的 ADR。
例如：
- 如果您喜欢使用 Google Drive 和在线编辑，那么您可以创建 Google Doc 或 Google Sheet。
- 如果您喜欢使用源代码版本控制，例如 git，那么您可以为每个 ADR 创建一个文件。
- 如果您喜欢使用项目规划工具，例如 Atlassian Jira，那么您可以使用该工具的规划跟踪器。
- 如果您喜欢使用 wiki，例如 MediaWiki，那么您可以创建 ADR wiki。
如何通过 git 开始使用 ADR
如果您喜欢使用 git 版本控制，那么下面是我们喜欢如何开始将 ADR 与 git 一起用于带有源代码的典型软件项目。
为 ADR 文件创建目录：
$ mkdir adr |
对于每个 ADR，创建一个文本文件，例如database.txt：
$ vi database.txt |
在 ADR 中写下您想要的任何内容。请参阅此存储库中的模板以获取想法。
将 ADR 提交到您的 git 存储库。
编写好的 ADR 的建议
良好 ADR 的特征：
- 理性：解释做特定广告的原因。这可以包括上下文（见下文）、各种潜在选择的优缺点、功能比较、成本/收益讨论等。
- 具体：每个 ADR 应该是一个 AD，而不是多个 AD。
- 时间戳：确定 ADR 中每个项目的写入时间。这对于可能随时间变化的方面尤其重要，例如成本、时间表、缩放等。
- 不可变：不要更改 ADR 中的现有信息。相反，通过添加新信息来修改 ADR，或通过创建新 ADR 来取代 ADR。
ADR 中良好“上下文”部分的特征：
- 解释您的组织的情况和业务优先级。
- 包括基于您团队的社交和技能构成的基本原理和考虑因素。
- 包括相关的利弊，并以符合您的需求和目标的方式描述它们。
ADR 中良好“后果”部分的特征：
- 解释做出决定后会发生什么。这可以包括效果、结果、输出、跟进等。
- 包括有关任何后续 ADR 的信息。一个 ADR 触发对更多 ADR 的需求是相对常见的，例如当一个 ADR 做出重大的总体选择时，这反过来又会产生对更多较小决策的需求。
- 包括任何事后审查流程。团队通常会在一个月后审查每个 ADR，将 ADR 信息与实际实践中发生的情况进行比较，以便学习和成长。
新的 ADR 可能会取代之前的 ADR：
- 当一个 AD 替换或使以前的 ADR 无效时，应该创建一个新的 ADR
ADR 示例模板
我们在网上收集的 ADR 示例模板：
- Michael Nygard 的 ADR 模板（简单且流行）
- Jeff Tyree 和 Art Akerman 的 ADR 模板（更复杂）
- 亚历山大模式的 ADR 模板（简单的上下文细节）
- 商业案例的 ADR 模板（更多面向 MBA，包含成本、SWOT 和更多意见）
- ADR 模板 MADR（更多 Markdown）
- 使用 Planguage 的 ADR 模板（更注重质量保证）
团队合作建议
如果您正在考虑与您的团队一起使用决策记录，那么这里有一些我们通过与许多团队合作学到的建议。
你有机会通过一起讨论“为什么”而不是强制要求“什么”来领导你的队友。例如，决策记录是团队更聪明地思考和更好地沟通的一种方式；如果决策记录只是事后强制的文书工作要求，那么它们就没有价值。
一些团队更喜欢名称“decisions”而不是缩写“ADRs”。当一些团队使用目录名称“decisions”时，就好像一个灯泡亮了，团队开始将更多信息放入目录中，例如供应商决策、计划决策、调度决策等。所有这些类型的信息可以使用相同的模板。我们假设人们用单词（“decisions”）比缩写词（“ADRs”）学得更快，当“record”这个词被删除时，人们更有动力去写正在进行的文档，还有一些开发人员和一些经理不喜欢“建筑”这个词。
理论上，不变性是理想的。在实践中，可变性对我们的团队来说效果更好。我们在现有的 ADR 中插入新信息，并带有日期戳，并说明该信息是在决定之后到达的。这种方法导致我们都可以更新的“动态文档”。典型的更新是当我们通过新队友、新产品或我们使用的实际结果或事后第三方更改（例如供应商能力、定价计划、许可协议等）获得信息时。