Stream Coding 文档优先开发

问题：AI 生成代码为什么反复返工

把一团含糊的需求丢给 AI，它不会告诉你需求含糊，而是基于假设直接生成代码。代码跑起来之后你发现行为不符合意图，于是开始一轮又一轮的修改循环：改提示、改代码、再改提示。最终结果只是比手写快一点点，返工成本吃掉了大部分收益。

这个技能把根因说清楚了：文档质量是唯一的瓶颈，不是模型能力。文档不够好，AI 只能靠猜；猜测必然偏离意图，偏离之后代码再漂亮也没用。

核心思路：文档是真相源，代码是打印输出

这个方法论的核心信念可以概括为一句话：如果你的文档足够好，AI 自己会写代码，真正的工作就是文档。

它把一次功能开发拆成四个阶段，时间占比和大多数习惯相反：

• 阶段1 战略思考（40%）：写代码之前先回答 7 个问题——解决什么问题、成功指标是什么、为什么能赢、核心架构决策、技术栈理由、MVP 范围、明确不做什么。每一问都拒绝抽象回答，要求具体到可衡量的结果。
• 阶段2 AI 就绪文档（40%）：产出 AI 零决策的实现规范。文档分三类：战略型（做什么和为什么）、实现型（怎么做）、参考型（查阅用）。实现文档必须包含四个章节：反模式（至少 5 个，告诉 AI 不要做什么）、测试用例规范（至少 5 个单元测试 + 3 个集成测试）、错误处理矩阵（每种失败模式怎么处理）、深度链接（精确导航，不用模糊引用）。
• 阶段2.5 对抗性审查（5%）：Spec Gate 通过后、生成代码前，把规范交给另一个 AI 模型或人类评审，用对抗性提示词找逻辑矛盾、隐式自由度和防御性缺口，按 CRITICAL / HIGH / MEDIUM / LOW 分级，零 CRITICAL 才能继续。
• 阶段3 执行（10%）：代码生成。不工作就修规范而不是修代码——先问“我的规范哪里不清楚”。
• 阶段4 质量与迭代（5%）：测试与偏差控制。每次手动改 AI 代码而不更新规范，都会积累偏差，偏差就是技术债。

Spec Gate：13 项检查，一项不能跳

这是它和 vibe coding 的根本区别。7/10 的规范只会生成 7/10 的代码，然后花 30% 返工。Spec Gate 分为基础检查（可操作、最新、单一来源、是决策非愿望、AI 可直接使用、无未来态、无废话）和文档架构检查（类型已识别、反模式位置正确、测试用例位置正确、错误处理位置正确、有深度链接、无重复），执行标准是全部通过且 AI 可理解性评分不低于 9/10。

适用边界与注意点

• 这个方法解决的是规范不清，不是模型不行。模型再强，喂给它模糊输入，照样给你看起来合理但不符合意图的代码。
• 代价很明确：前三个阶段占了约 90% 的时间。适合有明确目标、需要一次做对的功能；不适合还在探索方向的早期原型。
• 别把内容放错文档类型：反模式、测试用例、错误处理属于实现文档，不是战略文档的职责。
• 别跳过对抗性审查——写规范的 AI 和你有同样的盲点，换模型或换人来攻击，才能找到你自己看不到的问题。