研究报告 · 约 30,474 字 · 预计推送 4 部分

软件架构决策记录（ADR）实践：如何记录取舍、约束、证据与后续复盘 未开始

目录

题记与说明

版本：横纵综合报告 · 最终稿（2026-11-03；按独立审读意见修订，八条意见全部处理，本轮新增核实与改动的处置记录见第四节"核实与修正说明"第 6 条）
来源：本稿综合同日两份章节稿——纵轴《从诞生到当下的完整发展历程》与横轴《横向对比报告》（见 output/reports/parts/ 下 2026-11-03 两个文件），并对两稿之间的两处事实分歧做了当日一手核实与修正、对另外三项关键数据做了复核补充，核实过程与证据见文末"核实与修正说明"。全文关键事实均保留来源链接。

TL;DR

ADR（架构决策记录）是"一份决策一份短文档、与代码同库演进"的工程实践，由 Michael Nygard 于 2011 年 11 月提出。十五年间它完成四级跳：从敏捷博客习惯（2011–2015），经工具化与 ThoughtWorks 雷达背书（2016–2019），到 GitHub 官方规范与 ISO 42010 概念框架收录、MADR 成为事实格式标准（2020–2022），再到 2025 年起被当作 AI 编码智能体的"机构记忆"。格式之争已收敛——MADR 功能最全、Nygard 模板是兼容底线，而 2026 年一项受控实验显示二者各有最优区间（简洁 vs 结构化；该研究先用 DESMET 特征分析从五种模板中专家初选出最优的两个，受控实验仅对比 Nygard 与 MADR；单一研究、33 名本科生样本、待复制），模板没有普适答案；工具层则始终未收敛，头部 CLI 已停更，行业的真实落点是"模板即工具"（Markdown + Git 约定）。课题四要素中，"证据"是所有主流模板的结构性短板，"复盘"（状态机 + supersede 链）是 ADR 相对 RFC/Design Doc 的独特优势但兑现率低。建议按团队规模分层组合，并把"何时写、何时复审"制度化：AI 负责起草与合规审计，人负责裁决。

一、纵轴：发展脉络（1969 → 2026.11）

1.1 阶段〇（1969–2010）：史前积累——"决策文档"的两种传统

ADR 不是凭空出现的，它踩在两条更长的传统上。

第一条是工程师社区的"编号决策文档"传统。 1969 年 4 月 7 日，Steve Crocker 在 UCLA 写下第一份 RFC（"Host Software"），开启互联网社区用编号文本文档记录技术决定与讨论的习惯（RFC 1 原文）。2000 年 7 月，Python 社区把这一体裁产品化为 PEP（PEP 1 "PEP Purpose and Guidelines"，Barry Warsaw、Jeremy Hylton 起草），确立了"提案—讨论—接受/拒绝"的决策流水线（peps.python.org、Python 2.0 What's New）。这套"短文档 + 状态字段 + 全程留痕"的体例，正是 ADR 的精神原型。

第二条是架构研究与治理的"决策一等内容"传统。 2000 年前后，SEI 提出 ATAM（Architecture Tradeoff Analysis Method，Kazman、Klein、Clements，报告编号 CMU/SEI-2000-TR-004），把"架构取舍要有场景、要有证据、要显式化"方法化（ATAM 论文）。2005 年出现两篇奠基文献：一是 Capital One 的 Jeff Tyree 与 Art Akerman 在 IEEE Software（2005 年 3/4 月号）发表《Architecture Decisions: Demystifying Architecture》，给出企业级"架构决策描述模板"——决策、状态、假设、约束、备选方案（Positions）、论证（Argument）、影响（Implications）、相关决策/需求/制品（原文 PDF、IEEE Xplore）；二是 Anton Jansen 与 Jan Bosch 在 WICSA 2005 提出"软件架构即一组架构设计决策"的宣言式论文，被引逾 800 次，把"决策"抬升为架构的一等公民（Semantic Scholar）。

驱动因素：敏捷运动（2001 年后）把"重文档"钉在耻辱柱上，但架构治理又必须留痕；学界与业界同时意识到，架构里真正稀缺的知识不是视图图框，而是"当时的理由"。这一阶段的产品是"重模板"：字段齐全、动辄数页，用于企业架构评审，离开发者的日常还很远。

1.2 阶段一（2011–2015）：诞生——Nygard 的极简模板

关键事件：2011 年 11 月 15 日，Michael Nygard 在自己的博客（thinkrelevance.com，现归档于 cognitect.com）发表《Documenting Architecture Decisions》（cognitect.com 存档；本综合稿于 2026-11-03 再次抓取该页核实，页面标注日期即 2011-11-15）。

Nygard 的方案是做减法：每份记录只写一个决策，原文规定五个小节——Title（编号短句）、Context（促成决策的力量与约束）、Decision（决策本身）、Status（proposed/accepted 等）、Consequences（决策带来的多个后果，含取舍）。他明确反对"架构决策数据库"式的重工具：用纯文本、放进版本库、与代码一起演进、用简单工具生成目录即可。这份模板后来在社区传播中出现了瘦身变体（如 adr-tools 生成的 Status/Context/Decision/Consequences 四节加编号标题），这也是各家转述"四节到六节不等"的由来。后来社区通行的"以 ADR-0001《Record architecture decisions》开篇"的惯例，其样板内容就直接引用这篇 2011 年的文章作为灵感来源（Design Practice Repository 对该实践的梳理）。

