大家好,我是大伟/Wei•Will,深耕软件工程一线,专注AI应用落地与Agent开发。
AI 进入开发流程后,我们团队最明显的变化,不再是只想着让 Codex 写得更快,而是先明确:什么时候才允许 Codex 进入具体开发。
最近的一个项目,让我真正开始重视方案文档。
项目开始时,我想直接让 Codex 做实现。需求讲完以后,没有专门强调具体的实现方案,也没有把实现边界控制清楚。结果 AI 除了完成核心功能,还主动考虑了快照版本等扩展性内容。功能最后确实做出来了,但代码复杂度几何上升,后续修改越来越困难,项目最后因为复杂度失控、无法继续维护而失败。
这次之后,我们调整了开发流程:
必须先产出方案文档,团队一起讨论审核,确认实现边界之后,才允许让 Codex 进入具体开发。
同时,方案编写、团队讨论和审核都会正式进入开发排期,不再把它们当成开发之前顺手完成的事情。
思维导图

一次项目:功能做完了,代码却失控了
这个项目开始时,我们并不是没有需求,而是没有把具体实现方案讲透。
大家觉得需求已经比较清楚,不如直接让 Codex 实现,边做边调整。当时没有强调模块怎么拆、数据怎么流、接口怎么定,也没有明确哪些能力属于本次范围,哪些暂时不做。
Codex 开始实现以后,很快就给出了可运行版本。它不仅能完成核心功能,还会根据上下文主动考虑扩展性。比如它加入了快照版本相关的设计,认为以后可能需要版本回滚、兼容或历史管理。
单看这些设计,并没有明显错误。问题在于,它们不是本次需求必须解决的问题。为了让这些扩展能力能够工作,代码里增加了更多状态、对象、分支和兼容逻辑,模块之间的关系也越来越复杂。
最后,项目功能确实实现了,但代码复杂度已经几何上升。每改一个地方,都要理解一串额外设计;每补一个功能,又会碰到更多边界。项目不是败在功能做不出来,而是败在复杂度失控、后续无法维护。
这次经历让我看清一件事:让 Codex 直接开发,最大的风险不是它写不出来,而是团队没有提前告诉它哪些东西不要写。
AI 为什么容易把方案做复杂
AI Coding 很强,但它不会天然知道团队当前最需要的只是简单可用。
当需求中只写了“要支持快照”,Codex 很可能按照完整产品能力去理解,加入版本保存、历史查询、兼容处理和后续扩展。它追求的是把问题回答完整,而不是判断这些能力现在是否值得做。
这并不是 Codex 特有的问题。人工开发时也可能过度设计,只是过去写代码的速度有限,复杂度不会在一开始就膨胀得太快。AI 可以在很短时间内补出大量实现,如果缺少边界,复杂度也会以更快的速度增长。
所以,我们不再把方案文档当作形式材料,而是把它当作 AI Coding 的输入边界。方案必须提前回答:
- 本次要做哪些功能,明确不做什么;
- 数据从哪里来,经过哪些处理,最后到哪里去;
- 需要改哪些模块、接口和数据结构;
- 核心逻辑如何流转,异常和边界如何处理;
- 哪些扩展性设计现在需要,哪些属于以后再说;
- 什么样的实现算完成,由谁审核和验收。
现在,我们会用高级模型辅助方案设计,让它帮助梳理思路、比较方案和补充遗漏。目的不是让 AI 直接决定架构,而是把实现逻辑先写出来,让团队有机会在编码之前发现过度设计。
方案文档最大的价值,不是留下几页文字,而是迫使团队明确:哪些必须做,哪些可以不做,哪些现在不能做。
新流程:方案审核通过,才允许 Codex 开发
那次项目失败之后,我们把流程固定成四步。
第一步,接到需求。
先把目标、输入输出、使用场景和限制条件讲清楚。这个阶段不讨论具体代码,只确认问题本身是否明确。
第二步,编写方案文档。
由方案负责人使用高级模型辅助设计,整理出实现路径、核心逻辑、接口变化、数据流转、异常场景,以及本次明确不做的内容。特别是扩展性设计,必须说明为什么现在需要,否则不进入实现范围。
第三步,团队讨论并审核方案。
方案写完后,必须拿到团队内部讨论。大家一起检查逻辑是否闭环、实现是否过于复杂、边界是否遗漏、有没有更简单的做法。
审核没有通过,就不进入开发。只有方案明确了做什么、不做什么、怎么验收,Codex 才可以开始实现。
第四步,使用 Codex 实现方案。
审核后的方案文档作为开发上下文。Codex 负责具体实现,开发人员重点检查核心逻辑、关键边界和最终结果,发现超出方案范围的扩展设计时及时砍掉。
流程可以简单写成:
1 | 接到需求 -> 写方案文档 -> 团队讨论审核 -> Codex 实现 |
从表面看,流程比过去多了方案和讨论;实际运行后,它减少的是编码阶段的方向错误、过度设计和后期返工。
方案和讨论,也必须进入开发排期
流程改了以后,还有一个很容易被忽略的问题:方案时间必须进入排期。
以前安排开发任务,主要排的是编码、联调和测试时间。现在,一个需求的排期里会明确包含:
- 方案文档的编写时间;
- 团队讨论和审核时间;
- 根据讨论结果修改方案的时间;
- Codex 实现和人工检查的时间;
- 按照方案边界进行验收的时间。
如果不给方案和讨论排时间,团队在进度压力下又会回到“先写代码再说”。这次项目的问题正说明,省掉前面的方案时间,后面的复杂度、返工和维护成本会成倍回来。
从工作量占比看,过去编码、调试和改细节大约占七成,方案相对轻。现在,方案设计、文档逻辑和团队审核占比明显上升,纯编码占比下降。
但整体研发周期反而会变短,因为方案在编码前完成了讨论,减少了方向性错误;Codex 有了明确边界,也不会随意把快照版本、兼容逻辑等扩展能力做大;团队审核又会主动压制过度设计。
所以,表面上看是写代码的时间少了、写方案和讨论的时间多了;本质上,是把时间花到了更能降低复杂度和返工的位置。
总结
那个项目让我付出的代价是:功能做出来了,但代码复杂度失控,最后无法维护。
也正因为这次经历,我们团队把开发流程改成了:
1 | 接到需求 -> 写方案文档 -> 团队讨论审核 -> Codex 实现 |
方案文档负责控制实现边界,团队讨论负责识别过度设计,开发排期则为方案和审核留出真实时间。
AI 让编码变快了,但团队更需要先回答清楚:这次到底做什么,不做什么,怎样才算完成。只有这些问题有答案,Codex 才是在加速交付,而不是在加速制造复杂度。
我是大伟/Wei•Will,专注 AI 应用落地与 Agent 开发,关注我,我们一起成长。