cognitalk

Posted on Nov 13 Edited on Nov 13

The History of 'Architecture Decision Record' | 架构决策单(ADR)发展史

#softwareengineering #documentation #architecture

一句话总起

ADR 不是凭空发明的新概念，它是敏捷浪潮下，对抗传统厚重架构文档的产物：早在上世纪90年代学界就意识到“要记录架构决策理由”，但真正流行、定型成大家今天用的 ADR，是 2011 年 Michael Nygard 那篇博客；之后慢慢扩散、变体、工具化，直到现在进入 LLM/Agent 时代，走向人机共用的决策记忆载体。

第一阶段：前传（90年代～2010年，学术铺垫，没有“ADR”这个名字）

在瀑布时代，架构文档是厚厚的说明书、架构视图（比如 Kruchten 的 4+1 视图）。
痛点很明显：文档写得巨大、更新跟不上代码，只写“系统长什么样”，很少写“当初为什么这么选、放弃了什么方案”。架构师一走，历史权衡就跟着消失。

学术界很早就提出：架构知识管理、决策日志（Decision Log），要单独记录决策理由，而不是混在大文档里。

代表人物：Philippe Kruchten（4+1视图提出人），提出要增加决策视图，把取舍单独记下来；
但是：这些理论偏学术、笨重，很难在敏捷开发团队落地，行业里很少有人真的持续写。 > 简单理解：大家知道“要记为什么”，但没有简单好用、适合敏捷的标准写法。

第二阶段：诞生 & 定型（2011年，Nygard 原版 ADR，真正出圈）

2011年11月，Michael Nygard 发布博客《Documenting Architecture Decisions》，正式提出 Architectural Decision Record（架构决策单 ADR），给了极简模板：标题、状态、背景上下文、决策、后果。

核心思想在当年非常反传统：

轻！只记录单个架构级决策，拒绝长篇大论；
和代码放同一个 Git 仓库，跟着代码一起版本管理、走 PR 评审；
不可直接修改：决策一旦生效，不能回头改写；如果条件变了，新建一条 ADR，标记旧的被“取代（superseded）”，保留完整历史链条；
只记录有架构影响的关键选择，不是所有小改动都写。

它踩中了敏捷时代的痛点：敏捷不喜欢厚重前置文档，但又怕架构知识流失。这个模板简单到开会聊完，花10分钟就能写完，很快在技术圈传开。

重点：Nygard 不是第一个想到记录决策的人，但他是第一个给出极简、可落地模板、把它推广给工业界的人。

第三阶段：丰富变体、标准化、大规模落地（2012～2020）

出现很多扩展模板和思路，不再只有 Nygard 原版：

2012 年 Olaf Zimmermann 提出 Y-Statement（Y句式）：一句话浓缩决策，适合给业务、管理层快速汇报，格式：在XX背景下，考虑XX约束，我们决定XX，以此达成XX，接受XX代价；
2017 年 MADR（Markdown ADR）出来，变成流传最广的增强模板：在原版基础上增加备选方案、利弊、相关 ADR、负责人等字段，也是现在国内大厂最常用版本；
配套工具慢慢出现：adr-tools、各类脚手架、CI 脚本，自动编号、生成索引；
云厂商（AWS、Thoughtworks）把 ADR 放进最佳实践，金融、电商、开源项目大规模采用。

中间还出现过一场有意思的争论：
很多团队分不清“什么才算架构决策”，于是有人提出 ADR 可以是 Any Decision Record（任意重要决策单），不局限于架构选型，技术规范、流程、组织决策都能用；MADR 3.0 甚至改成这个含义，4.0 又改回 Architectural，这个争论一直延续到今天。

这个阶段的 ADR，定位还是：人写给人看的结构化备忘录。

第四阶段：平台化、规模化治理（2020～2023）

企业级落地遇到新问题：一个大公司几百上千条 ADR，散在各个仓库里，互相冲突、没人复审、慢慢吃灰。
于是进化方向是：

