GeoXMind

架构决策记录应保留什么

围绕背景、决策、理由和后果说明架构决策记录的价值，以及何时应替代而不是篡改旧决定。

架构决策记录应保留什么

架构图展示系统现在怎样组织，却很少解释为什么形成这种结构。几个月后，团队可能把经过权衡的选择当成偶然实现，也可能重复讨论已经排除的方案。架构决策记录的价值在于保存当时的情境、选择理由和预期后果，使系统演进有可追溯依据。

记录的是决定而不是会议纪要

一条架构决定应当影响系统结构、质量属性、关键接口或长期演进。变量命名和普通代码重构通常不需要单独记录；数据库边界、身份方案、同步与异步交互、外部平台依赖等决定则可能长期影响多个模块。

记录至少要回答：当时要解决什么问题，受到哪些约束，选择了什么，为什么接受它，以及预计带来哪些正面和负面后果。参与者和日期有助于寻找背景，但不能替代理由。长篇会议过程如果无法还原最终判断，仍然不是有效记录。

备选方案帮助理解取舍

只写“采用方案 A”容易让决定显得武断。列出认真考虑过的备选项和排除原因，可以说明权衡依据。原因要与当前情境相关，例如运维团队无法在交付期限内承担某种复杂度，而不是笼统写“方案 B 不好”。

不需要为了完整而编造大量候选。记录两三个真正影响判断的选择，并说明比较的质量属性、成本和风险即可。如果决定通过实验得出，应链接实验条件和结果；如果受外部约束影响，应记录约束来源。

状态变化不应抹去历史

决定可以处于提议、已接受、已拒绝、已取代或已废弃等状态。新信息出现后，应创建新的决定来取代旧记录，并在两者之间建立关联，而不是把旧内容改写成仿佛从未做过不同选择。这样才能解释旧代码、迁移步骤和遗留数据为何存在。

已取代并不表示旧决定毫无价值。它保留了当时的证据，也可能继续适用于尚未迁移的部分。删除旧记录会让系统在过渡期失去真实描述。

形式服从检索与维护

ADR 常用短文档保存，但具体标题和章节不必固定。关键是每条决定有稳定标识，能够从代码、需求或架构视图链接过去，并能按状态、领域和时间检索。决定过大时难以实施，过小时又造成记录噪声；可以用“一个可以独立被取代的判断”作为拆分尺度。

ISO/IEC/IEEE 42010:2022 的架构描述框架将架构原理和决定置于可表达的架构信息中。项目使用该标准时应依据合法取得的文本确定术语，公开目录只用于确认标准身份和范围。CMU SEI 则强调架构由影响整体结构和行为的重要设计决定组成，这也是 ADR 选择记录对象的依据。

让记录进入实际流程

决定只有在评审、实现和变更时被使用才会保持有效。代码评审可以检查关键实现是否引用对应决定；上线复盘可以判断预期后果是否出现；系统边界或约束变化时，可以搜索受影响的记录。记录不是审批负担，而是降低反复解释和错误回退的维护资产。

资料依据