主要参与者：Michael Nygard（作者）、最初在敏捷社区转发实践的早期采用者。
驱动因素：版本控制文化成熟 + 敏捷团队需要"轻量留痕"；学界 2005–2010 年的"架构知识（Architectural Knowledge）"研究提供了概念合法性，但业界要的是能落地的极简做法。

1.3 阶段二（2016–2019）：工具化与社区化——从博客习惯到行业默认实践

这是 ADR 从"一篇好文章"变成"一个生态"的关键五年。

权威背书：ThoughtWorks 技术雷达的条目历史（官方条目页，本综合稿 2026-11-03 抓取核实）显示：2016 年 11 月 "Lightweight Architecture Decision Records" 首次进入 Trial 环（2016-11-07 发布），2017 年 3 月维持 Trial，2017 年 11 月晋升 Adopt 环（即"默认采用"），2018 年 5 月维持 Adopt——practitioner Kevin Jalbert 的 2018 年博文也印证了这一时间点（kevinjalbert.com）。对保守企业而言，Adopt 环等于一纸通行证。

工具浪潮：Nat Pryce（npryce）在 2016 年前后发布 shell 脚本工具 adr-tools，提供 adr new / adr link / adr generate toc 等命令，把 Nygard 格式固化为可复制的工作流；此后无数项目的 ADR-0001 样板都写着"推荐 Nat Pryce 的 adr-tools"，例如 GOV.UK 各仓库至今保留这一模板（GOV.UK ADR-0001 示例、ADR 示例库）。

社区组织：GitHub 组织 adr（创建于 2017-07-12，GitHub API 实测）建成门户 adr.github.io，集中登记各类模板与工具（工具登记册）。2017 年，MADR（Markdown Architectural Decision Records）由 Oliver Kopp 发起、Olaf Zimmermann 深度参与，并在 2018 年 ZEUS 研讨会上发表格式论文《Markdown Architectural Decision Records: Format and Tool Support》（CEUR Vol-2072）。Zimmermann 还把决策记录压缩到极致：从 2017 年 SATURN 论文中的 (WH)Y 方法演化为 2019 年前后定名的 Y-Statement——一句话说清"在什么场景下、面对什么关切、选了什么、放弃了什么、为了什么质量、接受什么代价"（ozimmer.ch、MADR 模板解读）。

布道：2017 年 5 月 4 日，Michael Keeling 在 SATURN 2017 做《Architecture Decision Records in Action》报告，留下被广泛转引的实录与视频（会议日程、笔记存档）。

驱动因素：微服务兴起——每个服务一个 docs/adr/ 目录，决策记录天然贴合"服务自治 + 团队自治"；GitHub/Markdown 生态使 docs-as-code 零成本可行；ThoughtWorks 的 Adopt 环给了企业引入的底气。

1.4 阶段三（2020–2022）：主流化、标准化与第一轮反思

企业级背书：2020 年 8 月 13 日，GitHub 官方工程博客发表 Eli Perkins 的《Why Write ADRs》，讲述 GitHub 移动团队用 ADR 做"决策社交化"与异步沟通、并把"未来队友用新 ADR 取代（supersede）你的决策"视为正常生命周期（github.blog）。这标志着 ADR 进入大厂工程规范。

工具生态扩张：2020 年前后，Thomas Vaill（thomvaill）发布 log4brains——npm CLI，把 ADR 从 IDE 直接发布成带搜索与决策间链接的静态站点（github.com/thomvaill/log4brains；2021 年 Lullabot 等团队即用 ADR 记录"选用 log4brains"本身，实例）。斯图加特大学生态推出 ADR-Manager（Web 版 MADR 编辑器，后有 VS Code 扩展，源自 2022 年 Steven Chen 的学士论文、Justus Bogner 指导；adr/adr-manager-apps）。

模板的版本节点：2022 年 5 月 17 日 MADR 3.0.0-beta 将名称从 "Markdown Architectural Decision Records" 改为 "Markdown Any Decision Records"，标志 ADR 体例向产品决策、流程决策泛化；2022 年 10 月 9 日 MADR 3.0.0 正式发布（两个日期均经 GitHub Releases API 于 2026-11-03 复测）。社区同步出现 GADR（Generalized Architecture Decision Records）等泛化框架（adr.github.io/gadr）。标准层面，ISO/IEC/IEEE 42010:2022（2022 年 12 月出版）在新版架构描述框架中明确纳入"架构决策与 rationale"概念，为 ADR 提供了国际标准接口（标准概述、与 ADR 的对照实践）。

第一轮反思：实践中"写了没人读、决策过时无人维护"的问题浮出水面。2022 年赫尔辛基大学的灰色文献综述梳理了 19 篇行业文献中 ADR 实践的分布（综述 PDF）；2023 年 Buchgeher 与 Weinreich（JKU Linz）对 GitHub 开源项目做 MSR 研究，系统考察 ADR 在开源中的真实使用率（IEEE Access、JKU 摘要页）；2023 年 10 月 InfoQ 刊出《Has Your Architectural Decision Record Lost Its Purpose?》，把"ADR 是否已失去意义"变成公开议题（infoq.com）。

