给 AI 定验收标准：vibe 项目的 Definition of Done 实战

先划边界，免得读串：站内有《给 AI 写需求：PRD 写作法》，讲的是"做什么"（需求怎么写清楚）；有《从 Demo 到生产：上线前检查清单》，讲的是"发布门禁"（上线那一刻要查什么）；有《AI 调试方法论》，讲的是"出问题了怎么办"；有 spec 驱动开发相关指南，讲的是"怎么做"。这篇都不讲——这篇只讲一件事：在任务开始前，就给 AI 写好"什么叫完成"的验收标准（Definition of Done），让它照着打勾，而不是做完之后你来猜它到底做没做完。

AI 的"做完了"，和你的"做完了"不是一回事

三个 vibe coder 天天遇到的场景：

• 你让 AI "加个导出 CSV 功能"，它说完成了。你一点，发现中文全是乱码——它只在英文数据上测过。
• 你让 AI "修一下移动端导航错位"，它说完成了。你一切到深色模式，错位又回来了——它没测主题切换。
• 你让 AI "接一下 Stripe 支付"，它说完成了。本地能跑，一上线 webhook 签名校验没配，支付回调全被拒——它觉得"调通沙盒"就是做完。

问题不在 AI 偷懒，而在于你们俩对"完成"的定义从来没对齐过，而且没人把它写下来过。AI 的"完成" = 代码写出来、没报错；你的"完成" = 边界测过、文档更新、不污染现有功能。DoD 就是把你的"完成"翻译成 AI 能执行的清单，任务开始前就摆在它面前。

DoD 五要素模板

每个任务卡的 DoD 都写这五块，多一个都嫌多，少一个都可能翻车：

1. 功能验收（必须可演示）。用"用户能…"的句式写，每条都能亲手点一遍验证。反例："优化导出功能"；正例："用户点击导出后，能下载包含 1000 行中文数据的 CSV，用 Excel 打开不乱码"。

2. 边界与异常。列出这个任务最可能翻车的 2–3 个边界：空数据、超长输入、网络失败、权限不足。AI 不写边界用例，十有八九是因为你没点名。

3. 测试证据。要求 AI 给出"做完的证据"：跑了哪条测试命令、输出是什么；UI 任务要截图或录屏。没有证据的"做完了"，一律按没做完处理。

4. 代码卫生。三条硬线：无新增 lint/类型报错；不引入新的全局状态或硬编码密钥；改动范围限定在任务描述的文件/模块里（AI 最爱"顺手"改不相关的文件）。

5. 文档与可观测。用户可见的行为变化要更新对应文档（README、更新日志或帮助页二选一即可）；关键流程加日志/埋点，方便以后排错。

模板长这样，直接复制用：

## DoD（完成标准）
- [ ] 功能验收：
  - [ ]（用户能…，可亲手验证）
  - [ ]（用户能…，可亲手验证）
- [ ] 边界与异常：（列 2–3 个，说明期望行为）
- [ ] 测试证据：（测试命令 + 输出，或截图/录屏）
- [ ] 代码卫生：无新增 lint/类型报错；改动范围限定在（模块）内
- [ ] 文档与可观测：（更新了哪份文档；加了哪条日志/埋点）

好坏任务卡对照：同一任务，两种写法

任务：给博客加个"复制代码"按钮。

差的写法（AI 自由发挥版）：

给文章页的代码块加个复制按钮。

AI 会给你一个能点的按钮，然后：长代码块复制不全它没测、复制成功没反馈用户不知道成没成、移动端按钮挡住代码它没看。

好的写法（DoD 版）：

给文章页的代码块加个复制按钮。
## DoD
- [ ] 功能验收：
  - [ ] 点击复制后，500 行代码块能完整复制到剪贴板
  - [ ] 复制成功后按钮变为"已复制 ✓"并在 2 秒后恢复
- [ ] 边界与异常：剪贴板 API 被拒绝时（如非 HTTPS），降级为选中代码文本并提示用户手动复制
- [ ] 测试证据：桌面 Chrome + 手机 Safari 各录一段操作视频
- [ ] 代码卫生：无新增 lint 报错；只改代码块组件，不动文章页其他逻辑
- [ ] 文档与可观测：README 的"写作指南"章节加一行说明

