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 Record，ADR）在传统团队中常用于沉淀"为什么这样设计"的决策过程，但在 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-sqlite3@11.x与@types/better-sqlite3@7.x（devDependencies），模式包括"所有数据库访问经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 能写测试或运行命令来检查"的典型体现。

Options（MADR 模板）：候选方案

仅在使用 MADR 模板时适用，共四项检查：

至少有两个方案被真正考虑过（不是"做某事"对比"什么都不做"）；
每个方案都有真实的优点和缺点（不是稻草人对比）；
选中方案的论证引用了具体的驱动因素或权衡；
被否决的方案解释了为什么被否决，而不只是"是什么"。

仓库的 2026-03-11 决策是极佳范例：它在 Alternatives Considered 中列出了"无正式记录""Wiki 或 Notion 页面""轻量级 RFC"三个候选，并逐一给出否决理由——"上下文丢失、决策被反复重议""与代码脱节、不受版本控制""对大多数决策而言过重"。这种写法保留了决策过程的推理链，使后来者（包括 Agent）无需重走一遍讨论。

Meta：元信息

共五项检查：

Status 设置正确（新 ADR 通常为proposed）；
Date 已设置；
决策者已列出；
标题是描述决策的动词短语（而非描述问题）；
文件名遵循仓库约定。

关于文件名约定，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 it）；
1–3 项未勾选：与人类讨论缺口，大部分一分钟内可修复；
4 项及以上未勾选：ADR 需要更多工作，回到 Phase 1 处理模糊区域。

清单特别强调"这不是关卡，而是对话工具"（This isn't a gate — it's 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_ENGINE=sqlite与DB_ENGINE=postgres两条命令、一条 grep 检查、一条 CI 时长上限和一条接口导出检查——这正是针对"验证标准写'能工作'"这一失败模式的对症下药。

在仓库中实践：从模板到脚本的完整工具链

评审清单不是孤立文档，它处于 adr-skill 的完整工具链末端。理解整条链路有助于在评审时判断一份 ADR 是否沿用了正确约定：

模板选择（template-variants.md）：决策直接、候选方案 1–2 个时用 adr-simple.md（Context → 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 matter（status/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 中消化完整流程，再在下一个架构决策上付诸实践即可。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析