如何开始使用 ADR

要开始使用 ADR，请与你的团队成员就以下几个方面进行讨论。

决策识别：

• 该架构决策的紧迫性和重要性如何？
• 是必须立即做出，还是可以等了解更多信息后再做？
• 个人经验与团队经验，以及公认的设计方法和实践，都有助于决策识别。
• 理想情况下，应维护一份与产品待办事项清单相辅相成的决策待办事项清单。

决策制定：

• 存在多种决策制定技术，既有通用方法，也有软件架构特有的方法，例如对话映射（dialogue mapping）。
• 群体决策是一个活跃的研究课题。

决策实施与执行：

• 架构决策应用于软件设计，因此必须传达给资助、开发和运营该系统的利益相关者，并获得他们的认可。
• 架构清晰的编码风格，以及关注架构问题和决策的代码审查，是两种相关的实践。
• 在软件演进过程中对系统进行现代化改造时，也需要（重新）考虑架构决策。

决策分享（可选）：

• 许多架构决策在不同项目中反复出现。
• 因此，在采用明确的知识管理策略时，过往决策的经验（无论好坏）都是宝贵的可重用资产。

决策记录：

• 有许多用于记录决策的模板和工具。
• 参见敏捷社区，例如 M. Nygard 的 ADR。
• 参见传统软件工程和架构设计流程，例如 IBM UMF 以及 CapitalOne 的 Tyree 和 Akerman 提出的表格布局。

更多信息：

• 以上步骤改编自维基百科中关于架构决策的词条。

</需要翻译的内容>

如何借助工具开始使用 ADR

你可以按照自己偏好的方式，借助各类工具开始使用 ADR。

例如：

• 如果你偏好使用 Google Drive 和在线协作编辑，那么可以创建一个 Google 文档或 Google 表格。

• 如果你偏好使用源代码版本控制工具（如 git），那么可以为每一条 ADR 创建一个独立文件。

• 如果你偏好使用项目规划工具（如 Atlassian Jira），那么可以利用该工具的规划追踪功能。

• 如果你偏好使用 Wiki 系统（如 MediaWiki），那么可以创建一个 ADR Wiki 页面。

如何结合 git 使用 ADR

如果你偏好使用 git 版本控制，以下是我们针对一个典型软件项目，结合 git 使用 ADR 的推荐做法。

首先，为 ADR 文件创建一个专属目录：

ADR 的文件命名约定

如果你选择使用纯文本文件来编写 ADR，那么你可能需要制定一套自己的 ADR 文件命名约定。

我们倾向于采用一种具有特定格式的文件命名约定。

示例：

• choose-database.md

• format-timestamps.md

• manage-passwords.md

• handle-exceptions.md

我们的文件命名约定如下：

• 名称采用现在时态的祈使动词短语。这有助于提高可读性，并与我们的提交信息格式保持一致。

• 名称使用小写字母和连字符（与本仓库保持一致）。这是在可读性和系统易用性之间取得的平衡。

• 扩展名为 markdown。这便于轻松进行格式排版。

撰写优秀 ADR 的建议

一份优秀 ADR 的特征：

• 合理性：解释做出特定架构决策的理由。这可以包括背景（见下文）、各潜在选项的利弊、功能对比、成本/收益讨论等内容。

• 具体性：每份 ADR 应当只针对一项架构决策，而非多项。

• 时间戳：标明 ADR 中每项内容的撰写时间。这对于成本、时间表、扩展等可能随时间变化的方面尤为重要。

• 不可变性：不要修改 ADR 中已有的信息。相反，应通过添加新信息来修订 ADR，或通过创建新 ADR 来取代原有 ADR。

ADR 中优秀“背景”部分的特征：

• 说明你所在组织的状况和业务优先级。

• 包含基于团队人员构成和技能组合的合理性论证与考量。

• 列出相关的利弊，并以符合你需求和目标的方式加以描述。

ADR 中优秀“影响”部分的特征：

