文档优先开发方法论

为什么AI辅助开发总陷入修改循环？

很多人用AI写代码时会遇到这种情况：给了模糊的需求文档，AI生成的代码要么不符合预期，要么需要反复修改，最终效率提升有限。问题根源往往不在AI，而在文档——混乱、模糊的文档会让AI基于假设生成代码，一旦假设偏离真实意图，就会陷入“改代码→再改→再调整”的循环。

文档优先的核心思路

这个技能的核心是文档优先开发：把文档当作“唯一真相源”，代码只是文档的输出结果。真正的开发工作集中在前期文档打磨，而非后期代码修补。具体分为四个阶段：

• 阶段1：战略思考（占40%时间）：用7个问题框架明确方向，比如“到底解决什么问题”“成功指标是什么”“不构建什么”，拒绝“帮助用户管理任务”这类模糊表述，要求具体到用户、场景和可衡量结果。
• 阶段2：AI就绪文档（占40%时间）：文档分为战略型（做什么）、实现型（怎么做）、参考型（查阅）三类。实现文档必须包含反模式章节、测试用例规范、错误处理矩阵、深度链接四个章节，且需通过Spec Gate 13项检查（7项基础检查+6项文档架构检查），确保文档无歧义、AI可直接使用。
• 阶段2.5：对抗性审查（占5%时间）：文档通过Spec Gate后，用不同AI模型或人类评审进行压力测试，查找逻辑矛盾、隐式自由度等问题，修复所有CRITICAL问题后再进入编码。
• 阶段3：执行与迭代（共占15%时间）：遵循生成-验证-集成循环，代码失败时先修复规范而非手动改代码；迭代时若手动修改代码，必须同步更新文档，避免产生“偏差”（技术债务）。

适用边界与注意点

适合需要AI生成复杂功能、系统或重构项目的场景，尤其是文档不清晰时。但不适合简单脚本或一次性小工具——过度打磨文档反而会增加成本。另外：

• 不要跳过Spec Gate，即使文档是自己写的；
• 不要接受“适当处理错误”这类模糊规范；
• 不要把实现细节写进战略文档，避免重复；
• 代码出问题时先检查文档，而非直接改代码。