为 AI SDK 项目落地 ADR 规范架构决策记录的目录、命名、状态与生命周期管理指南【免费下载链接】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导读本文以本仓库skills/adr-skill技能包中的 ADR 约定参考文档 为骨架系统讲解如何在 TypeScript 项目中规范地落地 Architecture Decision RecordsADR架构决策记录。你将掌握ADR 目录如何选择与自动探测、文件名如何命名与 slug 化、一份可被 AI 编码 Agent 直接执行的 ADR 最少包含哪些章节、状态值与 YAML Front Matter 字段如何设计以及在大规模项目中如何按类别组织 ADR。本文同时结合仓库内配套的脚本new_adr.js、bootstrap_adr.js与真实决策案例contributing/decisions/2026-03-11-adopt-architecture-decision-records.md给出可复用的落地范式。读完本文你可以直接为本仓库或你自己的项目搭建一套人审批准、Agent 执行的 ADR 工作流。一、ADR 约定规范在项目中的定位本仓库的 ADR 技能包SKILL.md将 ADR 定义为面向编码 Agent 的可执行规范executable specifications for coding agents由人类批准决策由 Agent 负责实现。因此ADR 约定规范conventions不是琐碎的格式洁癖而是保证决策可被发现、可被追溯、可被执行的契约目录与命名约定决定了 Agent 能否用脚本自动找到既有决策Phase 0 代码库扫描最小章节约定决定了 ADR 是否自洽、Agent 能否不追问就动手实现状态值与可变性约定决定了决策的生命周期如何被诚实记录避免历史被改写。仓库自身就是这套规范的活案例contributing/decisions/目录下保存着采用 MADR 4.0 格式的真实 ADR其元数据、命名、章节结构完全遵循本文描述的约定。二、目录约定存放在哪里2.1 选择原则约定文档给出了明确的目录决策规则如果仓库已有 ADR 目录保留它不要另起炉灶如果仓库没有 ADR 目录按项目规模二选一docs/decisions/MADR 默认位置推荐给已有docs/目录结构的项目adr/更简单的备选适合较小的仓库。2.2 脚本探测顺序配套脚本按固定优先级探测既有 ADR 目录顺序为contributing/decisions/ → docs/decisions/ → adr/ → docs/adr/ → docs/adrs/ → decisions/这一顺序在 new_adr.js 的detectAdrDir函数中有完整实现它依次对候选路径执行fs.statSync(p).isDirectory()检查命中第一个存在的目录即返回全部未命中则返回null此时脚本会回退到adr/并自动创建。从源码结构看该函数大约位于文件第 113–130 行。这意味着只要你的仓库把 ADR 放在上述任一约定位置new_adr.js、bootstrap_adr.js都能自动识别无需手工指定目录。2.3 目录命名策略的自动探测new_adr.js还实现了目录内既有文件风格的自动识别detectStrategy约第 144–151 行扫描目录下所有.md文件只要发现任一文件名匹配^\d{4}-\d{2}-\d{2}-正则就判定采用日期前缀策略date否则若目录非空则采用纯 slug 策略slug空目录默认采用日期前缀策略。这一设计保证了新 ADR 永远与仓库既有风格保持一致避免混用。三、文件名约定YYYY-MM-DD-title-with-dashes.md3.1 命名规则规范定义的文件名模式为YYYY-MM-DD-title-with-dashes.md其中YYYY-MM-DD是 ADR 的创建日期必须与 Front Matter 中的date字段一致标题使用小写、短横线连接、现在时祈使动词短语present-tense imperative verb phrase即描述选择了什么而非描述问题本身。官方示例2025-06-15-choose-database.md2025-07-01-adopt-adrs.md同一天产生多个 ADR 完全合法——slug 后缀天然起到消歧作用例如2025-07-01-adopt-adrs.md与2025-07-01-choose-ci-tool.md。3.2 例外情况如果仓库既有的 ADR 采用纯 slug 命名无日期前缀如choose-database.md则遵循既有约定不要强行改成日期前缀。目录风格自动探测见 2.3正是为了处理这种存量仓库的兼容场景。3.3 slug 化的脚本实现new_adr.js中的slugify函数约第 19–27 行给出了标题转文件名的精确规则去除首尾空白并转小写移除引号字符、、反引号将非字母数字字符序列替换为单个-并将连续多个-合并为单个去除开头与结尾的-若结果为空回退为decision。生成的日期前缀由todayISO()new Date().toISOString().slice(0, 10)在脚本运行时自动注入保证dateFront Matter 字段与文件名中的日期前缀一致。同时脚本具备重名保护若目标文件已存在且为 slug 策略会自动追加-2、-3等序号。四、最小章节一份可执行的 ADR 至少包含什么约定文档规定每份 ADR至少必须清晰包含三部分Context背景为什么此刻需要做这个决策当前有哪些约束与驱动因素Decision决策选择了什么Consequences后果哪些事变得更简单/更困难、风险、成本与后续行动。对于agent-first面向 Agent的 ADR还必须额外确保约束是显式且可度量的constraints are explicit and measurable而不是快一点好一点这类模糊表述明确声明非目标non-goals防止实现时范围蔓延识别出后续任务follow-up tasks让决策能够被追踪落地。这一要求在 adr-simple.md 模板中落地为固定章节序列Context and Problem Statement→Decision→Consequences→Implementation Plan→Verification复选框→ 可选的Alternatives Considered→ 可选的More Information。而 adr-madr.md 则在其上扩展出Decision Drivers、Considered Options、Decision Outcome、Pros and Cons of the Options等选项分析章节。4.1 Implementation Plan让 ADR 成为可执行规范的关键SKILL.md 反复强调ADR 必须包含实施计划——要改哪些文件、遵循哪些既有模式、写哪些测试、如何验证决策被正确实现。从 examples.md 中的完整示例可见一份合格的 Implementation Plan 至少包含Affected paths受影响的具体文件与目录如src/db/client.ts、tests/setup.tsDependencies需要新增/移除/升级的依赖及其版本约束如better-sqlite311.xPatterns to follow要遵循的既有代码模式引用具体参考实现文件Patterns to avoid明确不要做什么如禁止在数据访问层之外直接 import 数据库驱动Configuration需要新增/修改的环境变量、配置文件、特性开关Migration steps若涉及替换旧方案描述可增量推进的迁移路径。配套的 Verification 必须写成可勾选的复选框且每个条目都可被 Agent 以命令或测试验证——例如npm test在DB_ENGINEsqlite下通过grep检查src/db/之外无直接pg引用。4.2 真实案例印证仓库自身的 2026-03-11-adopt-architecture-decision-records.md 完整遵循了这套骨架Context 描述了架构决策隐含在代码、对话与隐性知识中的问题Decision 明确采用 MADR 4.0 格式、存放于contributing/decisions/Consequences 用 Good / Bad / Neutral 三分法列出正反与中性后果Alternatives Considered 对无正式记录 / Wiki 或 Notion / 轻量 RFC三个选项逐一说明拒绝理由。这就是约定规范在真实仓库中的直接体现。五、状态值与 YAML Front Matter5.1 状态追踪方式状态记录在 YAML Front Matter 中--- status: proposed date: 2025-06-15 decision-makers: Alice, Bob ---5.2 状态值语义状态含义proposed讨论中尚未定论accepted决策已生效应当被遵循rejected被考虑过但明确未采纳deprecated曾生效但不再适用——必须说明替代路径superseded by title已被更新的 ADR 取代——新旧两侧必须互相链接状态机设计要点新 ADR 一律以proposed起步经讨论与评审后推进为accepted或rejected一旦被新决策取代旧 ADR 标记为superseded并双向链接到新 ADR。仓库的真实 ADR 目前即为accepted状态与contributing/decisions/目录约定一致。5.3 Front Matter 字段规范字段必填说明status是当前生命周期状态date是最近一次状态变更日期YYYY-MM-DDdecision-makers是决策的负责人consulted否被咨询的领域专家双向沟通informed否需保持知情的干系人单向通知consulted与informed遵循RACI 模型Responsible / Accountable / Consulted / Informed在较大团队中用于审计追踪audit trail。adr-madr.md 模板完整保留了这两个可选字段而 new_adr.js 的模板渲染逻辑renderTemplate函数会智能处理提供了值就写入未提供则整行删除确保不会把模板占位符泄漏进成品文件。六、可变性Mutability如何诚实记录历史约定文档对 ADR 的修改边界给出三条原则优先以带日期戳的方式追加新信息而不是重写既有内容——历史即证据追加而非篡改决策被替换时新建一份 ADR 并显式 supersede 旧 ADR——不直接在旧文件里翻案状态变更与事后记录after-action notes允许就地编辑——这两类修改属于生命周期管理而非内容改写。SKILL.md 进一步细化了更新操作矩阵Accept / reject修改状态补充最终背景Deprecate状态置为deprecated说明替代路径Supersede创建新 ADR新旧双向链接Add learnings追加到## More Information小节并加日期戳不重写历史。配套的 set_adr_status.js 脚本专门用于状态修改按 SKILL.md 的说明它同时支持 YAML Front Matter、bullet 风格与 section 风格三种状态书写方式并支持--json输出机器可读结果。七、大规模项目的分类组织当仓库积累大量 ADR 时约定文档建议使用子目录分类contributing/decisions/ # 或 docs/decisions/ backend/ 2025-06-15-use-postgres.md frontend/ 2025-06-20-use-react.md infrastructure/ 2025-07-01-use-terraform.md要点日期前缀在每个分类内是局部的——backend/与frontend/各自独立编号互不冲突尽早确定分类方案按架构层、按领域、按团队并记录在索引文件中备选方案是使用标签tags或平铺结构加可检索索引但子目录方案更简单且与所有工具链兼容无需额外解析逻辑。从new_adr.js的实现看目录探测、文件创建均基于路径字符串操作天然支持子目录嵌套--dir参数可直接指定docs/decisions/backend这类深层路径。八、配套工具链与实战流程8.1 两份模板的选择template-variants.md 给出了模板选型决策表信号用 Simple用 MADR真实可选项数量1–23受影响团队规模小 / 单人跨团队可逆性易回退难撤销预期生命周期数月数年需要干系人评审否是拿不准时先用 Simpleadr-simple.md讨论中暴露出更多复杂性再升级到 MADR。两份模板共享同一套元数据骨架YAML Front Matter、Implementation Plan、复选框式 Verification 与More Information收尾并都支持 Neutral, because... 作为第三类后果表述。8.2 三个脚本的完整用法从 SKILL.md 的 Script Usage 一节在目标仓库根目录执行# 简单 ADRsimple 模板 node skills/adr-skill/scripts/new_adr.js --title Choose database --status proposed # MADR 风格含选项分析 node skills/adr-skill/scripts/new_adr.js --title Choose database --template madr --status proposed # 创建后同步更新索引 node skills/adr-skill/scripts/new_adr.js --title Choose database --status proposed --update-index # 为尚无 ADR 的仓库完成引导 node skills/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions常用参数速查new_adr.js --help可查看完整列表--repo-root path仓库根目录默认.--dir pathADR 目录默认自动探测未命中回退adr/--no-create-dir目录缺失时报错而非自动创建--status value状态默认proposed--template simple|madr模板选择默认simple--strategy auto|date|slug命名策略默认auto即按 2.3 节规则探测--deciders / --consulted / --informedRACI 人员字段逗号分隔--technical-story关联的 issue/ticket/PR 引用--update-index/--index-file path更新索引文件--json输出机器可读 JSON含创建路径、相对路径、索引更新结果等。bootstrap_adr.js则负责从零搭建创建 ADR 目录、生成索引文件adr-readme.md 模板含 Conventions 与 Workflow 说明、并写入首份内容完整的 Adopt architecture decision records 决策而非空白模板默认状态为accepted。8.3 索引维护若仓库有 ADR 索引/日志文件通常是 ADR 目录下的README.md或index.md需保持同步。推荐直接使用new_adr.js --update-index其内部updateIndex函数约第 262–292 行会优先将- 标题 (状态, 日期)条目插入到## ADRs标题下列表的末尾不存在该标题时追加到文件末尾并自动去重已存在相同链接则不重复写入。8.4 创建后的质量闸门ADR 定稿前应使用 review-checklist.md 逐项验证Agent 可读性Context 是否自洽、Decision 是否具体到可执行、Consequences 是否可落地且包含风险与跟进项、Implementation Plan 是否点名了具体文件与模式、Verification 是否是可勾选的测试性标准。该清单还总结了常见失败模式及修复方向例如Improve performance 这类模糊后果 → 追问改善哪个指标、提升多少、如何测量只列一个选项 → 追问否决了什么、为什么补上被拒选项的理由实施计划只写update the code → 追问改哪些文件、哪些函数、用什么模式。按勾选数量给出行动建议全部勾选即发布1–3 项未勾选则与干系人讨论补缺4 项以上未勾选需回到意图收集阶段重做。8.5 四阶段工作流总览整个创建过程对应 SKILL.md 的四阶段流程Phase 0 扫描代码库按约定探测顺序找既有 ADR检查package.json等技术栈文件识别受影响代码模式与既有决策约束Phase 1 苏格拉底式意图收集逐个提问决策是什么、为何现在、约束、成功标准、备选方案、倾向、知情人、Agent 实现所需信息并以意图摘要门Intent Summary Gate让人类确认后才进入下一阶段Phase 2 起草选目录、选命名策略、选模板、逐节填写不留占位符、写 Implementation Plan 与复选框式 Verification优先用new_adr.js生成文件Phase 3 按清单评审对照 review-checklist 输出评审摘要Passes / Gaps / Recommendation通过或人类明确接受缺口后方可定稿。8.6 代码与 ADR 的双向链接为让决策与实现互相可发现规范建议在 ADR 的 Implementation Plan 中点名受影响的文件路径并在实现代码入口处添加轻量注释// ADR: Using better-sqlite3 for test database // See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md import Database from better-sqlite3;原则是入口处一条注释即可不要每行都加目标是可发现性未来 Agent 读代码能回溯决策读 ADR 能定位实现ADR 被 superseded 时也能据此批量找出需要更新的代码。ADR 被接受后还应将实施计划与后果中的跟进项转为可追踪任务issue / ticket / TODO、在 PR 描述中引用 ADR、实现完成后回填 Verification 结果到## More Information。结语约定规范是 ADR 生态的地基目录、命名、章节、状态、可变性与分类这六组约定共同构成了 ADR 技能包的可预测性基础。它们保证了脚本能在任何仓库稳定探测与创建 ADRAgent 能在 Phase 0 快速定位既有决策并在实现前遵守它们人类与 Agent 都能在版本历史中诚实追溯谁、何时、为何、如何做了某个架构选择。本仓库contributing/decisions/下的真实记录正是这套规范有效性的直接证明——若你的项目也面临决策散落在代码与对话中的困境不妨从bootstrap_adr.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），仅供参考
为 AI SDK 项目落地 ADR 规范架构决策记录的目录、命名、状态与生命周期管理指南【免费下载链接】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导读本文以本仓库skills/adr-skill技能包中的 ADR 约定参考文档 为骨架系统讲解如何在 TypeScript 项目中规范地落地 Architecture Decision RecordsADR架构决策记录。你将掌握ADR 目录如何选择与自动探测、文件名如何命名与 slug 化、一份可被 AI 编码 Agent 直接执行的 ADR 最少包含哪些章节、状态值与 YAML Front Matter 字段如何设计以及在大规模项目中如何按类别组织 ADR。本文同时结合仓库内配套的脚本new_adr.js、bootstrap_adr.js与真实决策案例contributing/decisions/2026-03-11-adopt-architecture-decision-records.md给出可复用的落地范式。读完本文你可以直接为本仓库或你自己的项目搭建一套人审批准、Agent 执行的 ADR 工作流。一、ADR 约定规范在项目中的定位本仓库的 ADR 技能包SKILL.md将 ADR 定义为面向编码 Agent 的可执行规范executable specifications for coding agents由人类批准决策由 Agent 负责实现。因此ADR 约定规范conventions不是琐碎的格式洁癖而是保证决策可被发现、可被追溯、可被执行的契约目录与命名约定决定了 Agent 能否用脚本自动找到既有决策Phase 0 代码库扫描最小章节约定决定了 ADR 是否自洽、Agent 能否不追问就动手实现状态值与可变性约定决定了决策的生命周期如何被诚实记录避免历史被改写。仓库自身就是这套规范的活案例contributing/decisions/目录下保存着采用 MADR 4.0 格式的真实 ADR其元数据、命名、章节结构完全遵循本文描述的约定。二、目录约定存放在哪里2.1 选择原则约定文档给出了明确的目录决策规则如果仓库已有 ADR 目录保留它不要另起炉灶如果仓库没有 ADR 目录按项目规模二选一docs/decisions/MADR 默认位置推荐给已有docs/目录结构的项目adr/更简单的备选适合较小的仓库。2.2 脚本探测顺序配套脚本按固定优先级探测既有 ADR 目录顺序为contributing/decisions/ → docs/decisions/ → adr/ → docs/adr/ → docs/adrs/ → decisions/这一顺序在 new_adr.js 的detectAdrDir函数中有完整实现它依次对候选路径执行fs.statSync(p).isDirectory()检查命中第一个存在的目录即返回全部未命中则返回null此时脚本会回退到adr/并自动创建。从源码结构看该函数大约位于文件第 113–130 行。这意味着只要你的仓库把 ADR 放在上述任一约定位置new_adr.js、bootstrap_adr.js都能自动识别无需手工指定目录。2.3 目录命名策略的自动探测new_adr.js还实现了目录内既有文件风格的自动识别detectStrategy约第 144–151 行扫描目录下所有.md文件只要发现任一文件名匹配^\d{4}-\d{2}-\d{2}-正则就判定采用日期前缀策略date否则若目录非空则采用纯 slug 策略slug空目录默认采用日期前缀策略。这一设计保证了新 ADR 永远与仓库既有风格保持一致避免混用。三、文件名约定YYYY-MM-DD-title-with-dashes.md3.1 命名规则规范定义的文件名模式为YYYY-MM-DD-title-with-dashes.md其中YYYY-MM-DD是 ADR 的创建日期必须与 Front Matter 中的date字段一致标题使用小写、短横线连接、现在时祈使动词短语present-tense imperative verb phrase即描述选择了什么而非描述问题本身。官方示例2025-06-15-choose-database.md2025-07-01-adopt-adrs.md同一天产生多个 ADR 完全合法——slug 后缀天然起到消歧作用例如2025-07-01-adopt-adrs.md与2025-07-01-choose-ci-tool.md。3.2 例外情况如果仓库既有的 ADR 采用纯 slug 命名无日期前缀如choose-database.md则遵循既有约定不要强行改成日期前缀。目录风格自动探测见 2.3正是为了处理这种存量仓库的兼容场景。3.3 slug 化的脚本实现new_adr.js中的slugify函数约第 19–27 行给出了标题转文件名的精确规则去除首尾空白并转小写移除引号字符、、反引号将非字母数字字符序列替换为单个-并将连续多个-合并为单个去除开头与结尾的-若结果为空回退为decision。生成的日期前缀由todayISO()new Date().toISOString().slice(0, 10)在脚本运行时自动注入保证dateFront Matter 字段与文件名中的日期前缀一致。同时脚本具备重名保护若目标文件已存在且为 slug 策略会自动追加-2、-3等序号。四、最小章节一份可执行的 ADR 至少包含什么约定文档规定每份 ADR至少必须清晰包含三部分Context背景为什么此刻需要做这个决策当前有哪些约束与驱动因素Decision决策选择了什么Consequences后果哪些事变得更简单/更困难、风险、成本与后续行动。对于agent-first面向 Agent的 ADR还必须额外确保约束是显式且可度量的constraints are explicit and measurable而不是快一点好一点这类模糊表述明确声明非目标non-goals防止实现时范围蔓延识别出后续任务follow-up tasks让决策能够被追踪落地。这一要求在 adr-simple.md 模板中落地为固定章节序列Context and Problem Statement→Decision→Consequences→Implementation Plan→Verification复选框→ 可选的Alternatives Considered→ 可选的More Information。而 adr-madr.md 则在其上扩展出Decision Drivers、Considered Options、Decision Outcome、Pros and Cons of the Options等选项分析章节。4.1 Implementation Plan让 ADR 成为可执行规范的关键SKILL.md 反复强调ADR 必须包含实施计划——要改哪些文件、遵循哪些既有模式、写哪些测试、如何验证决策被正确实现。从 examples.md 中的完整示例可见一份合格的 Implementation Plan 至少包含Affected paths受影响的具体文件与目录如src/db/client.ts、tests/setup.tsDependencies需要新增/移除/升级的依赖及其版本约束如better-sqlite311.xPatterns to follow要遵循的既有代码模式引用具体参考实现文件Patterns to avoid明确不要做什么如禁止在数据访问层之外直接 import 数据库驱动Configuration需要新增/修改的环境变量、配置文件、特性开关Migration steps若涉及替换旧方案描述可增量推进的迁移路径。配套的 Verification 必须写成可勾选的复选框且每个条目都可被 Agent 以命令或测试验证——例如npm test在DB_ENGINEsqlite下通过grep检查src/db/之外无直接pg引用。4.2 真实案例印证仓库自身的 2026-03-11-adopt-architecture-decision-records.md 完整遵循了这套骨架Context 描述了架构决策隐含在代码、对话与隐性知识中的问题Decision 明确采用 MADR 4.0 格式、存放于contributing/decisions/Consequences 用 Good / Bad / Neutral 三分法列出正反与中性后果Alternatives Considered 对无正式记录 / Wiki 或 Notion / 轻量 RFC三个选项逐一说明拒绝理由。这就是约定规范在真实仓库中的直接体现。五、状态值与 YAML Front Matter5.1 状态追踪方式状态记录在 YAML Front Matter 中--- status: proposed date: 2025-06-15 decision-makers: Alice, Bob ---5.2 状态值语义状态含义proposed讨论中尚未定论accepted决策已生效应当被遵循rejected被考虑过但明确未采纳deprecated曾生效但不再适用——必须说明替代路径superseded by title已被更新的 ADR 取代——新旧两侧必须互相链接状态机设计要点新 ADR 一律以proposed起步经讨论与评审后推进为accepted或rejected一旦被新决策取代旧 ADR 标记为superseded并双向链接到新 ADR。仓库的真实 ADR 目前即为accepted状态与contributing/decisions/目录约定一致。5.3 Front Matter 字段规范字段必填说明status是当前生命周期状态date是最近一次状态变更日期YYYY-MM-DDdecision-makers是决策的负责人consulted否被咨询的领域专家双向沟通informed否需保持知情的干系人单向通知consulted与informed遵循RACI 模型Responsible / Accountable / Consulted / Informed在较大团队中用于审计追踪audit trail。adr-madr.md 模板完整保留了这两个可选字段而 new_adr.js 的模板渲染逻辑renderTemplate函数会智能处理提供了值就写入未提供则整行删除确保不会把模板占位符泄漏进成品文件。六、可变性Mutability如何诚实记录历史约定文档对 ADR 的修改边界给出三条原则优先以带日期戳的方式追加新信息而不是重写既有内容——历史即证据追加而非篡改决策被替换时新建一份 ADR 并显式 supersede 旧 ADR——不直接在旧文件里翻案状态变更与事后记录after-action notes允许就地编辑——这两类修改属于生命周期管理而非内容改写。SKILL.md 进一步细化了更新操作矩阵Accept / reject修改状态补充最终背景Deprecate状态置为deprecated说明替代路径Supersede创建新 ADR新旧双向链接Add learnings追加到## More Information小节并加日期戳不重写历史。配套的 set_adr_status.js 脚本专门用于状态修改按 SKILL.md 的说明它同时支持 YAML Front Matter、bullet 风格与 section 风格三种状态书写方式并支持--json输出机器可读结果。七、大规模项目的分类组织当仓库积累大量 ADR 时约定文档建议使用子目录分类contributing/decisions/ # 或 docs/decisions/ backend/ 2025-06-15-use-postgres.md frontend/ 2025-06-20-use-react.md infrastructure/ 2025-07-01-use-terraform.md要点日期前缀在每个分类内是局部的——backend/与frontend/各自独立编号互不冲突尽早确定分类方案按架构层、按领域、按团队并记录在索引文件中备选方案是使用标签tags或平铺结构加可检索索引但子目录方案更简单且与所有工具链兼容无需额外解析逻辑。从new_adr.js的实现看目录探测、文件创建均基于路径字符串操作天然支持子目录嵌套--dir参数可直接指定docs/decisions/backend这类深层路径。八、配套工具链与实战流程8.1 两份模板的选择template-variants.md 给出了模板选型决策表信号用 Simple用 MADR真实可选项数量1–23受影响团队规模小 / 单人跨团队可逆性易回退难撤销预期生命周期数月数年需要干系人评审否是拿不准时先用 Simpleadr-simple.md讨论中暴露出更多复杂性再升级到 MADR。两份模板共享同一套元数据骨架YAML Front Matter、Implementation Plan、复选框式 Verification 与More Information收尾并都支持 Neutral, because... 作为第三类后果表述。8.2 三个脚本的完整用法从 SKILL.md 的 Script Usage 一节在目标仓库根目录执行# 简单 ADRsimple 模板 node skills/adr-skill/scripts/new_adr.js --title Choose database --status proposed # MADR 风格含选项分析 node skills/adr-skill/scripts/new_adr.js --title Choose database --template madr --status proposed # 创建后同步更新索引 node skills/adr-skill/scripts/new_adr.js --title Choose database --status proposed --update-index # 为尚无 ADR 的仓库完成引导 node skills/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions常用参数速查new_adr.js --help可查看完整列表--repo-root path仓库根目录默认.--dir pathADR 目录默认自动探测未命中回退adr/--no-create-dir目录缺失时报错而非自动创建--status value状态默认proposed--template simple|madr模板选择默认simple--strategy auto|date|slug命名策略默认auto即按 2.3 节规则探测--deciders / --consulted / --informedRACI 人员字段逗号分隔--technical-story关联的 issue/ticket/PR 引用--update-index/--index-file path更新索引文件--json输出机器可读 JSON含创建路径、相对路径、索引更新结果等。bootstrap_adr.js则负责从零搭建创建 ADR 目录、生成索引文件adr-readme.md 模板含 Conventions 与 Workflow 说明、并写入首份内容完整的 Adopt architecture decision records 决策而非空白模板默认状态为accepted。8.3 索引维护若仓库有 ADR 索引/日志文件通常是 ADR 目录下的README.md或index.md需保持同步。推荐直接使用new_adr.js --update-index其内部updateIndex函数约第 262–292 行会优先将- 标题 (状态, 日期)条目插入到## ADRs标题下列表的末尾不存在该标题时追加到文件末尾并自动去重已存在相同链接则不重复写入。8.4 创建后的质量闸门ADR 定稿前应使用 review-checklist.md 逐项验证Agent 可读性Context 是否自洽、Decision 是否具体到可执行、Consequences 是否可落地且包含风险与跟进项、Implementation Plan 是否点名了具体文件与模式、Verification 是否是可勾选的测试性标准。该清单还总结了常见失败模式及修复方向例如Improve performance 这类模糊后果 → 追问改善哪个指标、提升多少、如何测量只列一个选项 → 追问否决了什么、为什么补上被拒选项的理由实施计划只写update the code → 追问改哪些文件、哪些函数、用什么模式。按勾选数量给出行动建议全部勾选即发布1–3 项未勾选则与干系人讨论补缺4 项以上未勾选需回到意图收集阶段重做。8.5 四阶段工作流总览整个创建过程对应 SKILL.md 的四阶段流程Phase 0 扫描代码库按约定探测顺序找既有 ADR检查package.json等技术栈文件识别受影响代码模式与既有决策约束Phase 1 苏格拉底式意图收集逐个提问决策是什么、为何现在、约束、成功标准、备选方案、倾向、知情人、Agent 实现所需信息并以意图摘要门Intent Summary Gate让人类确认后才进入下一阶段Phase 2 起草选目录、选命名策略、选模板、逐节填写不留占位符、写 Implementation Plan 与复选框式 Verification优先用new_adr.js生成文件Phase 3 按清单评审对照 review-checklist 输出评审摘要Passes / Gaps / Recommendation通过或人类明确接受缺口后方可定稿。8.6 代码与 ADR 的双向链接为让决策与实现互相可发现规范建议在 ADR 的 Implementation Plan 中点名受影响的文件路径并在实现代码入口处添加轻量注释// ADR: Using better-sqlite3 for test database // See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md import Database from better-sqlite3;原则是入口处一条注释即可不要每行都加目标是可发现性未来 Agent 读代码能回溯决策读 ADR 能定位实现ADR 被 superseded 时也能据此批量找出需要更新的代码。ADR 被接受后还应将实施计划与后果中的跟进项转为可追踪任务issue / ticket / TODO、在 PR 描述中引用 ADR、实现完成后回填 Verification 结果到## More Information。结语约定规范是 ADR 生态的地基目录、命名、章节、状态、可变性与分类这六组约定共同构成了 ADR 技能包的可预测性基础。它们保证了脚本能在任何仓库稳定探测与创建 ADRAgent 能在 Phase 0 快速定位既有决策并在实现前遵守它们人类与 Agent 都能在版本历史中诚实追溯谁、何时、为何、如何做了某个架构选择。本仓库contributing/decisions/下的真实记录正是这套规范有效性的直接证明——若你的项目也面临决策散落在代码与对话中的困境不妨从bootstrap_adr.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），仅供参考