集中 ADR 知识库、架构图谱，做跨域影响分析；
和 EA、架构治理、合规流程打通；
建立复审机制：定期检查 ADR 的前提假设是否还成立；但检索、冲突校验、影响评估大多还是人肉。

第五阶段：LLM / Agent 时代（当下，就是我们上一轮聊的进化方向）

ADR 开始从纯人可读文档，走向人机双可读的决策记忆底座：

LLM 从会议、IM、PR 自动生成初稿；
RAG 语义检索、自动检查 ADR 冲突、影响面分析；
Agent 预审、把 ADR 里的架构约束转成流水线校验规则；
远期：AI Agent 自己做的选型，也产出 ADR，留给人和后续 Agent 查阅追溯（AgDR）。

极简时间线浓缩版

90年代～2010：学术提出决策日志思想，偏理论，难落地
2011：Nygard 发布原版 ADR，轻量模板诞生，敏捷圈引爆
2012：Y-Statement 短句格式
2017：MADR Markdown 增强模板流行
2018–2020：大厂、云厂商采纳，配套工具兴起
2020–2023：企业架构治理场景规模化使用
2024至今：进入 LLM/Agent 时代，向可推理、可校验的知识载体演进

一、ADR 到底是什么（先破一个常见误解）

ADR = Architecture Decision Record，架构决策记录。一条 ADR 就是一个.md 文件，记录一个架构上重要的决定：当时什么处境、桌上摆了哪几个方案、为什么选了这个、为此认下了哪些副作用。

💡 关键在最后半句。ADR 不是“我们决定用 PostgreSQL”这句结论——结论不值钱，值钱的是“为什么不是 MongoDB、为什么不是留着 MySQL 加分片、我们明知道放弃什么”。只写结论的 ADR 是宣言，不是决策。

Nygard 原话里那个判定标准特别好用：影响结构、非功能特性、依赖、接口或构建方式的，才叫“架构显著”。反过来——一个 lint 规则、一个 bug fix、一次重命名，不配占一个 ADR 编号，commit message 就够了。

“ADR 库 / ADR catalog” 则是这些文件的集合 + 索引 + 模板 + 状态机 + 追踪关系的总和。它不是一个文件夹，是一套决策账本（decision log）：append-only、编号不复用、被推翻也不删、只在新 ADR 里 Supersedes: ADR-0003 指回去。

这个“只追加不改写”的性质，正是它能当 AI 架构师知识库地基的原因——任何一个时间点上，“当前生效的 ADR 集合”= 那份时点的架构意图快照，Git checkout 到那个 commit 就能复原当时团队脑子里在想什么。

二、一条 ADR 长什么样：两代模板

第一代：Nygard 四段式（2011，极简派）

Michael Nygard 2011-11-15 发在 Relevance（后归 Cognitect）博客上的原版，CC0 扔进公有领域，这是它能席卷全行业的隐藏原因——法务零摩擦。全部内容就五块：

# Use PostgreSQL for transaction storage

## Status
Accepted  (supersedes ADR-0007)

## Context
订单服务上线 8 个月，MySQL 单主已到 70% 写饱和；
团队里没人有 Mongo 生产经验；合规要求可审计的
行级变更历史……

## Decision
迁到 PostgreSQL 16，用原生分区表 + logical
replication 做读写分离，不上 Citus。

## Consequences
+ 拿到 JSONB + 窗口函数，省掉一个 ES 边车
+ 合规审计用 pgaudit 直接过
- 团队要补 3 周 PG 运维培训
- 遗留的 4 个存储过程要重写（PL/pgSQL 语法不兼容）

四段各回答一个问题：标题=这是关于啥的、Status=走到哪一步了、Context=为什么是现在、Decision=到底干了啥（祈使句，“我们将用 X”而不是“我们考虑用 X”）、Consequences=变容易了什么、变难了什么。

