架构决策记录（ADR）

• 理解 ADR 五要素各自的内容与写作原则
• 理解"不可变"与"状态流转"的关系，真正可变的只有状态字段
• 理解 ADR 与普通笔记/文档的本质区别

ADR 的五部分作用如下：标题应该是一句话说明决策（动词式，如"使用 PostgreSQL 作为主存储"），方便在索引中快速识别；状态表示该决策当前所处的生命周期阶段（如 Accepted、Deprecated）；上下文描述触发决策的背景、约束、问题与可选方案，是决策的"为什么"；决策记录最终选定的方案及理由，并说明为什么其他方案被否决；后果记录该决策带来的正面影响与负面影响，包括后续要承担的技术债。ADR 不可变的根本原因是它是一份"历史审计记录"：决策做出时的背景、备选方案和权衡是当时的事实，事后修改会破坏决策的可追溯性，让后人无法还原当时的决策语境。因此，对决策的任何改变不作为"修改原 ADR"处理，而是新建一条 ADR（记录新决策）并把旧 ADR 的状态标记为 Superseded 或 Deprecated，通过链接指向新 ADR。

ADR 的价值在于"记录历史"而非"记录当前状态"。如果允许原地修改，ADR 就退化为普通文档，无法回答"当时为什么这么选、当时有哪些备选"这类问题。把决策演化建模为"新增记录 + 状态迁移"是事件溯源思想的体现，符合架构决策的审计与复盘需求。

• 区分"决策记录"与"实现方案书"的定位
• 判断决策粒度的标准（影响范围、成本、可逆性）
• 防止 ADR 变形的策略

判断标准在于决策是否具有"不可逆性、高成本、影响范围广"的特征。ADR 适合记录"已经做出、且难以低成本撤销"的架构决策，例如选型、模块划分、数据流方向；而设计文档（RFC）适合在决策做出之前，对方案进行详细设计、展开多个备选方案的对比与评审。粒度上，ADR 只记录"结论 + 关键理由 + 后果"，一份 ADR 通常控制在 1-2 页；设计文档则包含详细的技术方案、时序图、接口草案、实施计划。避免 ADR 膨胀的关键是将 ADR 视为"决策的索引/摘要"，把详细设计内容放在链接的设计文档或 Wiki 中，ADR 只保留指针与结论。同时约定：ADR 不写实现细节、不写代码、不写逐步操作说明，这些属于设计文档或代码本身。

ADR 是"决策管理"的载体，设计文档是"方案设计"的载体。混淆两者会导致 ADR 无人阅读（太长）、或设计文档没有决策记录（无从追溯）。通过"ADR 摘要 + 设计文档链接"的分离，既保持 ADR 的轻量，又保留完整的设计上下文。

• 掌握 ADR 常见状态及其含义
• 理解状态流转的触发条件与规则
• 掌握 ADR 之间 Superseded 链接的写法

常见状态包括：Proposed（草案，待评审）、Accepted（已评审通过，作为当前决策生效）、Deprecated（已不再推荐，但尚未有替代或仍在过渡期）、Superseded（已被新 ADR 取代）。流转规则：Proposed 经评审通过变为 Accepted；Accepted 被新决策取代时变为 Superseded，并填入指向新 ADR 的链接字段；若决策被否定但无替代方案，则标记为 Deprecated。被取代的 ADR 在"状态"或"后果"部分写明 Superseded by ADR-XXXX，新 ADR 反向写明 Supersedes ADR-XXXX，形成双向链接。这样任何读者都能沿决策链追踪"为什么从 A 变成了 B"，并了解历史决策的完整脉络。

状态流转使 ADR 既能反映"当前事实"（通过 Accepted 状态），又不破坏"历史事实"（通过 Superseded 保持原内容）。双向链接是决策可追溯性的关键，让后人能沿着决策演化链回溯。状态机应显式定义，避免随意跳转导致混乱。

