AI 开发流程经验

superpowers + headless + 强制人工验收 · 通用实践
计划先行探针优先隔离审查实时勾选ADR

一句话:让 AI 高速产出,用"隔离验证"兜底正确性。AI 写得快、覆盖广,但对自己的盲点不可见;流程的价值不在让 AI 更聪明,而在每一步都有独立于实现者的闸门(契约、测试门禁、人工 runbook、独立 reviewer)。

1. 整体流程

三层嵌套:项目级(一次性,出整体设计文档)→ 每个 Sprint(出 2 周规划摘要,拆成多个 plan)→ 每个 Plan(④ 编写 spec/design → ⑤ DoR 就绪门 ★ → ⑥–⑨ 循环)。详细 spec/design 在进每个 plan 时产出(just-in-time),sprint 文档只给摘要。

2. writing-plans:把计划写成可执行、可验收、可续接

计划是后续一切的脚手架。所有计划相关的纪律都在这一节。顺序很关键:先探查、过 DoR 就绪门(产 spec/design)、再拆分、每步带测试与验收,把正确性前置到计划阶段。

🙋 需要人参与的环节(不可全交给 AI):

探查结果研判(对应 ①):探针跑完,由人确认事实文档(真实端点/字段/坑)可信、足以支撑写计划——不让 AI 拿不确信的"实测"就开写。
DoR 过门研判(对应 ②):由 owner / 独立评审者判 8 项是否真就绪(无静默 TBD、外部依赖已实测、对外契约已过"第一个消费者")——机器自评不算就绪,过门才进 tasks。
争议设计拍板 → ADR(对应 ⑥):地基级 / 有争议的设计由人决策并落 ADR,不让 AI 自决。
计划评审批准(进入执行前):计划成稿后人逐项对 spec/design 审——覆盖完整、拆分粒度合适、无占位符、runbook 可照抄跑;批准后才进入执行。

其余步骤——③ 拆分、④ 每步 TDD、⑤ 生成 runbook、⑦ 全绿门禁——确定性高,可由 AI / headless 无人值守完成。⑤ 的 runbook 是写计划时由 AI 生成的产物(不需人参与);它"由人照着跑验收"发生在 §4 隔离审查,不在本阶段。

① 探查优先(写计划之前):不把猜的 API 写进计划。未知外部依赖先起真服务、跑通最小链路,把真实端点/字段/响应/坑记成事实文档,后续实现以实测为准。实战中探针常当场逮到外部系统的鉴权/寻址坑——等集成阶段才撞,排查成本翻倍。
② DoR 就绪门 + spec/design 拆分(进 tasks 之前 · superpowers:writing-specs):写步骤前先产独立 spec.md(需求)+ design.md(设计),过一道 DoR 就绪门——8 项每项三态之一(已决定 / 显式推迟+理由 / 待探查+探针+决策规则),无静默 TBD:①范围出口 ②接口契约(对外契约冻结前过"第一个消费者":UI→低保真原型 / 程序→SDK·样例;纯内部豁免)③数据模型 ④外部依赖探查事实(实测成文)⑤行为·边界·并发·威胁 ⑥NFR(安全/隔离/性能/parity/拓扑)⑦验收与测试策略(runbook)⑧关键决策留痕(ADR)。详细设计 just-in-time 进每个 plan(sprint 文档只给摘要;事实/探针/原型在进 plan 那刻才存在,前置=瀑布+漂移)。需求(spec)与设计(design)分开,可独立把关质量。
③ 任务级 checkbox 拆分:每个任务/步骤 - [ ],粒度到"可单独勾选/验证"(bite-sized:写测试 / 跑红 / 实现 / 跑绿 / 提交各一步)。
④ 每步 TDD:先写测试(红)→ 最小实现(绿)→ 重构;无测试不合并。
⑤ 必含手动验收 runbook:可照抄的命令序列 + 每步期望证据,让人不读代码也能复现验收。由 AI 在写计划时生成(不需人参与);无 runbook 的计划不算完成,§4 再由人照着跑做验收。
⑥ 有争议的设计 → 落 ADR:正文永远是最新版,决策理由与历史进 ADR + git。
⑦ 全绿门禁:每个任务结束跑项目的测试/lint/构建全绿才进下一步;失败先系统化调试定位根因,不打补丁猜。
贯穿全程 · 实时更新状态:每完成一步即勾 - [x] + 同步任务跟踪(in_progress/completed)——进度随时可见、可中断可续;不做完一批才补勾(无人值守跑完忘回填是典型反例)。