驱动因素：远程/异步协作放大了"决策上下文丢失"的痛点，ADR 成为默认答案；但采纳面扩大后，维护成本与"文档漂移"开始显形——这正是"后续复盘"机制（superseded by / deprecated 状态链、adr link、决策图）在此阶段被制度化的原因。

1.5 阶段四（2023–2026.11）：AI 时代——ADR 成为智能体的"机构记忆"

实证研究接棒：2024 年 ECSA 会议上，Ahmeti、Wohlrab 等（查尔姆斯理工大学）发表行业行动研究《Architecture Decision Records in Practice: An Action Research Study》，直接考察 ADR 在企业中如何被引入、维护与衰败（论文 PDF）。2024 年 9 月 17 日 MADR 4.0.0 发布（Releases API 实测）。

ADR 的角色跃迁（2025）：AI 编码智能体（Claude Code、Copilot 等）爆发后，实践者发现 ADR 是现成的、带 rationale 的高质量上下文来源，于是出现三个新动作：

  1. 作为长期记忆：把 ADR 目录喂给智能体，让它在改动前"读旧决策、守旧约束"；社区流传"Claude 因 ADR-0003 的约束而停下"的案例（Andrew Connell: ADR as long-term memory、实践讨论）。
  2. 审计智能体的合规性：actual.ai 的研究指出，编码智能体常常"读不到"覆盖被改代码的 ADR，需靠标题命名与范围声明提升可发现性（What Happens When Coding Agents Read Your ADRs）。
  3. 智能体起草 ADR：出现四阶段工作流的 ADR Skill（扫描—草拟—评审—归档，MCP Market 收录）、Archgate CLI 等决策感知工具（archgate.dev），以及"从代码 diff 自动生成 ADR 防止文档漂移"的路线（Richard Ewing）。社区甚至开始讨论"智能体改架构前必须先提议 supersede 某 ADR"的守门规则（AI-Driven Development 笔记）、"AI 生成 ADR"的公开讨论（Hacker News、mdedit.ai）。

最新实证（2026）：2026 年 4 月 30 日，巴西亚马逊联邦大学的 Nogueira、Silva、Conte 在 arXiv 发布《One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption》（arXiv:2604.27333；本综合稿于 2026-11-03 抓取摘要页与 HTML 全文核实）。该研究先用 DESMET 特征分析对 Tyree/Akerman、Nygard、arc42、Y-Statement、MADR 五种模板做专家初筛、选出得分最高的两个（MADR 0.900、Nygard 0.868；专家即论文前两位作者，均有四年以上工业界软件架构经验），再用 33 人受控实验（软件工程本科生，A 组 17 人、B 组 16 人，交叉/组内设计，两阶段任务间隔一周）仅对 Nygard 与 MADR 做成对对比：Wilcoxon 符号秩检验显示 Nygard 的总评分数显著高于 MADR（W=84.0，p=0.002，Cliff's Δ=0.6364，大效应），优势概率 P̂=0.8182——即从两种模板的观测中各任取一份组成一对，Nygard 得分高于 MADR 的概率约为 81.8%。论文摘要的定性结论是："Nygard 支持简洁客观的记录，MADR 便于承载结构化细节与具体架构需求。"AOE 等企业的技术雷达也已把 ADR 列入 Methods & Patterns 常设条目（AOE Tech Radar）。

驱动因素：LLM 需要"可机读、可检索、自带理由与代价"的上下文，ADR 恰好是 15 年来社区打磨出的标准单元；"决策记录"从给人看的文档，变成人与智能体共用的机构记忆，复盘方式也从人工例会扩展到"智能体持续对照 ADR 审计代码"。

1.6 纵轴收束：取舍、约束、证据、复盘四要素的演变

1.7 时间线速查表（2026-11-03 核实修订版）

时间事件来源核实状态
1969-04-07第一份 RFC（Steve Crocker，UCLA）ACM DL—
2000-07PEP 1 确立 Python 提案流程peps.python.org—
2000SEI 发布 ATAM（CMU/SEI-2000-TR-004）论文 PDF—
2005-03/04Tyree & Akerman 企业级决策模板（IEEE Software）PDF—
2005Jansen & Bosch："架构=一组设计决策"（WICSA）Semantic Scholar—
2011-11-15Nygard《Documenting Architecture Decisions》，五节模板cognitect✅ 页面直读
2016-11ThoughtWorks 雷达首次收录，入 Trial 环官方条目页✅ 官方页
2017-11雷达升 Adopt 环同上✅ 官方页
2016 前后Nat Pryce 发布 adr-toolsGOV.UK 样板佐证✅ 5,756★、2024-04 停更（API）
2017-05-04Keeling《ADR in Action》（SATURN 2017）日程—
2017-07-12GitHub org "adr" 创建api.github.com/orgs/adr✅ API
2018MADR 格式论文（ZEUS，CEUR Vol-2072）PDF—
2019 前后Y-Statement 定名传播ozimmer.ch—
2020-08-13GitHub 官方博客《Why Write ADRs》github.blog—
2020 前后log4brains 发布（静态站点化 ADR）GitHub✅ 1,606★（API）
2022-05-17MADR 改名 "Any Decision Records"（3.0.0-beta）Releases✅ Releases API
2022-10-09MADR 3.0.0 正式发布同上✅ Releases API
2022-12ISO/IEC/IEEE 42010:2022 出版，纳入决策/rationale概述—
2023GitHub 开源项目 ADR 使用的 MSR 研究IEEE Access—
2023-10InfoQ《Has Your ADR Lost Its Purpose?》infoq—
2024ECSA 2024 ADR 行动研究；MADR 4.0.0（09-17）PDF✅ Releases API（4.0.0）
2025ADR 作为 AI 智能体长期记忆/守门规则兴起actual.ai—
2026-04-30五模板研究（DESMET 特征分析专家初筛五选二）：受控实验仅对比 Nygard 与 MADR，33 人交叉实验中 Nygard 总分胜出arXiv:2604.27333✅ 摘要页 + HTML 全文