• 说明做出决策后会产生什么结果。这可以包括效果、成果、产出、后续行动等内容。

• 包含有关后续 ADR 的信息。一份 ADR 触发更多 ADR 的需求是相当常见的，例如当一份 ADR 做出一个宏观的总体性选择，进而又产生更多较小决策的需求时。

• 包含事后复盘流程。团队通常会在一个月后对每份 ADR 进行回顾，将 ADR 中的信息与实际实践中的情况进行比较，以促进学习和成长。

新的 ADR 可以取代先前的 ADR：

• 当某项架构决策取代或使先前的 ADR 失效时，应当创建一份新的 ADR。

ADR 的团队协作建议

如果你正在考虑与团队一起使用决策记录，以下是我们与众多团队合作后总结出的一些建议。

你有机会引领团队成员，通过共同探讨“为什么”而非强制规定“是什么”来实现这一点。例如，决策记录是帮助团队更明智地思考和更好地沟通的一种方式；如果决策记录只是事后被迫完成的文书工作，那么它们便失去了价值。

有些团队明显更偏好“决策”这一名称，而不是“ADR”这个缩写。当一些团队使用“决策”作为目录名称时，仿佛一盏灯被点亮了，团队开始向该目录中放入更多信息，例如供应商决策、规划决策、进度安排决策等。所有这些类型的信息都可以使用相同的模板。我们推测，人们通过完整词汇（“决策”）学习的速度比缩写（“ADR”）更快，而且当去掉“记录”一词后，人们更有动力去撰写进行中的文档，此外，一些开发人员和管理人员并不喜欢“架构”这个词。

理论上，不可变性是理想状态。但在实践中，可变性对我们的团队效果更好。我们将新信息插入到现有的 ADR 中，附上日期标记，并注明该信息是在决策之后补充的。这种方法催生了一份“活文档”，我们所有人都可以更新它。典型的更新时机包括：我们获得了新队友带来的信息、出现了新的产品方案、我们的使用产生了实际效果，或者第三方发生了事后变化，如供应商能力、定价方案、许可协议等。

</需要翻译的内容>

ADR 的团队协作问题

谁可以创建 ADR？

需要考虑以下几个方面：具体人员、特定角色、特定团队或特定部门；同时也要考虑是否存在可以委托创建 ADR 的人员、角色、团队或部门，即由他们提出需求，而由其他人来撰写。

示例回答：我们组织中任何阅读过架构决策记录 README 页面的人员都可以提出 ADR，即该人员可以开始撰写，并与团队分享。

什么情况下应当发起 ADR？

需要考虑以下几个方面：你所在组织的团队工作方式、软件系统架构、跨团队协调、长期可维护性、外部接口、你希望惠及的对象等。

示例回答：当我们希望未来的开发者能够理解我们当下所做事情的“为什么”时，我们就会创建 ADR。

什么情况下不应当发起 ADR？

需要考虑以下几个方面：与架构无关的决策，或属于微小决策（如低风险、自包含或仅涉及单个开发者），或已被其他文档完全覆盖（如标准、政策或文档），或属于临时性方案（如临时变通方案、概念验证或实验）。

示例回答：当决策在范围、时间、风险和成本上都非常有限，或已被其他文档覆盖时，我们会选择跳过 ADR。

ADR 的生命周期是怎样的？

需要考虑以下几个方面：创建流程、研究流程、决策流程、实施流程以及终止流程。同时需要考虑如何随时间跟踪 ADR 的生命周期，例如如何将 ADR 从一个状态推进到下一个状态，以及如何向利益相关者传达这一进展。

示例回答：我们希望 ADR 具有五个生命周期阶段：发起 → 研究 → 评估 → 实施 → 维护 → 终止。

ADR 生命周期各阶段的评判标准是什么？