⚠️ 90% 团队写废 ADR 都废在同一处：Consequences 只写好的不写坏的。而“我们明知道会变难的是什么”恰恰是三年后新人最想翻的那一栏。

第二代：MADR 4.0（2018-，结构化派）

Nygard 够轻，但多干系人、多方案选型时撑不住——没地方放“考虑过的选项”、没地方放“决策驱动因子”。Olaf Zimmermann（HSR OST，前 IBM 咨询架构师）带头搞了 MADR（Markdown Architectural Decision Records），把模板扩成这样：

---
status: accepted
date: 2025-02-10
deciders: 张三(架构), 李四(DBA), 王五(合规)
consulted: 风控组周某
informed: 全体后端
---

# 用 PostgreSQL 承载交易主存

## Context and Problem Statement
订单写负载即将打穿 MySQL 单主，如何在 6 周内
给出一条 3 年不用再迁的路径？

## Decision Drivers
- 合规：行级审计不可协商
- 团队 PG 经验 ≈ 0，学习预算 ≤ 3 周
- 不能引入新的运维中间件（SRE 已超载）

## Considered Options
* PostgreSQL 16 原生分区
* MongoDB 6 + Change Streams
* 保留 MySQL + Vitess 分片

## Decision Outcome
Chosen: **PostgreSQL 16 原生分区**，因为合规驱动
一票否决 Mongo，Vitess 的运维复杂度超出 SRE 带宽。

### Positive Consequences
- JSONB 干掉 ES 边车，年省 ¥38 万
### Negative Consequences
- 4 个存储过程重写
- 需在 Q3 前完成 DBA PG 认证

## Pros and Cons of the Options
### PostgreSQL 16
- Good, because 审计插件成熟
- Good, because 团队 SQL 心智可直接迁移
- Bad, because 分区键选错要停机重建

### MongoDB 6
- Good, because 写扩展最顺
- Bad, because 行级审计要自己造，合规不过 ← 决定性

### MySQL + Vitess
- Good, because 不用迁数据
- Bad, because 多一层 vtgate，SRE 明确接不住

## Links
- Supersedes 0007-mysql-single-primary.md
- Refined by 0051-pg-partition-key.md
- Blocks 0063-event-outbox.md

MADR 的三个杀手锏：

Decision Drivers 单列——把“不可协商的约束”从 Context 里揪出来，评审时第一件事就是对着 driver 逐条打勾，谁也别想用“我觉得”糊过去。
Pros and Cons 逐选项对齐——不是“A 好 B 差”的散文，是同一把尺子量三遍，三年后回看能复现当时的评分。
Front matter 机器可读——status / date / deciders / supersedes / tags 全是 YAML，IDE 插件、CI 校验、仪表盘、AI Agent 都能直接吃。

还有个隐藏第三派：Y-statement

一句话版：“在〈上下文〉下，面对〈关注点〉，我们选了〈方案〉，为拿到〈质量属性〉，接受〈副作用〉。” 适合 Slack 里当场拍板、事后补档的场景，一句顶一段。

怎么选

场景	用哪个
小团队、方案没啥争议、想零阻力起步	Nygard
多干系人 / 有合规审计 / 方案 ≥ 3 个要横向比	MADR 4.0（当下工程团队默认推荐）
会上 5 分钟拍完，事后要留痕	Y-statement 先落一句，一周内扩成 MADR
要给 ISO 42010 审计交差	MADR + 补 9 个标准字段

📌 一条铁律：一个仓库里只许有一种格式。混着用比任何一种单用都糟——检索、模板、CI 校验全废。

三、ADR 库目录：从“文件夹”到“决策图谱”

3.1 最小可用骨架（单仓库，90% 团队够用）

MADR 官方推荐落法是 docs/decisions/，Nygard 原文写的是 doc/adr/，两者都是社区正统，挑一个别混：

