架构决策记录保存选择时的上下文与后果

架构会随着大量选择逐步形成：采用何种边界、数据由谁拥有、怎样满足恢复目标、哪些风险被接受。代码只显示最终结构，通常无法说明当时有哪些约束和备选。架构决策记录把这些理由与后果保留下来，让未来修改建立在可追溯证据上。

ADR 不追求记录所有讨论，也不是审批表。它应聚焦对结构、质量属性和长期演进有显著影响、且未来可能被重新评估的决定。

先界定什么值得成为架构决策

选择变量名或调整局部实现通常不需要 ADR。改变模块依赖、数据所有权、部署拓扑、外部协议、安全边界和关键质量属性的决定，更值得独立记录。

判断标准可以是影响范围、替换成本、跨团队约束和风险。一项选择若会限制未来方案，或失败后恢复代价高，就应在实施前或形成共识时记录。

记录太少会失去上下文，记录太多会把重要决定淹没。团队应定期校准范围，并允许轻量记录，而不是把文档长度当作严谨程度。

首先是上下文：要解决什么问题，相关业务和技术约束是什么。其次是决策驱动因素，例如可用性、延迟、合规、团队能力和时间窗口。没有驱动因素，后人无法判断条件是否已经变化。

然后列出认真考虑的备选及关键权衡。无需复制所有会议过程，但应说明为什么没有选择看似合理的其他方案。正式决定要具体到可执行边界，避免“采用高可用架构”这类无法验证的表述。

最后记录后果，包括预期收益、接受的风险、实施工作和后续触发条件。只写优点会把 ADR 变成事后宣传，失去风险治理价值。

ADR 可以经历提议、已接受、已拒绝、已弃用和已替代等状态。新的决定改变旧选择时，应新增记录并链接“替代”关系，而不是把旧文件内容改成今天的理由。

历史记录解释旧代码为何存在，也支持事故复盘和迁移规划。删除被替代 ADR 会让版本历史难以直接阅读，还可能掩盖曾经有效的约束。

小的勘误可以修改，但实质性理由变化应形成新决定。文件状态、日期和关联 ID要清晰，避免读者把旧方案当成当前规范。

“为了性能”范围太宽。更可验证的写法是说明在何种负载和环境下，哪个响应或资源指标需要达到什么目标。安全、可修改性和恢复能力同样可以用具体场景描述。

SEI 的架构分析强调风险、敏感点和权衡点。ADR 可以链接压测、威胁模型、原型和评审结论，使理由不是纯意见。证据不必在文件中完整复制，但链接必须长期可访问。

若证据仍未知，应明确假设和验证计划。一个带待验证假设的决定，比用确定语气隐藏不确定性更可靠。

记录被接受后，要链接实际变更、接口契约和迁移计划。否则决策可能停留在文档，代码采用另一套方案。代码评审可以检查相关 ADR 是否落实关键边界。

运行数据也可能否定原假设。若故障率、成本或变更速度偏离预期，应重新评估决定并新增后续 ADR。架构治理不是在实施时结束，而是持续验证后果。

反过来，ADR 不应复制随代码频繁变化的配置细节。文件保存稳定的理由和边界，动态参数留在配置与运行手册中，并通过链接关联。

ADR 可与代码同库，按稳定编号或 slug 命名，使用 Markdown 便于评审和版本控制。集中索引列出标题、状态、领域和关联服务，避免只能依靠全文搜索。

跨仓库决定需要一个权威位置，其他仓库使用链接，不应复制多份后各自修改。链接目标要有访问控制和长期地址，人员变动后仍可读取。

模板应简短且允许按问题扩展。强制填写大量无关字段会导致空话；完全无结构又难以比较。上下文、决定、备选、后果、状态和关联证据通常足够构成骨架。

评审者应检查问题是否真实、约束是否完整、备选是否公平、风险是否可接受和回滚是否存在。意见要针对假设和证据，不把个人偏好包装成架构原则。

重大 Level 3 变化需要单独审批和更强证据，小范围可回滚改动则可采用轻量流程。决策风险决定审核强度，而不是所有 ADR 都走同一会议。

参与者和异议可以记录，但 ADR 不是会议纪要。最终要清楚谁拥有决定、何时复审，以及哪些条件会触发替代。

项目结束后补写的 ADR容易用结果倒推理由，遗漏当时的不确定性。最好在选择形成时写初稿，在验证后补充结果。无法及时记录时，也应标明这是历史重建而非原始证据。

另一种失效是文件永远保持“已接受”，即使系统已迁移。发布或架构盘点应检查 ADR 状态和链接。孤立文档越多，使用者越不信任整个目录。

ADR 的价值不在数量，而在让关键选择可解释、可检验、可替代。它保存的是决策时的上下文与承诺，使架构演进不必依赖个人记忆，也不会把旧约束误认为永恒原则。

Carnegie Mellon Software Engineering Institute：Software Architecture，https://www.sei.cmu.edu/software-architecture/
Carnegie Mellon Software Engineering Institute：Architecture Tradeoff Analysis Method Collection，https://www.sei.cmu.edu/library/architecture-tradeoff-analysis-method-collection/