尧图网页设计 
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.md2.1 适用条件Simple 模板适用于以下场景决策过程直接——存在一个明确的胜出方案权衡取舍极少只需要交代“为什么、是什么、后果、怎么实现”备选方案很少每个备选可以用一两句话否定掉速度优先——相比穷举式对比记录效率更重要。典型例子团队决定本地开发数据库改用 SQLitebetter-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 matterstatus、date、decision-makers三个必填元数据字段Context and Problem Statement说明为什么现在必须做这个决策、存在哪些约束要求背景足够完整让第一次读到的人或 Agent无需追问就能理解Decision明确我们选择做什么要求具体并包含范围scope与非目标non-goalsConsequences以Good, because .../Bad, because ...列表呈现正负后果Implementation Plan列出受影响路径Affected paths、依赖变更Dependencies、应遵循的模式Patterns to follow、应避免的模式Patterns to avoidVerification以复选框形式给出可验证的验收标准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/、ConsequencesGood/Bad/Neutral 三类、Alternatives Considered无正式记录、Wiki/Notion、轻量 RFC 三个备选各用一句否决和 More Information。这份已 accepted 的 ADR 证明了 Simple 结构足以承载一个真实、完整、可被后续 Agent 执行的架构决策。三、MADR 模板多方案权衡的结构化记录文件assets/templates/adr-madr.md3.1 适用条件MADROptions-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 或既有 ADRDecision 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 外还要求列出Configurationenv vars、配置文件、feature flags与Migration steps迁移步骤并说明是否可增量进行Verification同样以复选框列出具体、可测试的验收标准例如npm test在 SQLite 测试库下通过src/db/之外不允许出现直接pgimportPros and Cons of the Options可选为每个候选方案分别建立### 标题小节用 Good / Neutral / Bad 三类论点展开对比More Information兜底存放相关链接、团队约定、实现笔记或触发重新审视的条件。3.3 长版示例的价值references/examples.md 中提供了同一决策本地开发数据库用 SQLite的短版与长版两份完整成稿。长版MADR示范了Decision Drivers5 条量化驱动因素、Considered Options3 个候选、Pros and Cons of the Options每个候选 3~6 条论证、带编号的 Migration steps5 步渐进式迁移以及 8 条具体可执行的 Verification 复选框。这份示例是理解两套模板在信息密度上差异的最佳参照物同一决策Simple 用一页讲清结论MADR 则把推理全过程留存下来。四、两套模板共享的 Agent 优先特性无论选择哪套模板以下设计是二者共有的也是 adr-skill 区别于传统 ADR 工具的关键YAML front matter 元数据——统一记录status、date、decision-makersMADR 版额外支持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 questionsMore 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–23受影响的团队规模小团队 / 个人跨团队可逆性容易回退难以撤销预期存续周期数月数年是否需要干系人评审否是使用建议拿不准时先选 Simple。如果讨论过程中暴露出更多复杂性随时可以升级为 MADR原文档原话When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.。在 adr-skill 的四阶段工作流中模板选择发生在Phase 2Draft 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: proposedconsulted/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|slugauto 模式通过扫描目录内既有.md文件名判断是日期前缀还是纯 slug日期前缀格式为YYYY-MM-DD-{slug}.mdslug 由标题小写化、去除引号、非字母数字字符转连字符后生成索引更新--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 DriversCI 速度、测试隔离、生产一致性、离线 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），仅供参考 ADR 模板选型指南：AI SDK 仓库 adr-skill 中 Simple 与 MADR 两种模板的适用场景与实战选择
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.md2.1 适用条件Simple 模板适用于以下场景决策过程直接——存在一个明确的胜出方案权衡取舍极少只需要交代“为什么、是什么、后果、怎么实现”备选方案很少每个备选可以用一两句话否定掉速度优先——相比穷举式对比记录效率更重要。典型例子团队决定本地开发数据库改用 SQLitebetter-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 matterstatus、date、decision-makers三个必填元数据字段Context and Problem Statement说明为什么现在必须做这个决策、存在哪些约束要求背景足够完整让第一次读到的人或 Agent无需追问就能理解Decision明确我们选择做什么要求具体并包含范围scope与非目标non-goalsConsequences以Good, because .../Bad, because ...列表呈现正负后果Implementation Plan列出受影响路径Affected paths、依赖变更Dependencies、应遵循的模式Patterns to follow、应避免的模式Patterns to avoidVerification以复选框形式给出可验证的验收标准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/、ConsequencesGood/Bad/Neutral 三类、Alternatives Considered无正式记录、Wiki/Notion、轻量 RFC 三个备选各用一句否决和 More Information。这份已 accepted 的 ADR 证明了 Simple 结构足以承载一个真实、完整、可被后续 Agent 执行的架构决策。三、MADR 模板多方案权衡的结构化记录文件assets/templates/adr-madr.md3.1 适用条件MADROptions-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 或既有 ADRDecision 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 外还要求列出Configurationenv vars、配置文件、feature flags与Migration steps迁移步骤并说明是否可增量进行Verification同样以复选框列出具体、可测试的验收标准例如npm test在 SQLite 测试库下通过src/db/之外不允许出现直接pgimportPros and Cons of the Options可选为每个候选方案分别建立### 标题小节用 Good / Neutral / Bad 三类论点展开对比More Information兜底存放相关链接、团队约定、实现笔记或触发重新审视的条件。3.3 长版示例的价值references/examples.md 中提供了同一决策本地开发数据库用 SQLite的短版与长版两份完整成稿。长版MADR示范了Decision Drivers5 条量化驱动因素、Considered Options3 个候选、Pros and Cons of the Options每个候选 3~6 条论证、带编号的 Migration steps5 步渐进式迁移以及 8 条具体可执行的 Verification 复选框。这份示例是理解两套模板在信息密度上差异的最佳参照物同一决策Simple 用一页讲清结论MADR 则把推理全过程留存下来。四、两套模板共享的 Agent 优先特性无论选择哪套模板以下设计是二者共有的也是 adr-skill 区别于传统 ADR 工具的关键YAML front matter 元数据——统一记录status、date、decision-makersMADR 版额外支持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 questionsMore 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–23受影响的团队规模小团队 / 个人跨团队可逆性容易回退难以撤销预期存续周期数月数年是否需要干系人评审否是使用建议拿不准时先选 Simple。如果讨论过程中暴露出更多复杂性随时可以升级为 MADR原文档原话When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.。在 adr-skill 的四阶段工作流中模板选择发生在Phase 2Draft 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: proposedconsulted/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|slugauto 模式通过扫描目录内既有.md文件名判断是日期前缀还是纯 slug日期前缀格式为YYYY-MM-DD-{slug}.mdslug 由标题小写化、去除引号、非字母数字字符转连字符后生成索引更新--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 DriversCI 速度、测试隔离、生产一致性、离线 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），仅供参考