your-repo/
├── docs/
│   ├── decisions/                  ← ADR 库本体
│   │   ├── README.md               ← 索引 + 写作公约（必写！）
│   │   ├── TEMPLATE.md             ← 从 MADR release 拷来的模板
│   │   ├── 0001-use-modular-monolith.md
│   │   ├── 0002-adopt-postgresql.md
│   │   ├── 0003-event-driven-between-services.md
│   │   ├── 0004-kubernetes-on-eks.md
│   │   ├── 0005-redis-for-session.md
│   │   │
│   │   ├── superseded/             ← 被推翻的挪这里，不删
│   │   │   ├── 0002-mysql-single-primary.md
│   │   │   └── 0007-in-memory-session.md
│   │   │
│   │   └── index.json              ← 机器可读索引（给 CI/IDE/AI 吃）
│   ├── standards/                  ← 编码规范（不是 ADR）
│   ├── runbooks/                   ← 运维手册（不是 ADR）
│   └── architecture/               ← 现状图 / C4 模型（不是 ADR）
├── .adr-dir                        ← 告诉 adr-tools 库在哪（可选）
├── CLAUDE.md / AGENTS.md           ← 给编码代理的宪法，反向 link 进 ADR
└── .github/workflows/adr-check.yml ← CI 校验编号连续 / 断链 / 状态合法

命名约定就一条：NNNN-lowercase-with-dashes.md，NNNN 四位零填充、永不复用、按创建顺序不按主题分。为啥按顺序不按目录分类？因为 ADR 的价值一半在时间轴上——“第 3 号决定之后第 17 号为什么推翻它”这条线索，一分类就断了。分类交给 front matter 的 tags: 和 affects: 去做，别动文件名。

3.2 企业级骨架（50+ 工程师、多仓库、要审计）

单仓库装不下时，升级成 federated catalog：

architecture-adrs/                  ← 独立“元仓库”，只放索引和跨域决策
├── README.md                       ← 全公司 ADR 门户
├── catalog.json                    ← 聚合各业务仓的 index.json
├── enterprise/                     ← 跨域、CIO/架构委员会级
│   ├── 0001-cloud-standard-is-aws.md
│   ├── 0002-service-mesh-opt-in-not-default.md
│   └── 0003-pii-classification-scheme.md
├── domains/
│   ├── payments/    → 软链到 payments-svc/docs/decisions/
│   ├── identity/    → 软链到 identity-svc/docs/decisions/
│   └── marketplace/ → 软链到 marketplace-svc/docs/decisions/
├── taxonomy/
│   ├── decision-drivers.yml        ← 全公司统一的驱动因子词表
│   │                                  (cost / latency / compliance / ...)
│   └── impact-areas.yml            ← 影响域词表，供过滤
└── tools/
    ├── validate-links.py            ← CI：断链 / 循环 supersedes / 孤儿 ADR
    ├── drift-scan.py                ← 扫代码库，找“代码这么写但没 ADR”的地方
    └── render-site.py               ← 生成静态站，带图谱可视化

企业级比单仓多出来的四件事：

index.json 是刚需，不是可选。字段至少含 id / title / status / date / author / supersedes / superseded-by / affects[] / dependencies[] / tags[] / confidence。有它才有 IDE 插件跳转、PR 里自动 @ 相关 ADR、仪表盘看“哪些决策 2 年没复检了”。
superseded/ 子目录 + 状态字段双保险。文件挪走让活跃区保持干净，状态字段让链接不断——两者都要，别只做一个。
双向追踪：ADR → 代码（front matter 里写 implements: ["services/order/**", "infra/terraform/rds.tf"]），代码 → ADR（那些文件头注释里写 // ADR-0002）。CI 加一条规则：改到 rds.tf 的 PR 若没提 ADR-0002，bot 自动评论“你是否在推翻一个已接受决策？” 这是 AWS Well-Architected 明写的“架构合规门禁”。
季度复检（ADR review cadence）：每条 Accepted 满 12 个月自动进复检队列，决策人或继任者签“仍生效 / 降级 deprecated / 写新 ADR 取代”。没有这一步，一年后 ADR 库就会变成第二个没人信的 Confluence。