• 理解 ADR 采纳的阻力与动机
• 降低门槛、即时反馈的推广手段
• 识别与纠正形式化的苍白 ADR

推广 ADR 的关键是"让它自然地成为决策流程的一部分"而非额外负担。具体策略：第一，从"有争议的决策"起步，只在真正需要讨论（如多方案选型、影响较大）的地方要求 ADR，而不是事事都写；第二，把 ADR 模板压缩到极简（一句话标题 + 一个理由 + 一个后果），降低认知负担；第三，把 ADR 与 PR 评审绑定，决策变更必须附带 ADR 才能合并，让写 ADR 成为"合入门槛"而非"事后整理"；第四，短期奖励（如让 ADR 作者在评审中获得认可）与长期文化（把 ADR 当作知识沉淀的资产）结合。避免形式主义的关键是：ADR 必须写在"决策过程中"而非"决策完成后"，且 ADR 必须包含"备选方案与否决理由"，一段只有结论没有理由与权衡的 ADR 会被退回重写。

形式主义源于"先做后记"，导致 ADR 成为无信息量的装饰。真正的 ADR 是决策过程的产物，与决策同生共死。通过把 ADR 嵌入合入流程（gate）、强调决策留痕而非结果记录，才能把 ADR 从"文档负担"转化为"决策资产"。

• 区分 ADR（记录决策）与 RFC（提出方案征求反馈）的定位
• 判断"必须写"与"不需要写"的决策边界
• 避免过度文档化

ADR 是"决策的记录"，通常在决策已定或接近定稿时产生，用于固化结论与理由；RFC（Request for Comments）是"提案征求反馈"，在决策早期用于展开讨论、收集意见。适用场景上，RFC 适合"影响大、意见分歧、需要社区/团队广泛讨论"的初步提案；ADR 适合"方案已定、需要留痕"的决策。必须写 ADR 的决策包括：引入外部依赖或技术选型、改动系统边界或数据模型、影响可扩展性或安全性的架构改动、公共 API 的破坏性变更。不需要写 ADR 的包括：可逆的局部重构、纯内部实现细节、常规 bug 修复、可由现有规范覆盖的常规操作。判断标准是"决策成本与可逆性"：成本高、不可逆、影响广则写，反之不写。

RFC 是"前向"的讨论工具，ADR 是"后向"的记录工具，二者可在同一决策流程中先后使用（先 RFC 讨论，再 ADR 固化）。避免过度记录与过度讨论同样重要，用"可逆性 + 影响范围"作为开关，避免把所有小决策都文档化。

• 了解主流 ADR 工具的定位与差异
• 理解轻量工具 vs 重量平台的取舍
• 掌握 ADR 在 CI 中的检查与集成方式

adr-tools 是一组 shell 脚本，提供 adr new、adr list 等命令，轻量、无依赖，适合在 git 仓库中管理编号 ADR 文件；MADR（Markdown ADR）是 Markdown 格式的规范模板，以"轻量、可读、模板化"著称，配合 adr-tools 或手工维护，适合希望以纯文本 + git 管理、避免锁定工具的场景；Log4brains 是较重的可视化平台，提供 ADR 的浏览、搜索、状态看板与决策图，适合团队较大、需要可视化治理的场景。选型原则：团队规模小、追求极简用 adr-tools + MADR；需要可视化与搜索体验用 Log4brains。CI 集成方面，可在 CI 中运行 adr 校验（如 ADR 编号唯一、状态字段合法、Superseded 链接存在、Markdown 格式 / lint 通过），并结合文档站点（如 Docusaurus、VitePress）自动发布 ADR 页面，保证每次合并后 ADR 状态与发布内容一致。

工具选择本质是"轻量文本与 git 流程"还是"可视化平台"的权衡。ADR 是纯文本内容，最稳妥的存储是 git 仓库，工具只是编辑与展示的辅助。CI 集成可把"ADR 规范检查"变成硬性门禁，防止格式错误与链接失效。