一句话:把探针、DoR(spec/design)、checkbox、TDD、runbook、ADR、全绿门禁都前置进计划,正确性在计划阶段就可检验,而不是堆到最后。

3. 执行:交互 vs headless

	交互	headless(无人值守)
适合	有未知判断、探索性	计划已审定、确定性高
中途纠偏	能(实时可打断)	不能(只能 kill)

headless 三个要点(踩坑换来的)

订阅模式:脚本先 unset ANTHROPIC_API_KEY,否则走 API 计费报 Credit balance too low;shell 启动文件里硬编码的 key 要注释掉。
流式 + 落日志:claude -p --verbose --output-format stream-json | tee log;另开 tail -f 或 watch git log(每任务一 commit)看进度。
合并前停:headless 跑完只 push + 自评,合并留给人。

headless 的"自评 review"不算数 → 必须叠加 §4 隔离审查。

4. 核心:机器自评 ≠ 验证

一次 headless 自主跑完整批任务、自己跑了一轮 code review、单元 + 集成全绿——看起来"完成了"。但合并前的隔离审查仍逮到两个会进生产的真 bug,共同点是:都在实现者没设想到的边界路径上,应有的正确行为压根没实现。

一个由独立 reviewer 子代理发现:输入残缺(缺关键字段、无法判定归属)时,代码没有按"安全地拒绝"(fail-closed)处理,而是走进未定义路径、给出错误结果。
一个由人手动跑 runbook发现:重复 / 冲突的操作没被识别,这条路径根本没有对应处理,行为偏离预期。

重点不在"崩没崩",而在"该发生的正确行为缺失、且没被验证"。两个都是真 bug,可自动测试 + 机器自评全没逮到,根因是:

测试是实现者自己写的,只覆盖实现者想到的路径 → 天然盲于实现者的盲区;
测试数据回避了边界:用随机唯一值永不触发"重复 / 冲突",用假对象不模拟"残缺 / 异常" → 出错的那条路径永远没被走到;
机器审自己的代码 → 复用同一套假设,看不见自己没设想的情况。

结论:计划"完成" ≠ 通过。合并前必须两道独立于实现者的审查,它们的价值正是去走实现者没设想到的路径:
① 人:照 runbook 手动验收 + 对照 spec 逐项核,用真实、会撞边界的数据(机器不替代)。
② 独立 reviewer:派非实现者的子代理审本次 diff(main..HEAD),不带实现者的假设。
这两道闸把那两个 bug 挡在合并前。

5. 决策纪律

有争议的设计 → ADR:正文为最新版,理由/历史进 ADR + git。
地基级改动 → 先批判后批准:动手前用架构顾问做 blast-radius 分析,确认是真需求还是偏好。实战中这一步避免了一次"中途重开已交付地基"的返工——结论是不拆地基,把新能力留作上层叠加。
契约优先:对外契约是稳定面;不裸传/暴露底层系统,在其上加一层薄适配(投影 + 鉴权 + 隔离)。

6. 反模式清单

反模式	正解
headless 跑完 = 完成	必过人工 runbook + 独立 reviewer
机器审自己的代码当审查	隔离审查(独立子代理 / 人)
把猜的外部 API 写进计划	探针优先,实测钉死
测试用随机唯一名 / 假对象永不撞边界	加冲突/缺字段/越权等 fail-closed 用例
地基改动直接动手	先批判(blast radius)+ ADR
计划做完一批才补勾	实时勾选 + 任务跟踪
裸传底层系统的 API	自有契约 + 薄适配层

7. 上手清单(下个计划照做)

☐ brainstorm → spec 分节确认;争议 → ADR
☐ writing-plans:任务级 checkbox + 每步 TDD + 手动 runbook;不确定外部依赖 → 第一个任务设探针
☐ 执行:交互(有未知)或 headless(确定);实时勾选 + 全绿门禁
☐ 完成后:人跑 runbook + 独立 reviewer;修 Critical/Important
☐ CI 绿 → 人确认 → 合并 → 回标 spec/计划 checkbox