3.3 状态机：五个状态，别自创

社区已经收敛到这套，直接用：

        ┌──────────┐
        │ Proposed │  讨论中，未拍板
        └────┬─────┘
             │ 干系人 sign-off
             ▼
        ┌──────────┐   ┌──────────┐
        │ Accepted ├──►│ Rejected │  评审否了，保留理由防半年后再提
        └────┬─────┘   └──────────┘
             │ 时间流逝 / 新约束出现
             ├──────────────┐
             ▼              ▼
      ┌──────────┐   ┌────────────┐
      │ Deprecated│   │ Superseded │──┐ 新 ADR 的编号写这里
      └──────────┘   └────────────┘  │
      不推荐新代码用，但  已被 ADR-NNNN  │
      老代码还没迁完       正式取代      │
                                        │
                                        ▼
                              原文件头部改 status，
                              正文**一个字不改**，
                              移入 superseded/

三条不可破的不变式：

Accepted 之后正文永不编辑（连 typo 都新开一条 errata ADR，听着偏执，但审计场景救过无数人）
编号永不复用，ADR-0007 被推翻了，0007 这个号就陪它进坟
推翻 ≠ 删除，被否的决策是资产不是垃圾——“我们 2023 年试过 Vitess 为啥没成”这段话，值 20 万咨询费

3.4 README.md 才是 ADR 库的真正入口

新手建完目录就冲去写 0001，跳过 README，三个月后库就烂了。README 至少回答六件事：

# ADR 索引与写作公约

## 什么该写 ADR（过不了这三条就别写）
1. 推翻要 > 1 人日 或 要数据迁移
2. 影响结构 / 依赖 / 接口 / 非功能指标（SLA、成本、合规）
3. 一年后有人会问“当初为啥这么定”

## 什么不该写
- linter 能管的格式问题
- 只有一个合理解法的 bug fix
- 会被扔掉的 spike

## 流程
分支 → 复制 TEMPLATE.md → 填 → PR → 
至少 1 名 decider + 1 名 affected-team 批准 → 
merge 时 status: proposed → accepted → 
CI 自动更新 index.json 和本 README 的表格

## 当前生效决策（CI 自动生成，别手改）
| ID | 标题 | 日期 | 决策人 | 影响域 |
|----|------|------|--------|--------|
| 0001 | Modular Monolith | 24-03 | 张三 | 全局 |
| 0002 | PostgreSQL 16     | 24-05 | 李四 | 订单/风控 |
| ... 

## 已被取代（点开看“我们曾经错过的路”）
- superseded/0002-... → 被 0007 取代

那句“CI 自动生成表格”是灵魂——手写索引必烂，机器生成的索引才活得过两次人员更替。

3.5 和周边文档的分工（别把 ADR 写成四不像）

文档类型	回答的问题	粒度	更新频率
C4 / 架构图	系统现在长什么样	全局快照	季度
ADR	为什么长这样，为啥不是另一种	一次一个决定	事件驱动，追加
Spec / RFC	这个决定怎么落地实现	单个特性	随迭代
README	这仓库怎么跑起来	单仓	随代码
Runbook	半夜 3 点炸了怎么办	单个故障模式	随复盘
CLAUDE.md / .cursor/rules	AI 代理写代码时必须遵守啥	单仓	从 ADR 编译生成

最后一行是 2025 年之后新增的一环，也是接回你上一个问题的关键，下面第五节专门讲。

四、ADR 的发展史：一条被反复“重新发明”的实践

这块比多数人想的有意思——ADR 不是 2011 年凭空蹦出来的，它是至少四波人接力做出来的。

🏛️ 史前史（1990s–2010）：架构为什么这事，老问题了

软件架构作为一个正式学科在 1990 年代成型时，“记录设计背后的 why”就是核心议题。SEI 的 Bass / Clements / Kazman 在《Software Architecture in Practice》里就把“rationale（设计理由）”列为架构文档的一等公民；ISO/IEC/IEEE 42010:2011（架构描述国际标准）更是直接给了 ADR 的 9 个建议字段模板。