• 明确 Accept/Reject 的职责归属
• 理解团队级与组织级 ADR 的治理边界
• 掌握跨团队协调机制

团队级 ADR 通常由团队内部的架构师或技术负责人（或评审小组）负责 Accept/Reject，决策权应落在"对决策后果负责"的人身上；影响范围超出本团队、涉及共享基础设施或跨团队契约的 ADR，应由架构委员会或平台组统一评审。跨团队协调机制包括：建立 ADR 索引与共享仓库，让所有团队都能看到组织级 ADR；对跨团队决策设置评审会（如架构评审委员会）与知情/同意流程；对争议决策使用"升级机制"，由更高层委员会裁决。同时应明确 ADR 的"作用域"（Scope），区分组织级与团队级，避免团队私自修改影响全局的决策。

治理的核心是"权责匹配"——谁承担决策后果谁就有决策权。跨团队协调需要显式的评审结构与共享可见性，否则会因决策冲突导致返工。ADR 的治理本质上是人的决策流程，工具只是载体。

• 掌握 ADR 编号的引用规范
• 理解代码、PR、Wiki 与 ADR 的关联方式
• 实现从代码到决策的追溯能力

建立一致引用规范：在引入关键决策的代码位置（如新模块、依赖引入、特殊实现）添加注释 // ADR-0012: 采用 X 方案，让人在阅读代码时能溯源到决策；在 PR 描述中列出受影响的 ADR（如 Relates to ADR-0012），并说明本 PR 是否改变了既有决策；在 Wiki 中维护 ADR 索引，并在相关页面标注决策编号。编号建议用全局唯一且稳定的格式（如 ADR-0012），并在代码中通过脚本或协议固定命名。这样实现了"代码 → PR → ADR → 决策上下文"的完整追溯链，帮助新人理解"为什么这样写"。

代码注释引用 ADR 的粒度要克制——只在与决策强相关的关键位置引用，避免到处贴编号造成噪音。引用规范能降低"代码与文档脱节"的风险，让代码注释成为决策的入口而非重复。

• 理解 ADR 内容应包含决策过程而非仅结果
• 掌握备选方案留痕的写法
• 通过流程机制保证 ADR 与决策同步

避免"事后记录"的关键是让 ADR 在决策生成时即被创建，并成为决策讨论的载体。具体做法：ADR 的"上下文"部分明确记录触发决策的背景、约束与目标；"决策"部分列出被否决的备选方案（Alternatives）及每个方案被否定的理由，而不仅仅是最终选择；把决策讨论（如 issue、评审记录、会议纪要）链接到 ADR 中。通过流程保证：涉及架构决策的 PR 必须附带 ADR，且 ADR 需在讨论阶段（Proposed 状态）就存在，随决策逐步收敛到 Accepted。这样 ADR 记录的是"决策是如何形成的"而非"决策是什么"，保留完整的过程证据。

备选方案与否决理由是 ADR 最具价值的部分，它让后人理解"为什么不是 B"而不仅是"选了 A"。将 ADR 前置到决策流程而非后置到结果，是防止形式主义的根本手段。

• 理解 ADR 的价值定位（知识沉淀、追溯、防遗忘）
• 掌握背景、方案、权衡的记录维度
• 理解 ADR 对团队的实际收益

ADR 的核心价值在于把"散落在头脑中的决策背景"固化为可检索、可追溯的组织资产。它记录三方面：决策背景（为什么此时此地需要做决策、约束与目标是什么）、方案（最终采纳的方案及被否决的备选方案）、权衡（各方案在成本、复杂度、性能、可维护性等维度的取舍）。价值体现在：新人无需向老员工反复询问"为什么这样"即可快速理解架构；避免团队因成员流动而丢失决策上下文；为后续决策提供可参考的权衡依据，减少重复讨论；在架构被质疑时能提供当初的决策依据。

