纸质记录的力量：架构决策记录 (ADRs)
Source: Dev.to
知识工作的最终产出——软件架构与工程——是 决策。
无论以何种形式呈现，记录关键决策背后的思考过程都是必不可少的，原因包括：
- 在决策达成 前、期间 和 后 保持清晰。
- 防止事后偏见。
- 帮助未来的自己以及他人了解作出决策时的环境。
在本文中，我将分享我对 架构决策记录（ADRs） 的学习以及它们在软件和数据项目中的应用。
什么是 ADR？
架构决策记录 本质上是项目生命周期中 重要 架构决策的书面痕迹。从现在起，我将简略称它们为 ADRs。
在我作为软件和数据工程师的多年工作中，我 很少 遇到 ADR。文档在我参与的项目中呈现出多种形式：被废弃的 Notion 页面、图表、内容稀疏的文本文件，或——有时——根本没有文档。当决策发生变化时，ADR 通过引入 Proposed（提议）、Accepted（接受）、Rejected（拒绝）和 Superseded（被取代）等明确状态，帮助追踪这些变化。
为什么你应该在意？
架构决策是组织所做的最昂贵的选择之一。它们会影响：
- 添加新功能的难易程度。
- 系统在面对不断变化的业务需求时的弹性和灵活性。
以严谨的方式审视并为这些决策提供依据——并在规定的时间范围内完成——变得至关重要。此外，ADR 框架可以适用于许多其他领域和决策过程。
如何判断需要记录什么？
并非每个决策都需要留下书面记录；行政开销会变成噩梦。Michael Nygard 将 架构重要 的决策描述为影响以下方面的决策：
- 结构和构建技术。
- 非功能特性（例如，可扩展性、安全性）。
- 依赖关系和接口。
自问：
这个决策是否可逆，逆转的成本是多少？
Olaf Zimmermann 在他的博客文章中对决策制定标准作了详细阐述。
轻量级 ADR：设置方法
我会第一个提出 行政开销 的问题——要在文档习惯上获得初始动力本身就已经很困难。轻量级 ADR 提供了一种格式，在不显著影响工作流的情况下实现文档的好处。还有一些工具可以帮助管理 ADR，例如 adr-tools GitHub 仓库。
在我的项目中，我只需添加一个 /adr 文件夹，每个决策对应一个 Markdown 文档，例如：
/adr
│ ADR 001 - Postgres for Operational Database.md
│ ADR 002 - Microservice Architecture for Orders Module.md
│ …我把图表直接放在该文件夹中，并将所有内容提交到源码控制，确保文档的版本与代码保持一致。当决策发生变化时，我 不编辑 旧的 ADR；我会创建一个新的 ADR，将旧的标记为 已取代，并链接到新的文档。
ADR 的生命周期
这些文档的生命周期会因团队动态和利益相关者的职责而有所不同。始终会有一个主要联系人（个人或团队）负责沟通、发布和维护 ADR——即将 ADR 从一个状态移动到下一个状态。
典型状态图（改编自原始来源）：
Proposed → Accepted → Superseded
↘
Rejected- Proposed – 起草一个新决策。
- Accepted – 决策获批，成为当前的架构。
- Rejected – 提案被拒绝；ADR 仍保留以供历史参考。
- Superseded – 后续的 ADR 替代了此条；旧的 ADR 被归档但仍可访问。
通过遵循这一简单工作流，团队可以保持清晰、可检索的历史记录，了解为何做出架构选择以及这些选择是如何随时间演变的。
祝文档写作愉快！
结论
文档是一种习惯，尤其在团队采用的工具和技术不断变化的环境中显得尤为重要。虽然本文未涉及文档框架的许多组织层面的考量，但仅仅是填充和推广 ADR 所需的严谨性，就足以帮助避免因文档不足和决策孤岛而产生的一些陷阱。
ADR 所存放的位置与编写它们同样重要；这会影响它们的版本管理和维护方式，在我看来，这也是技术 文档 面临的最大挑战。