二、横轴：横向对比（时间截面：2026-11-03）

2.1 对比框架：四个圈层 × 五个维度

ADR 的"竞品"不是一个单一对手，而是四个圈层的替代与互补方案：

圈层含义代表
A. 模板/格式流派ADR 内部的格式竞争（"同类"）Nygard 原始模板、MADR、Y-Statements、EC-ADR
B. 工具链围绕 ADR 的创作、索引、发布、门户工具（"互补+竞品"）adr-tools、Log4brains、adr-log、ADR-Manager、Backstage ADR 插件、AI 生成 ADR
C. 替代记录形式满足"记录决策"同一需求的其他文档实践（"替代方案"）Google Design Doc、RFC 流程、PRD、Confluence 决策日志
D. 重型方法学传统重量级架构文档/评估方法（"上一代方案"）arc42、ATAM、ISO/IEC/IEEE 42010/42020

贯穿对比的五个维度：能力（结构化程度、取舍/约束/证据覆盖度、生命周期与复盘支持）、成本（学习/流程/维护）、生态（模板、工具、社区、AI 支持）、成熟度（社区规模、维护活跃度、学术与工业证据）、适用场景。

2.2 总对比表

GitHub star 数与最近推送时间均为 2026-11-03 经 curl https://api.github.com/repos/<repo> 实测复核（详见文末核实说明）。

方案圈层定位/形态能力（结构化/生命周期）成本成熟度证据（2026-11-03 实测/来源）最适用场景
Nygard 原始 ADRA五节 Markdown 短文（社区工具常见四节变体）取舍/后果覆盖好；约束靠 Context 字段；状态字段支持 supersede极低ThoughtWorks 2017-11 起 Adopt；几乎所有 ADR 工具的默认兼容格式；2026 实验中总分最高起步团队、第一个 ADR
MADRAMarkdown 模板 + 决策选项表 + 链接★结构化最强：强制列"考虑过的选项+优缺点"，约束有单独小节；支持链接成决策图低（会 Markdown 即可）GitHub 2,612 stars，2026-08 仍在更新；被 Simpler Grants.gov 等组织采用需要显式写取舍与备选项的团队
Y-StatementsA一句话模板（九要素）极简但完整覆盖"背景-关注点-选项-目标-代价-理由"；天然适合做对比与复用极低学界推广（Zimmermann）；有在线生成器快速记录、跨项目决策复用
EC-ADR 检查单A证据(E)-准则(C)-一致(A)-文档(D)-复盘(R) 五步流程唯一把"证据"和"复盘"显式流程化的流派低Zimmermann 提出（2021；转引自 Adil 2023 应用研究与 ResearchGate 图页；其本人原始博文未定位，见第四节核实说明）决策质量要求高、需要群体决策的场景
adr-toolsBBash CLI，adr new 生成编号文件生成+编号+链接；无检索/无发布/无时间线低5,756 stars，2024-04 后停止维护（实测 last push）；社区出现若干用其他语言重写/替代它的尝试（本稿未逐一核实，无公认继任者）极简主义、纯本地 Markdown 工作流
Log4brainsBNode CLI + 静态站点生成器生成、时间线、全局搜索、发布 docs-as-code 站点中1,606 stars，2024-12 后更新放缓需要"可浏览的决策知识库"的中小团队
adr-logB生成 ADR 目录索引文件只做索引一件事极低109 stars，2023-01 后无推送（实测）配合任何模板做目录
ADR-ManagerBWeb 端编辑器，支持 Y-Statements/MADR结构化编辑、跨项目决策复用中166 stars，2026-05 仍有活动；源于学术项目研究导向、想统一管理多仓库决策
Backstage ADR 插件B企业内部开发者门户组件在服务目录页聚合展示各仓库 MADR；不含创作流程高（需先建 Backstage 平台）@backstage/plugin-adr 已进入官方 community-plugins 仓库（2024-04 迁入）已有 Backstage 的大中型平台工程团队
AI 生成/辅助 ADRBLLM 扫描代码库/对话自动起草 ADR大幅降低写作成本；证据可自动引用代码；但正确性需人工审校低-中HN 讨论、mdedit.ai（2025-2026 新趋势，无公认标准工具）决策积压严重、想补录历史决策的团队
Google Design DocC实现前的设计文档（可几十页）覆盖背景/目标/方案/里程碑；讨论型而非记录型；无标准状态机高（写作+评审周期）Pragmatic Engineer 专题；Google 等大厂内部惯例跨团队大功能的事前设计评审
RFC 流程C编号提案 + 公开评论期 + 接受/拒绝裁决事前征求反馈最强；裁决结果天然成为记录高（流程周期以周计）rust-lang/rfcs 6,628 stars（实测，2026-11 仍活跃）；IETF 同源社区驱动/开源治理、影响面大的变更
PRD / 决策日志C产品文档或 Wiki 表格PRD 回答"做什么为什么"，不回答架构取舍；Wiki 日志检索好但易腐化中PRD vs ADR vs RFC 对比文产品侧需求决策；ADR 只做轻量日志
arc42D12 章节架构文档模板（第 9 章即架构决策）全景文档强；决策部分官方建议直接内嵌 ADR中-高arc42 官方文档第 9 节明确推荐"配合轻量 ADR 工具"需要完整架构文档的乙方交付/受规管系统
ATAMDSEI 权衡分析法，多日评估会议对质量属性取舍的事前评估最深，产出非决策记录极高（专家+数天-数周）2025 年与 ISO 42020 的流程对比研究高风险关键系统的正式评估
ISO/IEC/IEEE 42010/42020D架构描述/架构过程国际标准概念模型完备、合规性强；几乎无轻量工具支持极高与 ATAM 对比研究（同上）；adr.zone 的对照说明政府、军工、强合规行业