ADR 的价值不是"记文档"，而是"保存决策智慧"。背景、方案、权衡三者缺一不可：只有背景没有方案无法落地，只有方案没有权衡无法取信。这是 ADR 与普通日志的本质区别。

• 理解 ADR 价值的度量维度
• 掌握软性指标与硬性指标的结合
• 评估 ADR 投入产出比

ADR 的价值度量可从多个维度展开：过程维度，统计"同一问题被重复讨论的次数"是否因 ADR 索引而下降；效率维度，统计新人在首月内"理解架构的时间"或"需要向老同事提问的次数"是否减少；质量维度，统计由 ADR 支撑的决策在前瞻性、返工率上的表现；覆盖率维度，统计关键架构决策中被 ADR 记录的比例。这些指标多为软性（需结合访谈、问卷、工单数据），可通过"决策复盘会上依据 ADR 回溯的便捷程度"、"新人 onboarding 问卷中架构理解自评"等采集。管理上应平衡投入与产出：ADR 的价值是长期累积的，不必追求每个指标都精确量化，重要的是建立"决策可追溯"这一基线。

ADR 的价值难以用单一数字精确衡量，更多体现为"沟通成本下降"与"知识留存"这类间接效益。度量应聚焦于"重复讨论减少"和"决策背景可获取"两个可观测信号，并配合定性反馈综合评估。

• 理解 ADR 分级（组织级/团队级）的必要性
• 掌握不同层级 ADR 的评审与存储
• 理解层级间的引用与冲突处理

大型组织应通过"作用域（Scope）"为 ADR 分层：组织级 ADR 约束全组织或跨团队共享的决策（如统一技术栈、共享数据模型、安全规范），由架构委员会治理、存储于共享仓库，所有团队必须遵守；团队级 ADR 只约束本团队内部决策（如某服务的内部实现），由团队负责人治理、存储于团队仓库。层级间通过引用建立关系：团队级 ADR 可引用组织级 ADR 作为约束来源，并在冲突时遵循"组织级优先"原则。治理上，组织级 ADR 需要更严格的评审与变更控制，团队级 ADR 则追求轻量快速。清晰的分层避免了"所有决策都上升到组织级"的官僚化，也避免了"团队擅自决定全局事务"的失控。

分层治理的本质是"把决策权放到合适的作用域"。组织级 ADR 确定全局基线，团队级 ADR 在基线内做局部优化，二者通过引用与优先级规则协同，既保证一致性又保持灵活性。

• 掌握 ADR 失效的标记方式
• 理解失效检测的机制与触发点
• 维护 ADR 与代码现状的一致性

当决策被推翻时，不应删除原 ADR，而应将其状态标记为 Deprecated 或 Superseded，并写明原因与新决策的链接。失效检测的机制包括：在代码评审中，当实现明显偏离某 ADR 时，评审者应指出并触发 ADR 更新；在定期架构评审/复盘会中，对照代码现状核对 ADR 是否仍有效；通过文档与代码的关联（如代码注释引用 ADR 编号）帮助定位"已失效但仍被引用"的 ADR。更新时，把"推翻原因 + 新决策"一并记录，保持历史链完整。理想做法是建立"ADR 状态与代码实现一致"的提示机制，但这需要人工配合，难以完全自动化。

ADR 失效的管理是"诚实面对变化"的体现。标记废弃而非删除，保留了决策演化的完整历史；失效检测依赖评审流程与代码关联的配合，属于治理性工作而非一次性任务。

• 掌握 ADR 模板的字段设计
• 理解评审流程的各阶段
• 平衡模板的完整性与轻量性