差别不在字数，在于好的写法把"你以为 AI 会想到的"全部写成了"AI 必须做到的"。vibe coder 最大的幻觉就是"这么明显它肯定会处理"——不，它不会，除非你写下来。

四类任务的 DoD 速查表

不同任务类型，DoD 的侧重点不同。收藏这张表，写卡时对着勾：

任务类型	DoD 侧重	必写的一条
UI/前端	多端多态验证	桌面 + 手机各截一图；深色/浅色模式各看一眼
后端 API	契约与异常	成功/参数错误/无权限三种响应的 curl 示例与实际输出
数据迁移	可回滚	写出回滚步骤并实际演练一遍；迁移前后各 count 一次对账
修 Bug	复现-修复-回归	先给出复现步骤，修复后用同一批步骤验证，并跑一遍相关旧测试

数据迁移那行值得多说一句：vibe 项目里 schema 迁移翻车极其常见，就是因为 DoD 里从来没写过"回滚"。让 AI 在动手前先写回滚步骤，相当于逼它先想清楚"搞砸了怎么 undo"。

嵌入你的工作流：DoD 闭环

DoD 不是写在纸上好看的，它要嵌进你和 AI 的每一次协作里。下图是完整闭环：

每一步的实操：

• 第 1 步写 DoD：任务描述后面直接跟五要素模板。任务越小越要写——小任务的 DoD 只有 3 行，写起来 1 分钟。
• 第 2 步喂给 AI：把 DoD 贴进 prompt，并加一句"开始前先用你自己的话复述一遍 DoD，确认理解"。这句复述能拦下 80% 的理解偏差，AI 复述错了你当场纠正，比它写完 500 行代码再返工便宜得多。
• 第 3 步 AI 编码：加一条铁律——"实现中遇到 DoD 没覆盖的不确定情况，先停下来问我，不要自己猜"。AI 最大的问题不是慢，是自信地猜错。
• 第 4 步 AI 自检：让 AI 对照 DoD 逐条打勾，每条后面贴证据（测试输出截图、curl 结果、改动文件列表）。见下一节的自检 prompt。
• 第 5 步人验收：你只花 10 分钟，按 DoD 逐条亲手验证一遍。通过才算 done。

想偷懒的话，把第 1 步的模板和第 2 步的"复述"要求写进 AGENTS.md，变成每个任务的默认动作：

## 任务完成标准（DoD）
每个任务开始前必须先有 DoD（功能验收/边界异常/测试证据/代码卫生/文档可观测
五要素），写在任务描述末尾。编码前先用自己的话复述 DoD；编码中遇到 DoD 未
覆盖的不确定情况必须停下来问；完成后对照 DoD 逐条自检并贴证据，无证据的条
目视为未完成。

AI 自检：让它先自己打勾

AI 写完代码说"搞定了"，别急着自己测。先甩给它这段自检 prompt：

对照本次任务的 DoD 逐条自检，输出格式：
- [x] / [ ] 条目原文
  证据：（测试命令+关键输出 / 截图 / 文件路径+行号）
  未通过原因：（如果没打勾，写清楚为什么）
诚实自检：不确定的条目标 [ ] 并说明，不要猜。

"不要猜"这三个字是精髓。AI 有强烈的"报喜"倾向，你不明确要求诚实，它会把"大概行"写成 [x]。自检报告里出现 [ ] 不是坏事——它把返工范围精确到了条目级，你修起来飞快。

进阶用法：让 AI 把自检报告存成 docs/dod-reports/<任务名>.md。攒上几十份，你就有了这个项目真正的"质量档案"：哪个模块老是边界没测、哪类任务返工最多，一目了然。

人的 10 分钟验收流程

AI 自检完，轮到你。10 分钟，按这个顺序走：

1. 看自检报告（2 分钟）。先看有没有 [ ] 项，有就直接打回，不用往下测。
2. 跑主流程（3 分钟）。按 DoD 功能验收条目亲手点一遍，别只看截图——截图可以是旧的。
3. 怼一个边界（2 分钟）。挑 DoD 里你最不放心的那个边界，亲手试一次。空数据、超长输入、断网，随便挑一个。
4. 看 diff（3 分钟）。git diff 扫一遍：有没有动不该动的文件？有没有硬编码的密钥、URL、魔法数字？有没有删掉别人的代码？