2.3 能力维度：谁把"取舍、约束、证据、复盘"记录得最完整

课题标题里的四个关键词恰好构成一张能力检查表：

小结：能力维度上 MADR + EC-ADR 检查单的组合覆盖最全；单一方案中 MADR 是全能王，Y-Statements 是性价比之王，而 2026 年的实验提醒我们：总分最高的记录格式其实是 Nygard 的极简五节。

2.4 成本维度：轻量的边界在哪里

ADR 流派的核心竞争力是单位决策的记录成本。下列三条量级判断为本稿作者的经验估计（非文献实测数据，仅供参考量级）：一条 Nygard 式 ADR 半小时可完成，MADR 完整版约 1-2 小时，Y-Statements 只要几分钟。替代方案的成本高一个量级——Pragmatic Engineer 的专题文章显示 Design Doc/RFC 在大厂通常伴随正式评审会议与数天评论期（Engineering Planning with RFCs, Design Documents and ADRs）；ATAM 则需要外部评估团队和数天到数周的投入，因此 2022 年发表的行业研究明确指出重型评估在工业界不现实、轻量化是趋势（Lightweight Software Architecture Evaluation for Industry）。

但 ADR 的隐性成本常被低估：维护成本（决策变了要不要改旧 ADR？实践答案是用新 ADR 取代并链接，而不是改旧的）和流程成本（没有触发规则的 ADR 会退化为"只记大事"，或者相反地泛滥到每个 PR 一篇）。工具在此处的价值不同：adr-tools 几乎零成本但零赋能；Log4brains 要装 Node 依赖、维护静态站点；Backstage 插件的前提是整个平台工程投入。选型时真正的变量不是模板，而是团队愿意为"决策可检索"支付多少基础设施成本。

2.5 生态维度：谁在为 ADR 供血

2.6 成熟度维度：证据与反证并存

支持面：ThoughtWorks 雷达 Adopt 级（2017-11 起）并衍生出"设计系统决策记录"（2023）、"架构建议流程"（2025-04）等变体（Architecture Advice Process），说明格式已外溢到相邻领域。

反证面：学术研究给出了冷静的数字——JKU Linz 对 GitHub 开源项目的 MSR 研究发现 ADR 采用率仍低但逐年增长（MSR 2023）；社区讨论中常被提及的失败模式是"团队热情启动、数月后停更"（本稿未能定位可附链接的原始出处，按传闻处理，仅作方向性观察）；有据可查的是 Zimmermann 提出的 ADR 采用成熟度五级模型（AD Adoption Model，本稿已抓取该文核实其五级划分），把"写了模板"和"决策流程真正运转"区分开。横向看，RFC（以 Rust 为代表）的社区规模大于最大的 ADR 工具仓库——rust-lang/rfcs 6,628★ 对 adr-tools 5,756★，约为 MADR（2,612★）的 2.5 倍、adr-log（109★）的 60 倍——加上十年稳定的流程运转，其成熟度证据强于 ADR；ATAM/ISO 标准则在合规市场有不可撼动的地位。ADR 的成熟度属于"格式已成熟、工具未收敛、实践易衰减"的中间态。

2.7 适用场景：组合而非二选一

各来源的结论高度收敛于"分层组合"（Calcipy 的 ADR 方案对比与推荐、candost.blog 的 ADR/RFC 之辨）：

三、交叉洞察：两轴合读说明了什么

洞察一：十五年走成一个"钟摆"，落点是"轻格式 + 重流程"

纵轴显示 ADR 的每一步演进都是对上一代形态的减负：ATAM 数周的专家评估（1969–2010 的遗产）减成 Nygard 半小时的五节短文（2011），再压成 Y-Statement 的一句话（2019）；而当轻量格式被大规模采用后，第一轮反思（2020–2022）又把丢失的东西补回来——状态机、supersede 链、决策图、EC-ADR 的五步检查单。横轴的生态实测给这个钟摆一个量化注脚：工具层从"万物生长"（2016–2020）退回到"头部停更、模板常青"（adr-tools 5,756★ 停更于 2024-04，MADR 2,612★ 活跃至今）。两轴合读的结论是：这个行业最终选择把复杂度放在流程（何时写、何时复审、如何链接）而不是格式或软件里——格式已经收敛到"Markdown + 编号 + Git"这个最大公约数，专用工具没有成为必需品。