一个实用的 ADR 模板应包含：标题（一句决策）、状态（Proposed/Accepted/Deprecated/Superseded）、日期、上下文（背景与问题）、决策（最终方案）、备选方案（Alternatives 及否决理由）、后果/影响（正面与负面）、关联（Supersedes/Superseded by 链接、相关 issue）。评审流程设计为：作者创建 Proposed 状态的 ADR → 在评审中（如 PR 评审、架构评审会）讨论 → 根据反馈修订 → 评审通过后标记为 Accepted → 与实现合入。对于影响范围大的决策，可增加"知情通知"（让受影响团队知晓）与"冷静期"（一定时间后再确认）。模板应保持轻量，避免字段过多导致填写负担，同时确保关键信息（背景、决策、权衡、状态）不缺失。

模板是"写作脚手架"，既保证信息完整性，又降低每次写 ADR 的认知成本。评审流程把 ADR 从"个人记录"变成"团队共识"，任何决策都经过显式确认后才生效。

• 理解 ADR 维护的周期性工作
• 掌握过期识别与更新策略
• 维护 ADR 与现状的一致性

ADR 的维护包括定期检查与更新：通过周期性架构评审、代码评审、新人提问等信号识别"与现状不符"的 ADR；对过期的 ADR，优先新建 ADR 记录新决策并链接，而非直接改写旧内容；对仍有效但表述过时的 ADR，可做轻量修订（注明修订日期）。维护的触发点应尽量自动化/半自动化：在文档 CI 中检查过期的 ADR 状态、未更新的 Superseded 链接、无人认领的 Proposed 状态 ADR。同时应定期清理"长期处于 Proposed 且无进展"的 ADR，要么推进要么归档。维护的最终目标是让 ADR 集始终是"当前决策的可信快照"。

ADR 维护是"治理性"工作，本质是保持文档与代码事实对齐。它与"不可变"原则不矛盾——内容不可变，但状态与链接可更新，且过期识别需要流程与工具配合。

• 理解 ADR 作为架构治理的载体
• 掌握决策可追溯的实现方式
• 理解治理与可追溯的闭环

ADR 是架构治理的核心载体：它把分散的架构决策集中、编号、分层，形成可审计的决策库。决策可追溯体现在三个方面：向前追溯（从当前代码可以找到它依据的 ADR 与决策上下文）、向后追溯（从 ADR 可以找到其 Supersedes/Superseded by 的演化链和相关 PR/issue）、横向追溯（团队级 ADR 关联到组织级 ADR 的约束）。通过 ADR 的唯一编号、状态的规范化、双向链接以及 ADR 与代码/PR/Wiki 的关联，治理者可以随时回答"当前架构为何如此、经历了哪些演变、谁在何时做了哪些决策"。可追溯性使架构治理从"凭经验拍板"转向"有据可依"。

架构治理的核心是"决策的透明与可控"。ADR 提供了一条从决策到实现、从历史到当前的完整证据链，使任何架构变更都能被审计、被质疑、被复盘，这是治理的基石。

• 掌握 adr-tools 的基本用法
• 理解 ADR 与 Issue/PR/文档站点的集成方式
• 实现端到端的决策可追溯

adr-tools 通过 adr new 创建带编号的 ADR 文件、adr list 列出全部 ADR、adr edit/adr link 维护与关联，全部以 Markdown 文件形式存于 git 仓库，天然支持版本管理。集成方面：ADR 编号与 Issue/PR 关联——在创建 ADR 或提交 PR 时引用 issue 编号，在 PR 描述中标注关联 ADR，使问题、决策、变更三者打通；ADR 与文档站点集成——通过 CI 将 ADR 渲染发布到文档站点（如 Docusaurus、VitePress），形成可搜索、可浏览的决策库；通过自定义脚本校验 ADR 的编号唯一性、状态合法性、Superseded 链接有效性。这样从"提出 issue → 创建 ADR → 实现 PR → 发布文档"形成完整闭环，任何参与方都能沿链接追踪决策的前因后果。

工具与集成是"可追溯性"的工程保障。ADR 以 git 管理文件为源，通过 CI 与文档站点、Issue/PR 打通，让决策记录既是代码库的一部分，又是可检索的知识资产，实现端到端可追溯。