工业界更早。Olaf Zimmermann 考证：IBM Global Services Method 至少从 1998 年就有一个叫 ARC-100 – Architectural Decisions 的交付物，跟着每期项目走。同期 Philippe Kruchten 的 RAR（Rationale-based Architecture Reconstruction）、Antonio de Boer 的 Addressed / As-Is / To-Be 三段式都在各大咨询公司内流传。

那为什么没火？ 因为那时候的载体是 Word + Rational Rose + 共享盘，写一条理由要开一次变更控制委员会（CCB）。重量级到只有航天/银行核心敢用，互联网团队看一眼就跑了。

思想更上游还有一脉常被引用：Christopher Alexander 1977 年《A Pattern Language》——每个“模式”都是“上下文 + 力（forces）+ 解决 + 后果”的四段结构。GoF 设计模式抄了它的壳，Nygard 抄了它的骨。（这一条是社区通行的溯源说法，Nygard 原文没明写致敬，别当成他亲口认证。）

⚡ 爆点（2011-11-15）：Nygard 一篇博客把重量级拍成轻量级

Michael Nygard——《Release It!》作者，当时在 Relevance（后并入 Cognitect）——发了 《Documenting Architecture Decisions》。全文没提 ISO、没提 IBM、没引一篇论文，就讲了一件被他反复看到的事：

重大架构决定是在会议室、走廊、Standup 间隙做出来的，只活在几个人的脑子里。半年后这人跳槽了，新人看着 MySQL 分库分表的怪异 schema 问“为啥不直接换 PG”，没人答得上来，于是团队要么盲从、要么重吵一遍。

他的解法激进地简单：

一个决定一个文本文件，Markdown，扔进代码仓 doc/adr/
四段：Status / Context / Decision / Consequences，一页纸封顶
顺序编号，永不复用，永不删除
CC0 扔公有领域——这条最被低估，直接让后来所有工具链（adr-tools、Log4brains、MADR、VS 插件）零法务成本生长

为什么是 2011 年爆？ 三个时区同时到位：Git 已经赢了 SVN（“文档和代码同仓同 PR”第一次变得自然）、Markdown 刚被 GitHub 加冕、微服务运动开始让“一个系统一年做 50 个架构决定”成为常态。重量级文档扛不住这个频率，轻量级刚好卡在甜点。

🌱 扩散期（2014–2017）：工具化 + ThoughtWorks 盖戳

2014：adr-tools（Nat Pryce & Duncan McGregor，bash 脚本）——adr new Use PostgreSQL 一条命令建好编号文件、adr list 出索引、adr link 建 supersedes 关系。“写 ADR 从‘写文档’降级成‘跑条命令’”，这是 adoption 曲线的转折点。
2016 前后：ThoughtWorks Technology Radar 把 ADR 放进「Trial / Adopt」环。ThoughtWorks 的雷达从 2013 年对外发布，是当年 CTO 圈最看的选型信号之一，这一盖戳等于给 ADR 发了“企业级安全感”护照——之前是“几个极客在搞”，之后是“我们架构委员会要求”。
同期 Netflix、Monzo、Zalando、GitLab 的工程博客先后公开自家 ADR 目录，GitLab 自己现在仓里 1000+ 条 ADR 成了公开教科书。

📐 规范化期（2018–2020）：MADR 与标准化

2018-04：Olaf Zimmermann 发论文 《Markdown Architectural Decision Records: Format and Tool Support》（第 9 届 European Conference on Software Architecture），MADR 从“一个人觉得该加几栏”升级成有学术论文背书的格式。
2019：Zimmermann 开博客 The Concerned Architect 连载《Architectural Decisions — The Making Of》，把 1998 IBM ARC-100 → 2011 Nygard → 2018 MADR 这条线第一次串成史。
2020-09：MADR 进 DocGen2 研讨会 keynote，标题就很宣言——“Capturing Decisions Where the Developer is Working”。意思很清楚：ADR 的战场不是 Confluence，是 IDE。
同期工具开花：Log4brains（静态站生成 + 图谱）、adr-viewer、VS Code ADR 插件、JetBrains 插件、adr-log CLI。