第 4 步最容易被 vibe coder 跳过，但 AI"顺手改文件"是返工和线上事故的最大来源。养成习惯：diff 里出现任务描述之外的文件，先问为什么。

DoD、PRD、用户故事：三者的分工

很多人问：有了 PRD 还要 DoD 干嘛？分工其实很清楚：

• PRD 回答"做什么、为什么做"。面向人和规划，一份 PRD 覆盖一个功能甚至一个版本。
• 用户故事回答"谁、在什么场景、要什么"。是需求的表达格式。
• DoD 回答"做到什么程度算完"。面向执行，一个 DoD 只管一个任务（通常是半天到两天的工作量）。

协作链条是：PRD 拆成任务 → 每个任务配 DoD → AI 按 DoD 执行 → 人按 DoD 验收。PRD 保证"做对的事"，DoD 保证"把事做对"。站内《给 AI 写需求：PRD 写作法》管的是前半段，这篇管的是后半段，两篇合起来才是完整的 AI 协作链。

完整实战：从任务卡到验收走一遍

拿一个真实小任务演示全流程：给更新日志页加个 RSS 订阅按钮。

第 1 步：写任务卡 + DoD（你，5 分钟）。

任务：在 /changelog 页右上角加 RSS 订阅按钮，点击复制 RSS 链接。
## DoD
- [ ] 功能验收：
  - [ ] 点击按钮后 RSS 链接复制到剪贴板，按钮变为"已复制"
  - [ ] RSS 链接在浏览器打开能看到合法的 XML（含最近 20 篇更新日志）
- [ ] 边界与异常：RSS 为空时按钮置灰并提示"暂无内容"；复制 API 被拒时降级为选中链接文本
- [ ] 测试证据：桌面 + 手机各一张截图；curl 一次 RSS 地址贴出前 5 行
- [ ] 代码卫生：无新增 lint 报错；只改 changelog 相关文件
- [ ] 文档与可观测：README 加一行 RSS 说明

第 2 步：喂给 AI + 复述（你 + AI，2 分钟）。prompt 里加上："开始前用你自己的话复述 DoD"。AI 复述："…RSS 为空时按钮置灰…"——你发现它漏了"复制 API 被拒"的降级，当场补上。一次 30 秒的纠正，避免了一次返工。

第 3 步：AI 编码（AI）。它按 DoD 实现，遇到不确定的停下来问你："RSS 链接用绝对地址还是相对地址？"——你回"绝对地址"，它继续。这就是 DoD 铁律"不确定先问"的价值。

第 4 步：AI 自检（AI，3 分钟）。它输出：6 条 [x]，每条贴了证据——截图两张、curl 输出、改动文件列表。你扫一眼，发现"手机截图"那条证据是桌面浏览器开窄窗口模拟的，不是真机。你在验收时就知道要亲手在手机上点一次。

第 5 步：你验收（10 分钟）。按流程走：自检报告有疑点 → 亲手在手机上点 → 怼一个边界（把更新日志删空看按钮是否置灰）→ 看 diff。全部通过，merge，任务卡归档。

整个流程你投入了不到 20 分钟，换来的是"一次做对"。没有 DoD 的版本通常是：AI 说做完了，你随手点一下好像行了，三天后用户反馈 RSS 在手机上复制不了，你再开一轮返工——总耗时只多不少。

模板库：四套 DoD 直接复制

存进 .ai-templates/dod/，新任务复制一份改两行：

UI 组件任务：

- [ ] 功能验收：桌面 Chrome + 手机 Safari 各一截图；深色/浅色模式各看一眼
- [ ] 边界与异常：空数据、超长文本、加载失败三种状态都有对应 UI
- [ ] 测试证据：截图 2 张；交互录屏 1 段（如有动效）
- [ ] 代码卫生：无新增 lint/类型报错；样式走设计系统 token，不写死色值
- [ ] 文档与可观测：组件用法写进 Storybook 或 README（三行即可）

后端 API 任务：

