ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

AI SDK 仓库 ADR 评审清单实战:让架构决策记录成为编码 Agent 可直接执行的规格

AI SDK 仓库 ADR 评审清单实战:让架构决策记录成为编码 Agent 可直接执行的规格 AI SDK 仓库 ADR 评审清单实战让架构决策记录成为编码 Agent 可直接执行的规格【免费下载链接】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导读架构决策记录Architecture Decision RecordADR在传统团队中常用于沉淀为什么这样设计的决策过程但在 AI 驱动的开发流程里它的价值被进一步放大一份合格的 ADR 应当让一个没有任何背景知识的编码 Agent 只读一遍就能直接开始实现不需要再追问任何澄清问题。本文以 AI SDK 仓库The AI Toolkit for TypeScript内置的 adr-skill 中的 ADR 评审清单 为核心系统讲解Agent 就绪评审的七大维度、快速打分规则、常见失败模式并结合作战级脚本与仓库真实 ADR 实例给出从起草到定稿的完整落地方法。读完本文你将掌握一套可复用的 ADR 质量闸门既能评审别人的决策记录也能写出让 Agent 无需追问即可开工的实现计划。ADR 评审清单在四阶段工作流中的定位adr-skill 将 ADR 的创建定义为四个不可跳过的阶段而评审清单是第三阶段的验收工具Phase 0扫描代码库——查找已有 ADR、确认技术栈、定位受影响的代码模式为后续提问积累上下文Phase 1苏格拉底式意图捕获——逐题访谈确认触发原因、约束、成功标准、候选方案与实现所需信息Phase 2起草 ADR——选择目录、文件名策略与模板填写每一节并写出实现计划Phase 3对照清单评审——用本清单验证 ADR 是否达到Agent 就绪标准。评审清单在开头就点明了核心目标见 review-checklist.md使用此清单在 Phase 3 中验证 ADR 后再定稿。目标一个编码 Agent 能否读这份 ADR 后立即开始实现决策无需提出任何澄清问题这一句话定义了整个评审的评判标准不是文档写得是否通顺而是信息是否完备到足以让 Agent 独立执行。它与 SKILL.md 的哲学一脉相承——由本技能创建的 ADR 是编码 Agent 的可执行规格executable specifications人类批准决策Agent 负责实现。因此约束必须显式且可度量决策必须具体到可以行动用 PostgreSQL 16 pgvector而非用数据库后果必须映射为具体的后续任务非目标必须声明以防止范围蔓延且 ADR 必须自包含、不依赖任何隐性知识。Agent-Readiness Checks七大评审维度逐项拆解清单的正文部分按七个维度组织每个维度下列出可勾选的检查项。下面逐项结合仓库源码与模板说明其意图与落地方式。Context Problem上下文与问题这一维度回答这份决策为什么存在共四项检查无背景知识的读者能理解该决策为何存在触发原因清晰什么变了、什么坏了、或即将坏掉什么不假设隐性知识——缩写必须定义、系统必须显式命名包含指向相关 issue、PR 或既有 ADR 的链接。仓库中真实的 2026-03-11-adopt-architecture-decision-records.md 是优秀范例它开篇说明架构决策是通过代码、对话和隐性知识隐式做出的进而列出由此产生的三个具体困难无法判断模式是有意还是偶然、不知道旧决策是否仍适用、反复重议已定决策并引用 Michael Nygard 的经典文章作为背景。这就是问题驱动而非方案推销的写法——上下文里只陈述问题解决方案留给 Decision 节。Decision决策本身共三项检查决策足够具体、可执行不是采用更好的方案而是用 X 做 Y范围有边界——明确包含什么、不包含什么非目标约束显式且尽可能可度量如p95 小于 200ms而非够快。adr-simple.md模板在 Decision 节明确要求具体——包括范围和非目标MADR 模板则要求用Chosen option: ... because ...句式把决策与决策驱动因素绑定。评审时若发现use a better approach这类模糊表述应直接判不通过。Consequences后果共四项检查每条后果具体且可行动而非愿景式表述识别出后续任务迁移、配置变更、文档更新、新测试风险需附带缓解策略或接受理由没有一条后果是对决策的换皮复述。两个模板都提供了 Good/Bad/Neutral, because ... 三段式句式强制作者为每条后果给出理由。注意模板设计者特意加入Neutral, because作为第三类参数——不是所有后果都是好坏二分例如抽象层增加约 200 行代码但让未来数据库迁移更容易就是中性后果。评审时要特别警惕后果全是正面的红旗决策必然有代价全部正面的后果列表通常是选择性地只挑了优点。Implementation Plan实现计划这是Agent 优先ADR 最重要的一节共六项检查受影响的文件/目录被显式命名不是数据库代码而是src/db/client.ts要添加/移除的依赖带版本约束要遵循的模式引用现有代码而非抽象描述要避免的模式被明确指出什么不要做配置变更被列出环境变量、配置文件、功能开关若在替换某物需描述迁移步骤。MADR 模板 给出了实现计划的标准骨架Affected paths / Dependencies / Patterns to follow / Patterns to avoid / Configuration / Migration steps。而 examples.md 中的长版示例展示了完整形态——例如 SQLite 决策中受影响路径列出了 9 个具体文件与目录并注明是新建还是重构依赖写为better-sqlite311.x与types/better-sqlite37.xdevDependencies模式包括所有数据库访问经src/db/client.ts统一接口与仅用参数化查询同时明确禁止在src/db/之外直接导入better-sqlite3或pg、禁止在共享查询中使用 JSONB 运算符等 PostgreSQL 专属语法。Verification验证标准共四项检查标准是复选框而非散文每条标准可测试——Agent 能据此写测试或运行命令来检查标准同时覆盖能工作功能正确与做得对结构/架构正确没有模糊标准性能良好 → 100 并发请求下 p95 延迟 200ms。模板中 Verification 一律呈现为- [ ]复选框。示例中出现了可直接执行的验证命令例如grep -r from better-sqlite3 src/ --include*.ts | grep -v src/db/这条命令本身就是一个可编程检查——如果输出非空说明有代码绕过了抽象层。这种命令即验证的写法是把模糊的不要直接导入变成机器可验证的标准正是评审清单要求Agent 能写测试或运行命令来检查的典型体现。OptionsMADR 模板候选方案仅在使用 MADR 模板时适用共四项检查至少有两个方案被真正考虑过不是做某事对比什么都不做每个方案都有真实的优点和缺点不是稻草人对比选中方案的论证引用了具体的驱动因素或权衡被否决的方案解释了为什么被否决而不只是是什么。仓库的 2026-03-11 决策 是极佳范例它在 Alternatives Considered 中列出了无正式记录Wiki 或 Notion 页面轻量级 RFC三个候选并逐一给出否决理由——上下文丢失、决策被反复重议与代码脱节、不受版本控制对大多数决策而言过重。这种写法保留了决策过程的推理链使后来者包括 Agent无需重走一遍讨论。Meta元信息共五项检查Status 设置正确新 ADR 通常为proposedDate 已设置决策者已列出标题是描述决策的动词短语而非描述问题文件名遵循仓库约定。关于文件名约定adr-conventions.md 明确规定模式为YYYY-MM-DD-title-with-dashes.md日期前缀与 front matter 的date字段一致标题用全小写、连字符、现在时祈使动词短语如2025-06-15-choose-database.md。scripts/new_adr.js源码中的slugify()函数new_adr.js正是这套约定的程序化实现——它剥离引号、将非字母数字字符替换为连字符、合并连续连字符并去除首尾连字符确保文件名可预测。脚本还通过detectStrategy()检测目录中已有文件是否带日期前缀new_adr.js自动延续既有命名策略。Quick Scoring快速打分不是关卡而是对话工具清单为评审提供了简单的计分规则全部勾选可以定稿Ship it1–3 项未勾选与人类讨论缺口大部分一分钟内可修复4 项及以上未勾选ADR 需要更多工作回到 Phase 1 处理模糊区域。清单特别强调这不是关卡而是对话工具This isnt a gate — its a conversation tool。这意味着计分结果的作用是定位问题、开启讨论而不是机械地阻止合并。在 Phase 3 的实际使用中SKILL.md 还要求评审结果以摘要形式呈现而非罗列全部复选框格式为✅ 通过项 / ⚠️ 发现的缺口 / 建议Ship it / Fix the gaps first / Needs more Phase 1 work且只呈现失败项与显著优点并提出具体修复建议而非单纯标记问题。Common Failure Modes八种常见失败模式速查表清单末尾用一张症状-根因-修复的三列表格汇总了 ADR 写作中最常见的八种失败模式这是评审时最实用的对照工具症状根因修复后果写成提升性能意图模糊追问提升哪个指标、提升多少、如何测量只列一个方案决策已定、ADR 事后补写追问你否决了什么、为什么——把推理过程记录下来上下文读起来像方案宣讲跳过了问题定义把上下文改写成问题陈述把方案移到 Decision 节后果全是正面选择性呈现追问什么变难了维护成本是什么我们决定用 X但没有为什么缺少论证追问为什么选 X 而不是 Y——而不是 Y 迫使进行对比实现计划写更新代码过于抽象追问哪些文件、哪些函数、什么模式验证标准写能工作不可测试追问你会运行什么命令来证明它能工作未列出受影响路径实现计划含糊其辞Agent 应扫描代码库并提出具体路径这张表可以当作评审时的提问脚本每遇到一个症状就按修复列的追问句式深挖一层。例如评审examples.md中短版示例的 Verification 时可以看到作者把测试通过拆解成了DB_ENGINEsqlite与DB_ENGINEpostgres两条命令、一条 grep 检查、一条 CI 时长上限和一条接口导出检查——这正是针对验证标准写能工作这一失败模式的对症下药。在仓库中实践从模板到脚本的完整工具链评审清单不是孤立文档它处于 adr-skill 的完整工具链末端。理解整条链路有助于在评审时判断一份 ADR 是否沿用了正确约定模板选择template-variants.md决策直接、候选方案 1–2 个时用 adr-simple.mdContext → Decision → Consequences → Implementation Plan → Verification需要记录多方案结构化权衡时用 adr-madr.md在 simple 基础上增加 Decision Drivers、Considered Options、Pros and Cons of the Options 等节。判断信号包括真实方案数量、受影响团队规模、可逆性、预期寿命、是否需要干系人评审。脚本支撑SKILL.md 的 Script Usage 一节创建 ADR 首选new_adr.js它自动完成目录检测、命名策略检测、模板渲染与索引更新状态变更用set_adr_status.js仓库尚无 ADR 时用bootstrap_adr.js一键初始化目录、索引与第一份采用 ADR决策。典型用法# 简单 ADR 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 # 生成后自动更新索引 node /path/to/adr-skill/scripts/new_adr.js --title Choose database --status proposed --update-index # 为无 ADR 的仓库引导初始化 node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions所有脚本均支持--json输出机器可读结果便于 CI 或其他 Agent 消费。真实参照本仓库已按此约定建立了 contributing/decisions/ 目录其中 2026-03-11-adopt-architecture-decision-records.md 是一份accepted状态的真实 ADR从文件名日期前缀 动词短语、YAML front matterstatus/date/decision-makers到 Context/Decision/Consequences/Alternatives Considered 的章节组织都严格遵循了上述约定可作为评审时对照的标准答案。目录级 README 则充当索引按清单要求维护每份新 ADR 一个列表项的更新习惯——这一步也可交给new_adr.js --update-index自动完成。结语把评审清单嵌入你的 Agent 工作流ADR 评审清单的本质是把文档可读这一主观感受转译为一组可勾选、可计分、可对话的客观检查项其终极判据只有一个编码 Agent 能否零追问地开工实现。将这份清单纳入 Phase 3 的强制环节配合快速打分规则定位缺口、借助八种失败模式速查表引导追问再以仓库的模板、脚本与真实 ADR 为参照就能把 ADR 从记录历史的文档升级为驱动 Agent 的规格。对于正在用 AI Agent 协作开发的团队这是一套低成本、高杠杆的质量基础设施——先在本仓库的 review-checklist.md 与 SKILL.md 中消化完整流程再在下一个架构决策上付诸实践即可。【免费下载链接】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),仅供参考
返回列表