洞察二：生态赢家 ≠ 认知赢家——"MADR 胜出"与"Nygard 胜出"如何同时成立

两章节稿在此处表面冲突：横轴章节稿（parts/2026-11-03-ADR架构决策记录实践-horizontal.md 第四节洞察 1）的判断是"模板之争已基本结束（MADR 事实上胜出，Nygard 模板作为兼容底线共存）"——本稿第二节的相应表述是 TL;DR 的"格式之争已收敛"与 2.3 小结的"MADR 是全能王"；纵轴章节稿（parts/2026-11-03-adr-vertical.md 第 5 节）的转述是"Nygard 模板以约 81% 的概率在简洁性与清晰度上优于 MADR"（本稿 1.5 节按论文原文核实：Wilcoxon 检验针对的是总评分数，P̂=0.8182）。核实后的消解是：两句话说的不是同一场比赛。生态位上，MADR 确实胜出——它是工具链的默认输入（log4brains 默认随附 MADR 模板、可自定义，ADR-Manager 与 Backstage 插件均以 MADR 为格式），是唯一强制 Pros/Cons 选项表的主流模板，2026-08 仍在活跃维护；但认知负担上，33 人交叉实验（W=84.0，p=0.002，Cliff's Δ=0.6364）显示阅读者对简洁的 Nygard 五节体理解更好，论文原话是"Nygard supports concise and objective documentation, while MADR facilitates structural details and specific architectural requirements"（arXiv:2604.27333）。换句话说：MADR 赢在"写与管"的基础设施，Nygard 赢在"读与懂"的认知成本。这对选型的直接含义是：面向新人的启蒙期用 Nygard/最小版 MADR 降低动笔门槛，涉及重大取舍、多方评审的决策用完整 MADR 保住结构，两者可以共存于同一个 docs/adr/ 目录——实验结论本身也反对"一刀切"。两点限定：其一，该实验是单一研究、样本为 33 名软件工程本科生，结论有待独立复制；其二，"共存于同一目录"的混用建议适用于纯 Markdown + Git 工作流——一旦引入以 MADR 结构为输入假定的工具（ADR-Manager 即 MADR 编辑器，log4brains 默认模板为 MADR 但可自定义），Nygard 格式文件的解析与跨格式的 supersede 链维护缺乏现成支持（本稿未逐一实测各工具对非 MADR 文件的容错），重视工具链一致性的团队应统一为单一格式。

洞察三："证据"是两轴共同指向的全行业短板，也是下一个增量所在

把两轴叠在"证据"这一维度上看，图景高度一致且令人意外：纵轴上，从 Tyree/Akerman 的"论证（Argument）"字段（2005）到今天的 MADR，二十一年间没有任何一个主流模板为证据（benchmark、PoC、代码引用、压测数据）设计过结构化字段——证据始终寄生在 Context 或 Rationale 的自由文本里；横轴上，EC-ADR 检查单（把 Evidence 列为流程第一步）和 AI 辅助生成（自动引用代码位置与基准数据）是仅有的两个解法，且均未普及、均无工具内置校验。两轴交叉指出的方向很清晰：谁先在模板与流程里补上"证据"这一块（哪怕只是一行强制的 Evidence: 链接 + AI 自动引用 + 人工抽查），谁就拿到 ADR 实践的下一个增量。这对个人团队是低成本可执行的改进：不需要新工具，只需要在 Definition of Done 里加一条"决策依据必须带可点开的链接"。

洞察四：复盘是 ADR 的结构性优势、兑现率是现实鸿沟——AI 正在把这个鸿沟变成机会

纵向看，ADR 的复盘机制被工具化了十五年：Status 字段 → supersede 链 → adr link 决策图 → Log4brains 时间线；横向看，这套机制恰恰是 ADR 对 RFC（一次性裁决）和 Design Doc（写完即死）的结构性优势。但两项实证研究戳破了气泡：ECSA 2024 的行动研究发现企业里 ADR 的主要价值停留在"回答为什么"，很少驱动真正的复盘；ICSA 2026 的论文指出 ADR 的实际影响还缺乏量化证据（PDF、论文页）。两轴合读的判断是：复盘失败不是格式问题，而是触发问题——人不记得回头读旧决策，但 AI 可以。2025 年后出现的三类实践（智能体改动前读 ADR、持续审计代码与 ADR 的一致性、改架构前必须先提议 supersede）正是把"复盘"从人工例会变成持续运行的守门进程。这可能是 ADR 历史上第一次，其"复盘"设计被完整兑现。

洞察五：重型方法没有死，只是退到高价值区间；轻与重在内嵌点上合流

纵向的时间线容易让人读出"轻量派消灭重型派"的爽文叙事，横向的圈层对比给出更准确的图景：ATAM/ISO 42020 在强合规与关键系统场景仍是刚需，2025 年仍有新的对比研究发表（scitepress）；arc42 通过"第 9 章官方建议内嵌轻量 ADR"（docs.arc42.org/section-9）完成了与轻量派的合流而非对抗；ISO/IEC/IEEE 42010:2022 则在概念层给 ADR 发了国际标准的身份证。轻重之间不是替代关系，而是按决策风险分层的互补关系：日常决策走 ADR，跨团队大功能走 Design Doc/RFC，关键系统评估走 ATAM——2026 年的全部主流来源都收敛于这个分层组合。