- [ ] 功能验收：成功 / 参数错误 / 无权限三种情况的 curl 命令与实际输出
- [ ] 边界与异常：必填参数缺失、非法枚举值、并发重复请求（幂等）
- [ ] 测试证据：新增或更新的自动化测试及运行输出；Postman/curl 实测记录
- [ ] 代码卫生：无新增 lint/类型报错；错误码走项目错误码表，不新造
- [ ] 文档与可观测：API 文档更新；关键分支有日志（含请求 id）

数据迁移任务：

- [ ] 功能验收：staging 环境完整跑一遍；迁移前后行数 count 对账一致
- [ ] 边界与异常：回滚步骤写出来并实际演练一遍；迁移失败时的告警方式
- [ ] 测试证据：staging 迁移日志；对账 SQL 与结果；回滚演练记录
- [ ] 代码卫生：迁移脚本可重入（失败重跑不产生脏数据）；生产执行前 double check
- [ ] 文档与可观测：迁移记录写进运维文档；迁移过程有进度日志

修 Bug 任务：

- [ ] 功能验收：先给出复现步骤，修复后用同一批步骤验证通过
- [ ] 边界与异常：同类场景回归（如修了 A 表单的校验，B 表单同类字段也测一遍）
- [ ] 测试证据：复现步骤文档；修复前后对比截图/录屏；相关旧测试全跑一遍
- [ ] 代码卫生：无新增 lint/类型报错；修的是根因不是症状（写出一句话根因说明）
- [ ] 文档与可观测：根因一句话记进 bug 档案；该加的日志加上

"修的是根因不是症状"那条是修 bug 任务的灵魂：让 AI 写出一句话根因说明，逼它证明自己真的理解了 bug，而不是把报错按下去而已。

给 solo vibe coder 的极简版 + 怎么知道它在起作用

如果你觉得五要素太重，先用极简三行版，1 分钟写完：

## DoD
- [ ] 能亲手验证：（一句话说清用户能做什么）
- [ ] 边界：（最可能翻车的一个场景 + 期望行为）
- [ ] 证据：（截图 / 测试输出 / curl 结果，三选一）

三行版覆盖了 DoD 80% 的价值：可验证、想边界、要证据。等你尝到甜头，再自然过渡到完整五要素。

怎么知道 DoD 在起作用？看两个数：返工率（任务 merge 后一周内因为"没做完"被 reopen 的比例）和验收时长（你亲手验收一个任务的平均分钟数）。上了 DoD 的团队，返工率通常在两周内腰斩——因为"没做完"在 AI 自检那一步就被拦下了，根本到不了你这里。验收时长也会从"漫无目的地乱点 30 分钟"变成"照单打勾 10 分钟"。这两个数不用精确统计，凭感觉都能察觉变化。

五个常见坑

坑 1：DoD 写得比代码还长。DoD 是清单不是论文。一个小任务的 DoD 超过 10 行，就是写劈叉了——拆任务，而不是 lengthen DoD。

坑 2：写了 DoD 但验收时不用。最常见的死法：DoD 写完，验收时凭感觉点两下。仪式感要有：打开 DoD，一条一条勾，勾完才 merge。

坑 3：DoD 里写"性能良好""体验流畅"。这种没法验证的词等于没写。改成可测量的："列表 1000 条时滚动不掉帧""首屏加载 < 2s（4G 模拟）"。

坑 4：每个任务都从零写 DoD。把常用任务的 DoD 存成模板（UI 组件、API 接口、迁移、修 bug 四套），新任务复制一份改两行就行。模板在 .ai-templates/dod/ 里放着，比每次现写快十倍，也让团队每个人的 DoD 口径保持一致。

坑 5：把 DoD 当成只给 AI 看的。你自己亲手写的代码（比如 AI 生成后你手工改的那几行）同样要过 DoD。标准面前，人和 AI 一视同仁，否则 DoD 很快就没人当真了。

最后说一句大实话：DoD 不能保证 AI 一次写对，但它保证错得明白、改得精确。以前你返工时要说"这里不对、那里也不对"，现在你说的是"DoD 第 3 条没过，证据呢？"——协作成本从"玄学"变成了"清单"。对靠 AI 写代码的人来说，这就是从"碰运气"到"有工程"的分水岭。从下一个任务开始试试：花 5 分钟写 DoD，让 AI 复述、自检、贴证据，你会发现"做完了"这三个字第一次有了统一的含义。