🏢 企业化期（2020–2023）：云厂商下场定调

这一波的意义是——ADR 从“团队自律”变成“合规条款”。

Microsoft Azure Well-Architected Framework 正式写进“Maintain an ADR”作为架构治理最佳实践，且明确三条铁律：append-only、Accepted 不改写、变更必新开一条并 supersedes 回指；建议字段里加了 confidence level（高/中/低）——这个字段很妙，逼作者承认“这决定我是赌的”。
AWS Prescriptive Guidance 出专篇《Using architectural decision records to streamline decision-making》，把 ADR 的产出对齐到三个业务结果：新老成员对齐、战略方向留痕、反模式防御。
ISO/IEC/IEEE 42010:2011 被 adr.github.io 正式列为 ADR 模板之一，政企/汽车/医疗投标时“我们 ADR 符合 42010”从加分项变及格线。
国内同期：ThoughtWorks 中国、阿里云、腾讯云、华为的架构白皮书开始批量出现 ADR 章节；吉利拿百炼 + ADR 库撑车云协同研发是公开案例里最实的（上一轮提过）。

🤖 代理时代（2024–2026）：ADR 从“给人看”变成“给 Agent 读”

这是当下正在发生、也是跟你上一个问题直接咬合的一层。

范式 shift 一句话：以前 ADR 是“对下一个工程师的礼貌”，现在是编码代理每次会话都要加载的承重上下文。Claude Code 读 CLAUDE.md、Cursor 读 .cursor/rules、Copilot 读 .github/copilot-instructions.md——这些文件如果和 ADR 各写各的，三个月后必然互相打脸（Actual AI 的原话：“The same decision gets restated in CLAUDE.md, AGENTS.md, a README, and a wiki page, and the four copies disagree within a few months.”）。

于是社区给出的新写法叫 agent-optimized ADR——同一条决策，人读一版，Agent 读一版，人那版编译出 Agent 那版：

---
id: R-IMG-001
applies_to: ["**/*.tsx", "**/*.ts"]   ← glob 作用域，Agent 只在碰这些文件时加载
status: accepted
supersedes: []
---
# 图片一律走框架 Image 组件

MUST:    用 <Image> 渲染
MUST NOT: 出现原生 <img>
MUST:    给 width/height，或响应式容器用 fill

## Verify                              ← 关键新增：Agent/CI 可自证
rg "<img " app/ && echo "FAIL: raw <img>" || echo "OK"

四个新字段是这一代的标志：

applies_to: glob——不再全量塞进 context，按当前编辑的文件按需注入，省 token 也省幻觉
MUST / MUST NOT / SHOULD RFC 2119 语气——Agent 对祈使句的遵从率显著高于散文
## Verify 一段可执行命令——Agent 改完代码自己跑一遍，能对账才算合规，不能对账的 ADR 对 Agent 等于装饰
单一事实源 + 编译分发——ADR 是 source of truth，CLAUDE.md / .cursor/rules / AGENTS.md 由脚本从 ADR front matter 生成，禁止手改；改一处，全 Agent 同步

配套冒出一整层 ADR Skills（上一轮提到的那层“分水岭”）：

Skill	干啥
Microsoft `adr-author`	Frame → Decide → Govern 状态机；单选方案 / 没写 downside / 没填 driver 直接打回；PII 扫描 + 决策 ID 原子分配
`adr-drafting`（JosiahSiegel）	七轮苏格拉底反问把“我觉得”逼成可辩护决策
`adr-backfill`	老决策补档，要求两个独立信源交叉验证，禁止 Agent 编当年理由，查不到就写 `not recorded`
Terminal Skills `documentation-and-adrs`	写完 ADR 顺手对齐 README / changelog / 接口注释，末尾挂一个能 fail 的校验
Actual AI Architecture Advisor	MCP 形态，PR 里发现“代码在做决策但没人写 ADR”就自动起草一条丢给人类签
漂移扫描 pipeline	静态分析代码库推断“事实上的架构”，和 ADR 库对账，找出“代码这么写但 ADR 说不该这么写”的漂移点，自动开 issue

