ADR 模板选型指南：AI SDK 仓库 adr-skill 中 Simple 与 MADR 两种模板的适用场景与实战选择
【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai
导读
在 AI SDK 开源仓库中，adr-skill（位于 skills/adr-skill）为架构决策记录（ADR）的创建与维护提供了一整套面向 Agent 的工作流，而其核心选型问题是：该用哪种模板起草一份 ADR？本指南以 template-variants.md 为骨架，完整讲解adr-simple.md与adr-madr.md两套模板的设计意图、章节结构、共享特性，以及基于选项数量、团队规模、可逆性、生命周期与评审需求的量化选择标准。读完本文，你将能在“快速记录决策”与“结构化多方案权衡”之间做出正确判断，并掌握用new_adr.js --template命令把选型落到实处的完整操作方式。
一、模板变体的整体定位
adr-skill在assets/templates/目录下内置了两套 ADR 模板，供起草阶段按需选用：
- assets/templates/adr-simple.md——轻量模板，面向结论明确、权衡极少的直接决策；
- assets/templates/adr-madr.md——MADR 4.0 风格模板，面向存在多个真实可选方案、需要结构化记录权衡过程的重型决策。
两套模板共享同一套“Agent 优先”的设计哲学。根据 SKILL.md 中的定义，用该技能产出的 ADR 本质是给编码 Agent 的可执行规范（executable specifications for coding agents）：由人类批准决策，由 Agent 负责实现，因此文档必须自包含——约束要明确且可度量，决策要具体到可执行（如"使用 PostgreSQL 16 配 pgvector"，而不是"使用一个数据库"），后果要能映射为具体的后续任务，并且必须包含实现计划。模板选型本身也是这一哲学的体现：选择哪一种骨架，取决于你要给未来的 Agent（或人类读者）呈现多少决策信息。
二、Simple 模板：结论明确的轻量决策
文件：assets/templates/adr-simple.md
2.1 适用条件
Simple 模板适用于以下场景：
- 决策过程直接——存在一个明确的胜出方案，权衡取舍极少；
- 只需要交代“为什么、是什么、后果、怎么实现”；
- 备选方案很少，每个备选可以用一两句话否定掉；
- 速度优先——相比穷举式对比，记录效率更重要。
典型例子：团队决定"本地开发数据库改用 SQLite（better-sqlite3）"，备选方案只有"每轮 CI 起一个 Docker PostgreSQL"和"pg-mem"，各用一句话即可说明否决理由——这种场景完全不需要展开成多方案的论证结构。
2.2 章节结构
Simple 模板的章节顺序为：
Context and Problem Statement（上下文与问题陈述）→ Decision（决策）→ Consequences（后果）→ Implementation Plan（实现计划）→ Verification（验证）→ Alternatives Considered（备选方案，可选）→ More Information（更多信息，可选）
对应到 adr-simple.md 中的实际占位内容：
- YAML front matter：
status、date、decision-makers三个必填元数据字段； - Context and Problem Statement：说明"为什么现在必须做这个决策、存在哪些约束"，要求背景足够完整，让第一次读到的人（或 Agent）无需追问就能理解；
- Decision：明确"我们选择做什么"，要求具体，并包含范围（scope）与非目标（non-goals）；
- Consequences：以
Good, because .../Bad, because ...列表呈现正负后果； - Implementation Plan：列出受影响路径（Affected paths）、依赖变更（Dependencies）、应遵循的模式（Patterns to follow）、应避免的模式（Patterns to avoid）；
- Verification：以复选框形式给出可验证的验收标准；
- Alternatives Considered（可选）：每个备选方案用一两句话说明为何被否决；
- More Information（可选）：相关 ADR、PR、issue 或触发重新审视该决策的条件。
2.3 与仓库真实实践的对照
本仓库自身的第一份 ADR——contributing/decisions/2026-03-11-adopt-architecture-decision-records.md——正是这种轻量结构的实际样例：它包含 Context（隐性决策导致的问题）、Decision（采用 MADR 4.0 格式、存放于contributing/decisions/）、Consequences（Good/Bad/Neutral 三类）、Alternatives Considered（无正式记录、Wiki/Notion、轻量 RFC 三个备选各用一句否决）和 More Information。这份已 accepted 的 ADR 证明了 Simple 结构足以承载一个真实、完整、可被后续 Agent 执行的架构决策。
三、MADR 模板：多方案权衡的结构化记录
文件：assets/templates/adr-madr.md
3.1 适用条件
MADR（Options-Heavy，选项密集型）模板适用于以下场景：
- 存在多个真实可选的方案，需要文档化地记录结构化权衡；
- 需要显式捕获决策驱动因素（decision drivers）——即当时真正影响取舍的标准；
- 该决策很可能被重新审视，因此比较过程需要长期留存；
- 干系人需要看到推理过程，而不只是最终结论。
该模板对齐 MADR 4.0 规范，并在此基础上扩展了面向 Agent 的章节（即实现计划与验证）。原文档明确指出："This template aligns with MADR 4.0 and extends it with agent-first sections."
3.2 章节结构
MADR 模板的章节顺序为：
Context and Problem Statement → Decision Drivers（决策驱动因素，可选）→ Considered Options（候选方案）→ Decision Outcome（决策结果）→ Consequences（后果）→ Implementation Plan → Verification → Pros and Cons of the Options（各方案优缺点，可选）→ More Information（可选）
对照 adr-madr.md 中的占位内容，各章节要点如下：
- YAML front matter：在 Simple 的
status、date、decision-makers基础上，增加可选的consulted（被咨询的专家，双向沟通）与informed（被告知的干系人，单向沟通）两个字段，遵循 RACI 模型； - Context and Problem Statement：鼓励以问题形式表述（"How can we ...?"），并可链接相关 issue、ticket 或既有 ADR；
- Decision Drivers（可选）：逐一列出约束、需求或影响力（force），如"CI 速度""测试隔离""生产环境兼容性"；
- Considered Options：列出全部候选方案标题；
- Decision Outcome：明确写出被选方案及理由（引用驱动因素与权衡），其下挂 Consequences——与 Simple 模板不同的是，MADR 的后果列表除了
Good, because与Bad, because，还引入了第三种类别Neutral, because（既非正面也非负面的后果）； - Implementation Plan：比 Simple 模板更完整，除 Affected paths / Dependencies / Patterns to follow / Patterns to avoid 外，还要求列出Configuration（env vars、配置文件、feature flags）与Migration steps（迁移步骤，并说明是否可增量进行）；
- Verification：同样以复选框列出具体、可测试的验收标准（例如"
npm test在 SQLite 测试库下通过""src/db/之外不允许出现直接pgimport"）； - Pros and Cons of the Options（可选）：为每个候选方案分别建立
### 标题小节，用 Good / Neutral / Bad 三类论点展开对比； - More Information：兜底存放相关链接、团队约定、实现笔记或触发重新审视的条件。
3.3 长版示例的价值
references/examples.md 中提供了同一决策（"本地开发数据库用 SQLite"）的短版与长版两份完整成稿。长版（MADR）示范了Decision Drivers（5 条量化驱动因素）、Considered Options（3 个候选）、Pros and Cons of the Options（每个候选 3~6 条论证）、带编号的 Migration steps（5 步渐进式迁移）以及 8 条具体可执行的 Verification 复选框。这份示例是理解两套模板在"信息密度"上差异的最佳参照物：同一决策，Simple 用一页讲清结论，MADR 则把推理全过程留存下来。
四、两套模板共享的 Agent 优先特性
无论选择哪套模板，以下设计是二者共有的，也是 adr-skill 区别于传统 ADR 工具的关键：
- YAML front matter 元数据——统一记录
status、date、decision-makers，MADR 版额外支持consulted与informed。这些字段被 new_adr.js 的渲染逻辑直接消费：有值则替换占位符，无值则整行删除，避免把{list everyone whose expertise was sought}之类的占位文本泄漏到真实 ADR 中； - Implementation Plan（实现计划）——包含受影响路径、依赖、应遵循/避免的模式、配置、迁移步骤。这是让 ADR 变成"Agent 可执行规范"的关键：
new_adr.js脚本通过--deciders、--consulted、--informed、--technical-story、--chosen-option等参数把这些信息注入模板； - Verification 以复选框呈现——验收标准必须可测试，Agent 在实现完成后可以逐项勾选核验；
- Agent 优先的措辞——占位文本引导撰写者写得具体、可度量、自包含（例如模板要求"agent should be able to start coding from this without asking follow-up questions"）；
- More Information 小节——用于交叉链接、后续跟进与重新审视的触发条件；
Neutral, because...作为第三种论证类别——与 Good、Bad 并列，帮助记录那些"既非利好也非利空"的中性后果（如"抽象层增加约 200 行代码，但让未来的数据库迁移更简单"）。
此外，references/adr-conventions.md 为两套模板共同遵守的约定提供了补充：目录命名（docs/decisions/、adr/等的检测顺序）、文件名规范（YYYY-MM-DD-title-with-dashes.md）、状态机（proposed→accepted/rejected/deprecated/superseded）以及"追加而非重写"的变更原则。状态变更可由 set_adr_status.js 脚本就地完成。
五、如何选择：量化决策信号
原文档给出了一张精炼的选择对照表，是模板选型的核心依据：
| 决策信号 | 使用 Simple | 使用 MADR |
|---|---|---|
| 真实可选方案数量 | 1–2 | 3+ |
| 受影响的团队规模 | 小团队 / 个人 | 跨团队 |
| 可逆性 | 容易回退 | 难以撤销 |
| 预期存续周期 | 数月 | 数年 |
| 是否需要干系人评审 | 否 | 是 |
使用建议：拿不准时，先选 Simple。如果讨论过程中暴露出更多复杂性，随时可以升级为 MADR（原文档原话："When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity."）。
在 adr-skill 的四阶段工作流中，模板选择发生在Phase 2（Draft the ADR）的第三步。完整的流程为：Phase 0 扫描代码库（查找既有 ADR、技术栈、相关代码模式与代码↔ADR 引用）→ Phase 1 苏格拉底式提问捕获意图（经 Intent Summary Gate 确认后）→ Phase 2 起草（选择目录、命名策略与模板）→ Phase 3 对照 references/review-checklist.md 的 Agent 就绪检查清单评审。评审清单中与 MADR 模板直接相关的检查项包括：至少两个真实考虑的方案、每个方案有真实的优缺点、被选方案的理由引用具体驱动因素、被否决方案说明否决原因。
六、把选型落地：new_adr.js 的命令行操作
模板选型最终要通过scripts/new_adr.js落地为真实文件。该脚本（见 skills/adr-skill/scripts/new_adr.js）的设计目标是无外部依赖、安全默认值（自动检测 ADR 目录与命名策略），且在没有既有 ADR 的仓库中也能工作。
从目标仓库根目录执行：
# Simple 模板（默认）：结论明确的决策 node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed # MADR 模板：多方案结构化权衡 node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed # 同时更新索引（README.md 或 index.md） node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index # 在尚无 ADR 的仓库中初始化：创建目录、索引和第一份 ADR node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions脚本行为要点（均可从源码验证）：
- 模板加载：
loadTemplate()依据--template simple|madr从assets/templates/adr-simple.md或adr-madr.md读取原始模板； - 占位符渲染：
renderTemplate()用正则替换 YAML front matter 占位符（如status: "{proposed | accepted | ...}"→status: proposed），consulted/informed无值时整行删除，MADR 标题占位符替换为--title传入的值，同时支持{TITLE}、{STATUS}、{DATE}、{DECIDERS}、{CHOSEN_OPTION}等内联占位符——因此--chosen-option参数专门用于填充 MADR 模板的 "Chosen option" 一行； - 目录自动检测：
detectAdrDir()按contributing/decisions/→docs/decisions/→adr/→docs/adr/→docs/adrs/→decisions/的顺序探测，找不到时默认落到adr/； - 命名策略：
--strategy auto|date|slug，auto 模式通过扫描目录内既有.md文件名判断是日期前缀还是纯 slug；日期前缀格式为YYYY-MM-DD-{slug}.md，slug 由标题小写化、去除引号、非字母数字字符转连字符后生成； - 索引更新：
--update-index会定位README.md或index.md，优先把- title (status, date)条目插入## ADRs标题下，否则追加到文件末尾； - 机器可读输出：
--json输出包含adrDir、createdAdrRelPath、template、strategy、indexChanged等字段的 JSON，便于 CI 或 Agent 程序化消费。
若环境不允许运行脚本，也可以直接从assets/templates/复制对应模板手动填写（SKILL.md 中明确给出了这条回退路径）。
七、选型实战：一个完整决策示例的两种写法
以 references/examples.md 中的"SQLite 本地开发数据库"决策为例，直观对比两套模板的产出差异：
Simple 写法只需回答：为什么现在换（CI 共享 PostgreSQL 导致 flaky 与 3 分钟+ 慢设置）、决定做什么（SQLite + better-sqlite3，生产仍用 PostgreSQL，非目标是不迁移生产也不建完整 ORM）、后果（CI 3+ 分钟降到约 2 秒 / 需维护双方言兼容）、实现计划（src/db/client.ts抽象层 + 两个具体实现 + 测试配置）、验证（两条npm test环境 + import 约束 + CI 时长）、两个备选各一句否决。
MADR 写法额外增加：5 条量化 Decision Drivers（CI 速度、测试隔离、生产一致性、离线 DX、维护成本）、3 个候选方案的完整 Pros/Cons 小节（每个 3~6 条论证）、含 9 处受影响路径和 5 步编号迁移步骤的 Implementation Plan、8 条含 grep 命令的可执行验证项、Neutral 后果记录，以及每周 PostgreSQL 兼容性 CI 作业这一后续任务。
判断要点：决策被推翻的成本越高、未来被重新审视的概率越大、需要说服的干系人越多，就越应该选择 MADR；反之，一个数周内即可验证、容易回退的小团队决策，用 Simple 记录反而更高效。
八、总结与延伸阅读
模板选型不是风格偏好，而是信息策略：Simple 记录结论，MADR 留存推理过程。无论选哪套，都要保证实现计划具体到文件路径与模式、验证标准可勾选可执行，让一份 ADR 真正成为 Agent 可以直接开工的规范文档。当前仓库自身就是一个活样本——contributing/decisions/2026-03-11-adopt-architecture-decision-records.md 用 Simple 结构记录了"采用 ADR"这一决策，而其内容恰好论证了为何需要这套机制。
进一步深入可查阅：
- 模板正文：assets/templates/adr-simple.md 与 assets/templates/adr-madr.md；
- 完整技能说明与四阶段工作流：skills/adr-skill/SKILL.md；
- 起草后的评审依据：references/review-checklist.md；
- 目录、命名、状态与生命周期约定：references/adr-conventions.md；
- 同一决策的短/长版成稿对照：references/examples.md；
- 支撑选型落地的脚本：scripts/new_adr.js、scripts/bootstrap_adr.js、scripts/set_adr_status.js。
【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
