把 AI 接进开发流程，失败的常见原因不是模型不够强，而是人把不可审查的环节当成了可审查的环节。需求没写清就让它开工，它写完后你只能读 500 行 diff 去猜它想干什么。
这套流程的核心只有两条：计划必须先被人看过，实现必须分步可验证。
1. 四种角色与各自的可信度
同一个模型在不同环节的可靠程度差别很大，混为一谈就会用错地方。
| 角色 | 它产出什么 | 可信度 | 人的动作 |
|---|---|---|---|
| 需求澄清助手 | 追问、列举歧义点、反例场景 | 较高（它擅长指出漏洞） | 逐条回答，把回答写进需求 |
| 设计草案生成 | 方案对比、接口草案、数据模型 | 中（方案合理但缺项目背景） | 人工选择并补约束 |
| 实现执行 | 具体代码、配置、脚本 | 中偏下（细节失误多） | 必须验证 |
| 审查与测试生成 | 边界用例、检查清单、负向用例 | 中（查不到"为什么"层面） | 挑出可执行的，丢弃泛泛的 |
用法上有个反直觉的结论：让它当审稿人比让它当作者更划算。同一段逻辑，让它生成往往有边界遗漏；让它审一段已有代码，它挑出的空对象、异常吞掉、缺超时这类问题命中率明显更高。
2. 一条可执行的工作流
1) 写清需求与验收标准 ← 人主导，AI 只做追问
2) 让它先出计划（不动代码） ← 只允许读仓库、列步骤
3) 人工确认计划 ← 砍范围、定顺序、指定验证命令
4) 分步实现 ← 一步一个可运行改动
5) 每步验证 ← 跑指定命令，看输出
6) 汇总审查 ← 通读全部 diff，确认无夹带
一次完整的第 2 步输入长这样：
只做计划，不要改任何文件。
需求：订单支持部分取消，取消数量可以小于订单总量。
给出：
1. 涉及的文件与类（用 rg 找到真实路径，不要猜）
2. 分几步做，每步能编译、能独立验证
3. 每步的验证命令与预期输出
4. 你不确定、需要我确认的点
注意"用 rg 找到真实路径，不要猜"这句：计划阶段最容易出现的失误，是它凭目录直觉写出不存在的文件路径，而后面所有步骤都基于这个错误前提。
3. 为什么"先出计划"是关键
| 计划 | 实现 | |
|---|---|---|
| 体量 | 十几行 | 几百行 |
| 审查成本 | 读一遍 2 分钟 | 逐行读 + 跑，看情况 |
| 发现问题时 | 改一句话 | 全部返工 |
| 暴露歧义 | 是 | 否（歧义被代码固化） |
结论：计划是可审查的，实现是不可审查的。人在实现阶段只能做"验证"，做不了"审阅"——你没有精力逐行判断 300 行里的每一处设计选择。
计划里必须出现的三样东西：
- 真实文件路径（检索得到，不是推测）；
- 分步顺序（哪一步先，为什么）；
- 验证方式（命令 + 预期输出）。
缺第 3 项的计划等于没计划，因为无法判断"做完了没有"。
4. 任务拆分的粒度
| 粒度 | 表现 | 判断 |
|---|---|---|
| 太粗 | "实现部分取消功能" | 无法验证，diff 一大片 |
| 合适 | "给 OrderService.cancel 增加 quantity 参数并校验，测试用例 X 通过" |
能编译、能跑、能回退 |
| 太细 | "改第 42 行的变量名" | 往返开销大于收益 |
判断标准只有一条：这一步结束后能否跑一条命令判断对错。能，就是合适粒度；不能，就再拆或再合。
一条经验：单个改动涉及文件数超过 3 个，通常可以再拆（典型量级，按你项目单文件规模核对）。
5. 验收标准怎么写
验收标准是这次任务唯一的"评分规则"，写虚了就全盘失效。
| 虚的写法 | 可判定的写法 |
|---|---|
| 体验良好 | 接口在 200 条并发下错误率 0（按你的压测口径核定阈值） |
| 处理好异常 | 下游返回 500 时接口返回 {"code":50301}，不抛栈 |
| 性能优化 | 同一输入下 SQL 从 N 次降到 1 次，用 EXPLAIN 确认 |
| 兼容旧数据 | amount 为 null 的老订单走 ERR_LEGACY_ORDER 分支 |
| 代码规范 | ./mvnw spotless:check 通过 |
写验收标准时反复问一句：这句话能用一条命令或一个断言表达吗？ 不能就重写。
【验收】
- 命令：./mvnw -q test -Dtest=OrderPartialCancelTest
- 预期：5 passed；其中 quantity > 剩余量 的用例返回 400 + code=40012
- 回归：./mvnw -q test -Dtest=OrderCancelTest 保持 3 passed
6. 自我检查机制
不要问"你确定吗"，要它跑指定命令并贴输出。
现在执行以下检查并把原始输出贴出来，不要复述结论：
1. ./mvnw -q -DskipTests compile
2. ./mvnw -q test -Dtest=OrderPartialCancelTest
3. git diff --stat
若第 2 条失败，贴完整堆栈的前 20 行。
更进一步是"对比预期输出"：
这段解析逻辑的输入输出对：
输入 "a,b,,c" → ["a","b","c"]
输入 "" → []
输入 "a,,,b, c " → ["a","b","c"]
先写出预期的断言，再实现，最后跑给我看。先写断言能防止它把实现迁就成测试。
"先写断言再实现"这一条挡住了最常见的偷懒路径：改测试以让代码通过。
7. 失败回退
跑偏时不加提示继续堆补丁，是成本最高的处理方式。正确做法是回到上一个已验证点。
# 1. 先看清偏了多少
$ git status --short && git diff --stat
# 2. 未提交：直接丢弃这部分改动
$ git stash push -m "ai-wip-order-partial"
# 3. 已提交但还没推：硬回退到上一个验证点
$ git reset --hard HEAD~1
# 4. 回退后重新描述任务，把导致跑偏的那句话改掉
判断该不该回退的三个信号：
| 信号 | 含义 | 动作 |
|---|---|---|
| diff 里出现你没要求的文件 | 它扩大了范围 | 回退，明确边界重来 |
| 它开始改测试 | 实现被迁就 | 回退，要求先写断言 |
| 连续两次修复引入新问题 | 前提就错了 | 回退，重写计划 |
第 3 条的关键：连续两轮修不好，问题一定在需求描述或计划，不在提示词措辞。继续调措辞只是重复消耗。
8. 人的位置
| 环节 | 谁做 | 理由 |
|---|---|---|
| 定验收标准 | 人 | 标准就是取舍，取舍不能被生成 |
| 方案选择 | 人（AI 只给候选） | 需要项目历史与团队约束作为前提 |
| 写代码 | AI 为主 | 可验证，错了能重来 |
| 跑验证 | 人复核 AI 的结果 | 它说跑过不等于跑过 |
| 不可逆操作 | 人 | 迁移、删除、发布、--force 推送 |
| 最终合入 | 人 | 责任在人不在工具 |
不可逆操作清单值得单独写在 AGENTS.md 里：
## 禁止 AI 直接执行
- 任何 `DROP` / `TRUNCATE` / 无 WHERE 的 `UPDATE` / `DELETE`
- `git push --force`、`git reset --hard` 到已推送的历史
- 生产环境部署、重启、扩缩容命令
- 修改 `application-prod.yml` 与数据库迁移脚本
以上操作只允许生成脚本内容，由人审阅后手动执行。
9. 团队协作
| 事项 | 写法 |
|---|---|
| 提交信息 | 写清"做了什么 + 怎么验证的"，例：feat(order): 支持部分取消（test: OrderPartialCancelTest 5 passed） |
| PR 说明 | 分"生成的改动"与"人工修改的部分"两栏 |
| 标注 | 大段生成代码在 PR 描述里注明来源与已验证范围，便于评审者决定读到什么深度 |
| 评审重点 | 标注过的部分重点看错误分支与边界；人工部分按常规 |
标注的价值不是合规，是分配评审注意力。一个 400 行的 PR，如果标出"其中 350 行是生成的脚手架，逻辑集中在 OrderService.cancel 的 40 行"，评审者就知道往哪看。
反过来，无差别标注"本 PR 含 AI 生成内容"等于没标——它不减少任何阅读量，只会让评审者放弃判断。
10. 排错：工作流跑不动的情况
| 现象 | 原因 | 处理 |
|---|---|---|
| 一次改了十个文件 | 没定范围，或计划里没写边界 | 拆成多轮，每轮声明"只改 X，其他只读" |
| 反复问同样的澄清问题 | 验收标准写得太虚，它无法据此决策 | 把标准改成可断言的句式 |
| 说改好了但测试没过 | 它只跑了编译，或没跑 | 固定要求"贴命令与输出" |
| 越改越乱 | 前提错误却持续打补丁 | 回退到上一个验证点，重写计划 |
| 计划里的路径不存在 | 它凭直觉推测目录结构 | 计划阶段强制要求用 rg/glob 检索 |
| 每个模块都要重新交代背景 | 约定没落进 AGENTS.md |
把重复出现的约束沉淀到项目级文件 |
最后一条是这套流程的长期收益所在：每一次纠正都应该变成一条约定，否则同类错误会在每个新任务里复发。
11. 边界：这套流程管不到的地方
| 场景 | 流程的作用 | 局限 |
|---|---|---|
| 清楚的增量需求 | 效果最好 | 无 |
| 需求本身在探索 | 只能用于"验证假设" | 需要人来定义探索方向 |
| 架构级改造 | 可用于拆步骤 | 方案取舍必须人做 |
| 遗留代码库（无测试） | 先补测试再让 AI 改 | 补测试本身就是大工程 |
| 强合规/审计场景 | 流程可用于留痕 | 验证责任人仍需人工承担 |
一句话：这套流程放大的是已经清楚的意图，不是替你产生意图。
12. 自测
- 为什么说"计划可审查、实现不可审查"？这决定了流程里的哪一步不能省？
- 任务拆分粒度的唯一判断标准是什么？
- 验收标准从"虚"改到"可判定"，改的是什么？
- 让它自我检查时，为什么"先写断言再实现"能挡住一类偷懒？
- 哪些信号说明该回退而不是继续加提示？
- PR 里标注"哪段是 AI 生成"真正的作用是什么？