对使用者的判断与建议

选型分层清单：按团队形态对号入座的五档组合（个人/小团队、中型产品团队、开源/社区、大型企业/强合规、决策积压存量项目）已在 2.7 节"适用场景"完整给出，此处不再重复罗列。从两轴暴露的失败模式反推，以下四条制度化规则是无论落在哪一档都应遵守的底线：

  1. 触发规则写进完成定义：改变公共接口、数据模型、外部依赖、性能/安全预算的 PR 必须挂 ADR 编号——否则 ADR 会在数月内衰减为"只记大事的日志"（"数月"为作者经验估计；衰减风险的方向与 ECSA 2024 行动研究对 ADR 维护与衰败的考察、Zimmermann 成熟度模型"写了模板≠流程运转"的区分相一致，两文献均未给出具体时限）。
  2. 永不修改已接受的 ADR：决策变化就写新 ADR 并标记 "Superseded by ADR-nnnn"，保持决策史可回放（GitHub 工程博客把"被取代"定义为正常生命周期，github.blog）。
  3. 标题与范围声明保证可发现性：actual.ai 的智能体实测发现编码 agent 经常"读不到"覆盖被改代码的 ADR——清晰的命名与范围声明对人类同事同样有效（actual.ai）。
  4. 强制一行证据 + AI 分工：即便模板没有证据字段，也约定每条 ADR 带一行可点开的 Evidence:（benchmark/issue/代码引用）；AI 负责起草初稿、对照 ADR 审计代码合规、提议 supersede，人负责取舍与裁决——"模型编造证据"的风险靠人工抽查与链接可验证性兜底。

什么情况下不要用 ADR：一次性探索性原型（结论不进入主干）、纯产品需求决策（PRD 的领域）、需要广泛协商的社区级变更（直接用 RFC）。把 ADR 用在这些地方，只会加速它退化成没人读的仪式文档。

四、核实与修正说明（2026-11-03，综合者实测）

两章节稿之间存在两处事实分歧（下列第 1、2 条），本稿按一手来源做了修正；另有三项关键数据（第 3–5 条）做了复核补充：

  1. Nygard 模板节数（纵轴稿称"四节"，横轴稿称"4~6 字段"）。本稿直接抓取 cognitect.com 存档页核实：原文为五节 Title、Context、Decision、Status、Consequences。纵轴稿"四节"漏掉了 Decision。社区工具（如 adr-tools 生成的 Status/Context/Decision/Consequences 四节加编号标题）存在瘦身变体，横轴"4~6 字段"的模糊表述由此而来；本稿统一为"原文五节、社区变体四至六节"。
  2. ThoughtWorks 雷达轨迹（纵轴稿称 2016-11 入 Assess、2017-11 Vol 18 升 Adopt；横轴稿称 2016-11 起即 Adopt）。本稿抓取官方雷达条目页核实：2016-11-07 首次进入 Trial，2017-03 维持 Trial，2017-11 升 Adopt，2018-05 维持 Adopt，该条目已不在最新版雷达上。两稿均不准确。纵轴稿引用的 Vol 15 中文版 PDF 在本次综合时抓取超时、无法复核其"Assess"之说，本稿以官方条目页为准，并弃用"Vol 15/Vol 18"的卷号表述。
  3. GitHub star 数与维护状态（横轴稿数据）。本稿以 curl https://api.github.com/repos/<repo> 逐项复测（2026-11-03），全部吻合：adr/madr 2,612★、pushed 2026-08-28；npryce/adr-tools 5,756★、pushed 2024-04-25（此后停更）；thomvaill/log4brains 1,606★、pushed 2024-12-17；adr/adr-manager 166★、pushed 2026-05-18；adr/adr-log 109★、pushed 2023-01-05；adr/e-adr 50★、pushed 2026-08-31；rust-lang/rfcs 6,628★、pushed 2026-11-01（活跃）。组织 adr 创建时间 2017-07-12 经 curl https://api.github.com/orgs/adr 复测吻合（纵轴稿同）。
  4. 2026 年五模板研究细节（纵轴稿称"33 人交叉实验、约 81% 概率优于 MADR"）。本稿抓取 arXiv 摘要页与 HTML 全文核实：33 名软件工程本科生（A 组 17 人、B 组 16 人）、交叉（组内）设计、两阶段间隔一周；五种模板（Tyree/Akerman、Nygard、arc42、Y-Statement、MADR）仅出现在 DESMET 特征分析的专家初筛环节（专家即论文前两位作者、均有四年以上工业界经验，MADR 0.900、Nygard 0.868 入围），受控实验仅对 Nygard 与 MADR 做成对比较：Wilcoxon W=84.0、p=0.002，Cliff's Δ=0.6364，优势概率 P̂=0.8182（≈81%；论文原义为"随机配对观测中 Nygard 优于 MADR 的概率"）；论文未报告贝叶斯因子。纵轴稿数字成立，本稿补齐统计细节并澄清实验范围。
  5. MADR 版本日期。经 GitHub Releases API 复测：3.0.0-beta 2022-05-17、3.0.0 2022-10-09、4.0.0 2024-09-17，与纵轴稿一致。
  6. 本轮修订新增核实（2026-11-03，针对独立审读意见逐条处理）：
    • e-ADR 与 EC-ADR 的关系：抓取 github.com/adr/e-adr 的 README 确认，e-ADR 为 "Embedded Architectural Decision Records"——以 Java 注解在源码中嵌入/引用 ADR 决策知识的库，支持 MADR 与 Y-Statements 两种格式，与 A 圈层的 EC-ADR 检查单并非同一物；已在 2.5 补关系澄清，2.2 的 e-ADR 行不动。
    • EC-ADR 来源：其"Zimmermann 2021 提出"之说已通过二手文献核实（Adil 2023，SciTePress 与 ResearchGate 图页均转引该归属，五要素为 Evidence/Criteria/Agreement/Documentation/Review），但 Zimmermann 本人提出该检查单的原始博文仍未定位——其 2021-04-23《Any Decision Records》一文经抓取不含 "EC-ADR" 字样；2.2 的 EC-ADR 行已补转引链接并如实标注"原始博文未定位"。相关谱系另见 Zimmermann 更早的 ecADR "Definition of Done" 工作（LinkedIn 帖）。
    • "热情启动、数月后停更"失败模式：抓取 Zimmermann AD Adoption Model 核实，该文确有五级采用成熟度模型，但不含该失败模式描述；2.6 原先归给"LinkedIn 上的实践者文章"的表述因无链接、参考来源中亦无此文，已降级为传闻性表述并如实标注。
    • adr-tools"社区转向 Go/Node 重写分支"：检索未能定位到具体分支名与链接，2.2 已降级为"社区出现若干用其他语言重写/替代它的尝试（未逐一核实，无公认继任者）"。
    • log4brains 模板兼容性：抓取其 README 确认"模板可自定义（默认：MADR）"；洞察二关于 Nygard/MADR 混用建议的兼容性限定据此改写。
    • 2026 实验的 DESMET 初筛细节与 P̂ 释义：按 arXiv HTML 全文核实后补入 1.5 节与本节第 4 条；"五模板受控实验"的不准确简称在 TL;DR、时间线与参考来源中统一改为"五模板研究（专家初筛五选二，受控实验仅对比 Nygard 与 MADR）"。