需要考虑以下几个方面：ADR 的验收标准，即你如何判断它已足够完善，可以从一个生命周期阶段进入下一个阶段？问题是否被清晰地阐述？是否已考虑过各种备选方案？权衡取舍是否已得到充分理解并记录在案？所有相关背景信息是否都已就位？所有相关利益相关者是否都已参与？所有反馈是否都已被采纳？

示例回答：我们希望当活跃团队已完成以下工作后，由利益相关者对 ADR 进行投票：1）完成研究工作，2）完成评估工作，3）将 ADR 提案发布给利益相关者，附带征求意见的请求和一周期限，4）所有利益相关者的意见均已被采纳和处理。

哪些角色和职责与 ADR 相关？

可以考虑诸如提案人、研究员、评估者、审查者、审批者、维护者等角色。职责方面可包括与利益相关者沟通、确保预期目标达成、在网站或内网上发布信息，以及定期审查工作，尤其是在发生相关变更时。

示例回答：我们希望每份 ADR 始终有一个主要联系人、一个次要联系人以及一个负责团队；他们负责沟通、发布、维护、每年至少一次的定期审查，以及在必要时最终退役该 ADR。

治理如何与 ADR 互动？

可考虑组织的运作方式、法律或人力资源等方面的特殊合规要求，以及如何处理共识、冲突与升级之间的关系。是否存在某些领域、人员或团队在 ADR 上拥有比其他方更大的影响力，例如能够批准、投票或否决该 ADR？

示例回答：ADR 的治理优先级顺序为：首席执行官、首席技术官、首席法务官、实施该 ADR 的团队、团队中最熟悉该 ADR 的专家。除非在 ADR 中另有说明，否则其他任何人都不具有治理权。

哪些原则与 ADR 相关？

可考虑组织的运作方式，包括快速推进与稳健推进之间的权衡、决策共识与决策冲突之间的取舍、风险偏好与安全偏好之间的平衡、公开讨论与私下讨论之间的选择等。

示例回答：我们遵循以下领导力原则：偏向行动、持异议但承诺执行、对于易于逆转且易于隔离的决策，70% 的把握已足够，以及公开的运作方式，但组织保密协议中规定的机密信息除外。

ADR 的后续概念

Arc42 以务实的方式回答了三个问题，并可根据你的具体需求进行定制。关于你的架构，你应该文档化/传达哪些内容？你应该如何文档化/传达？Arc42 包含架构决策记录，以及关于目标、约束、上下文、质量、风险等方面的指导。

C4模型 是一种易于学习、对开发者友好的软件架构图示方法。C4 是一组分层图示，用于描述上下文、容器、组件、代码，以及用于系统景观、动态和部署的辅助图示。

架构图示、视图与视角

架构图示被称为“架构视图”。

“架构视图”是“架构视角”的一个实例。

“架构视角”针对具有特定关注点的特定受众。

架构视角示例、视图示例和图示示例：

• 业务能力

• 高层业务流程图

• 价值流

• 映射到应用组件的软件功能

• C4模型 上下文图（目标状态 / 当前状态）

• C4模型 容器图（目标状态 / 当前状态）

• 实体关系图（ERD），用于将数据实体映射到应用组件

• 时序图，用于描述系统内部及集成场景中的功能流程

• 业务流程模型与标记法（BPMN）图示，用于描述跨应用组件的数据流

• 业务流程模型与标记法（BPMN）图示，用于描述业务流程/用户场景

• 身份与访问管理（IAM）图示

• 基于角色的访问控制（RBAC）图示，展示每个应用组件的角色

• 基于属性的访问控制（ABAC）图示，展示每个应用组件的属性

• 隐私图示

相关图示：

• 用例图向管理层/客户展示用例，这先于需求，而需求又先于软件架构。

• 部署图展示软件组件所部署到的物理硬件/计算机。

• 数据流图展示数据如何流经系统并发生转换。

• 时序图用于展示诸如 HTTP 之类的协议在时间轴上是如何工作的。

• 活动图描绘软件系统所执行活动的流程，例如 NPC 人工智能。

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.