大部分”AI 帮我做功能”故事都以”80% 完成、最后 20% 永远完不成”收尾——因为 spec 是在代码里偷偷被写出来的，agent 一路在猜、一路猜错。修法在上游：写一页 spec、逼 AI 把它的歧义挖出来、拆成每个都有真正验收测试的 ticket、再一个一个 ticket 上线。这是把”agent demo 看起来真不错、但我真正的功能卡住了”变成”功能真上线了”的工作流。
这篇主要解决什么问题
半成品陷阱：agent 看起来把功能做完了，你开心地演示，接下来一周陆续发现 spec 没盖到的边界、AI 静悄悄加进来的范围扩张、能过但不真正测新行为的测试。这个工作流把”隐式 spec”路径在后段慌忙买单的严谨，预付到前段。
这篇适合谁看
独立开发、原型开发、deadline 压力下做功能的开发者。如果你已经上线 2-3 个 AI 做的功能，并发现它们全都需要一次”比第一次还长”的二次过——特别相关。琐碎功能（一个函数 + 一个验收测试）不必这么搞——开销不划算。
什么时候适合用
功能大到需要一页 spec——一般是动 3+ 个文件、多个 endpoint、或者带分支的 UI 流程。Deadline 压力让你想跳过规划（“让 agent 直接写”）时。被”demo 漂亮、上线翻车”咬过几次之后。
什么时候不建议用
spec 还不存在的纯研究 / 探索任务。先做原型学一下”能做什么”，再从学到的内容里归纳 spec。在探索性工作上强行 spec-first 会制造虚假清晰，把你从学习中带偏。
开始前准备
- 有一个具体的 user story：谁在做什么、为什么、成功长什么样。模糊故事产出模糊 spec。
- 对代码库要熟到能预测会动哪几个文件。AI 会猜，你的活是纠偏。
- 选代码推理强的模型：Claude Sonnet 4.6 / Opus 4.7+ 或 GPT-5.5。小模型抓不到”spec 里没写的”那条 prompt 的意图。
- 开 AI 之前先建 feature 分支和草稿 PR。PR 描述就是 spec 的家。
具体步骤
- 先写 spec。 一页：user story、验收准则、边界情况、明确”不做”的部分。“不做”是被跳过最多、价值最高的一节。
- 粘给 AI。 让它：“列出这份 spec 的歧义和缺失细节。先不写代码，只问问题。“想要的输出像：“如果用户上传 50MB 图片会怎样？匿名上传允许吗？rate-limit 的错误 UX 怎么处理？”
- 按 AI 揭示的缺口修 spec。 这是整个任务最高杠杆的 10 分钟。现在的每一处歧义，将来都是半天返工。
- 把 spec 拆成 ticket。 问：“把这份 spec 拆成 5-8 个可实现 ticket。每个给：标题、可能动的文件、一句话的验收测试。”
- 一次实现一个 ticket。 把 ticket 连同完整 spec 给 agent。每个做完跑验收测试。通过就 commit；不通过就修完再走下一个。
- 所有 ticket 做完跑集成测试。 把完整 spec 的验收准则当集成测试。不通过不上线。
- 拒绝范围扩张。 AI 建议”顺便处理 X”时回头看 spec。spec 里没 X 就推迟到 follow-up。“顺手做一下”是功能 3x 估时的真正原因。
Spec 模板范例
# Feature：<名字>
## User story
作为 <角色>，我想 <动作>，以便 <结果>。
## 验收准则
- [ ] 准则 1（具体、可测）
- [ ] 准则 2
- [ ] 准则 3
## 边界情况
- X 时会怎样
- Y 时会怎样
## 不在范围内（明确不做）
- 功能 A（推迟）
- 功能 B（另一个 ticket）
## 数据模型改动
<schema diff 或"无">
## API 变化
<endpoint 变化 或"无">第一次实操怎么跑
挑一个最近上线、但有范围扩张或晚发现边界情况的功能。回头补写它本该有的一页 spec。跟实际做的对比。差距就是你的”spec 纪律”学习材料。然后在下个真功能上跑这个流程，量一下：写 spec 是净省时间还是觉得 overhead？大多数开发者在第 2 个功能上看到盈亏线。
完成后检查
- Spec 是不是一页装得下？装不下 = 拆功能、或者验收准则太啰嗦。
- AI 揭示的是真歧义，还是”你考虑错误处理了吗”这种通用提示？通用 = 你 spec 太薄或 prompt 没逼住。
- Ticket 是不是干净映射到 spec 的节？一个 ticket 跨两节 = 它其实是两个 ticket。
- 每个 ticket 的验收测试能不能在 30 秒里跑完？“人工验”做测试 = spec 还不够紧。
- Agent 是不是提了范围扩张被你拒了？数一下。>3 次 = spec 在干活；0 次 = agent 不够野，或者你 prompt 太保守。
进阶技巧
- UI 功能画线框稿（草也行）。AI 从草图实现 UI 比从散文好得多。
- 后端功能：把数据模型写进 spec。一半实现就直接出来了。
- Spec 当成文档跟代码放一起（
docs/specs/feature-name.md）。实际偏离时更新——这些更新就是审计痕迹。 - Agent 实现时给它完整 spec、不只是当前 ticket。没有完整 spec，agent 会自己重新发明上下文。
怎么验收输出
- 一页 spec 含验收准则 + 不做的事项。
- AI 揭示的歧义你已经在文档里决定（不是在脑子里）。
- Ticket 列表干净映射到 spec 各节，每个都有真验收测试。
- 每个 ticket 的验收测试都跑过（不是”在 dev 看起来 OK”）。
- 最终集成测试对照完整 spec 通过。
- PR 描述指向 spec；spec 留在 repo 里。
FAQ
- 写 spec 多久？: 一天的功能 30-60 分钟写 spec。下游省的不止返工时间，还有清晰度本身。
- AI 能写 spec 吗？: 能起稿。决策你自己负责。没有 owner 的 spec 产出没方向的代码。这个阶段把 AI 当速记，不当作者。
- 重构的 spec 怎么写？: 形状稍不同：“改前 / 改后、为什么、影响半径”。看 AI 重构工作流。
- Spec 中途要改怎么办？: 先改 spec 文档，再继续。Spec 文档才是基准，不是你的记忆。
- 跟 Claude Code / Codex 怎么搭？: 一样的流程；把 spec 粘进 agent 上下文（或它的 rules 文件），让它每个 ticket 都看得到。
- 这不就是瀑布吗？: 一页 spec 不是瀑布；是单个功能的”做完的定义”。真瀑布是 30 页 + 评审节点。