仍然未直接核实、沿用章节稿转述的内容（章节稿自身已声明）：ATAM 报告编号 CMU/SEI-2000-TR-004（二手来源确认）；Vol 15 PDF 原文（抓取超时）；各 AI 实践案例的原始页面未逐一点开复核。本轮修订中因无法核实而做了降级/传闻化处理的三处（EC-ADR 原始博文、adr-tools 重写分支、"热情启动数月后停更"的原始出处），处置明细见上文第 6 条。

五、参考来源

奠基与原典

社区、模板与工具

背书、布道与流程参照

标准与重型方法

实证研究与反思

AI 时代实践

实测数据接口（2026-11-03 调用）

思考题（读完后想一想，参考答案可展开）

  1. 报告用“钟摆”概括 ADR 十五年的演进——钟摆的两个方向各指什么？行业最终的落点是什么？
    参考答案

    一个方向是持续减负：ATAM 数周专家评估 → Nygard 半小时五节短文 → Y-Statement 一句话；反向是补回：反思期把状态机、supersede 链、EC-ADR 检查单补了回来。生态注脚：adr-tools（5,756★）2024-04 停更，MADR（2,612★）仍活跃。落点：复杂度被放进“何时写、何时复审、如何链接”的流程，格式收敛为 Markdown+编号+Git。

  2. 生态位上“MADR 胜出”与认知上“Nygard 胜出”如何同时成立？这对模板选型有什么直接含义？
    参考答案

    MADR 赢在“写与管”：它是 log4brains 等主流工具的默认输入格式，且唯一强制 Pros/Cons 选项表；Nygard 赢在“读与懂”：2026 年 33 人交叉实验中总评显著更高（W=84.0，p=0.002）。含义：启蒙期用 Nygard/最小版 MADR 降门槛，重大取舍用完整 MADR 保结构；该实验是 33 人单一研究、待复制，混用仅限纯 Markdown+Git。

  3. 报告揭示了 ADR 实践的哪些风险与局限？哪些场景明确不该用 ADR？
    参考答案

    ①证据短板：没有主流模板为 benchmark、压测数据设结构化字段；EC-ADR 与 AI 自动引用均未普及、无工具校验，AI 还引入“编造证据”风险。②复盘兑现率低：ECSA 2024 行动研究显示其价值多停在“回答为什么”。③隐性成本被低估：没有触发规则，ADR 会退化为“只记大事”或泛滥到每个 PR 一篇。④一次性原型、纯产品决策、社区级协商变更不该用 ADR，否则会沦为没人读的仪式文档。

  4. 个人开发者或小团队如何按报告建议从零起步？四条制度化底线规则分别是什么？
    参考答案

    起步：Nygard/MADR 最小版 + docs/adr/ + Git，不装工具，ADR-0001 写“为什么用 ADR”。四条底线：①触发规则进完成定义，改接口/数据模型/性能预算的 PR 挂 ADR 编号；②永不改已接受的 ADR，变化写新 ADR 标 superseded；③命名与范围声明帮 agent 读到覆盖被改代码的 ADR；④强制一行 Evidence，AI 起草审计、人裁决。

← 资料库今日播报 →