⚠️ 这一代真正的难点不是“写”，是“防腐烂”。Anthropic 官方都在文档里念叨“记得定期 review 你的 CLAUDE.md 删掉过期条目”——几乎没有团队真做。所以 2026 年的最佳实践是：把 ADR 保鲜这件事本身交给一个 Agent，让它扫代码、对账、去重、解冲突、提 PR，人只做签字。

五、ADR 库怎么喂给“AI 架构师”

现在把两轮串起来。你上一轮问“灌完材料变成 AI 架构师”，光灌 PDF 和 Confluence 是不够的——那些材料里 60% 是“是什么”，只有 40% 是“为什么”，而架构师值钱的恰恰是那 40%。ADR 库就是把这 40% 提纯出来、结构化、可追溯后的产物。

接线图（照着搭就行）：

┌─────────────────────────────────────────────────┐
│  Git 仓 docs/decisions/                          │
│  ─ Nygard/MADR 正文（人读）                       │
│  ─ front matter（机器读）                         │
│  ─ ## Verify 块（Agent 自证）                     │
└──────────────┬──────────────────────────────────┘
               │ ① CI 编译时
               ▼
┌─────────────────────────────────────────────────┐
│  编译器（adr-compile）                            │
│  ├─→ CLAUDE.md        (Claude Code 吃)           │
│  ├─→ .cursor/rules/   (Cursor 吃，按 glob 分片)  │
│  ├─→ .github/copilot-instructions.md             │
│  ├─→ AGENTS.md        (Codex / Gemini CLI 吃)    │
│  └─→ index.json       (RAG 层吃)                 │
└──────────────┬──────────────────────────────────┘
               │ ② 索引进 RAG
               ▼
┌─────────────────────────────────────────────────┐
│  Dify / 百炼 Knowledge Studio / Bedrock KB        │
│  ─ ADR 单独建库，和“普通文档库”分开               │
│  ─ 检索策略：front matter 硬过滤(status/affects)  │
│     + 正文混合检索 + supersedes 图遍历            │
└──────────────┬──────────────────────────────────┘
               │ ③ Agent 回答时
               ▼
┌─────────────────────────────────────────────────┐
│  AI 架构师 Persona (Delphi / 自建)                │
│  被问“要不要上 Service Mesh”时，强制三步：        │
│  1. 先查 ADR 库：有没有相关的 Accepted / 被否过的 │
│  2. 引原文：“2024-05 ADR-0011 我们评估过 Linkerd，│
│     被否理由是 SRE 带宽，见 §Pros and Cons”      │
│  3. 才给新建议，且必须显式说“这在推翻/细化 ADR-X，│
│     要不要我起草一条 superseding ADR？”           │
└─────────────────────────────────────────────────┘

这套接法解决了上一轮我提的三个“是不是真 AI 架构师”的检验：

检验	没 ADR 库	有 ADR 库
会不会拒绝回答	源文档没写也敢编	front matter 里查无此项 → “这条我们没拍过，要不要开个 Proposed？”
给不给被否方案	只给一个“最优解”	MADR 的 Pros and Cons 段直接摊开三个方案为啥否俩
引不引得到原文	引到 PDF 第几页	引到 `ADR-0011 §Decision Drivers 第 2 条`，可点回 Git commit

💡 一句可以贴在墙上的话：“PDF 让 AI 架构师知道我们做过什么；ADR 库让它知道我们为什么做、放弃了什么、什么条件下该改主意。” 前者是百科，后者才是判断力。

DEV Community