项目翻车后,我重新整理了一套 AI Coding 实操方法

大家好,我是大伟/Wei•Will,深耕软件工程一线,专注AI应用落地与Agent开发。

最近复盘一个翻车案例时,我重新意识到:AI Coding 把敲代码的效率拉高以后,工程里最该增加的不是更多代码,而是更多方案评审。这个案例的业务细节不展开,失败路径却很典型。

需求刚提出来时,大家觉得事情并不复杂。团队很快让 AI 生成代码、补接口、接状态、处理异常,目标只有一个:先把流程跑起来。第一版确实很快有了结果,演示也能通过。于是后面的每个问题,都继续交给 AI 在现有代码上补一层。

一个条件加一个分支,一个边界塞进一个兼容层,一次失败再加一套重试逻辑。每次修改单独看都说得通,合在一起却形成了谁也不敢轻易触碰的复杂结构。后来团队花了越来越多时间解释旧代码、排查隐式状态和修复连锁问题,项目最终不是因为功能做不出来而失败,而是因为代码复杂度已经超过了团队的维护能力。

这件事真正值得复盘的地方,不是“AI 写错了一段代码”,而是我们在方案还没有站稳的时候,就让它把方案变成了大量代码。

代码写得越快,错误方案扩散得越快;越要把评审和验证前置。

思维导图

思维导图

翻车案例:代码很快跑通,系统却越来越难改

代码先跑起来,方案却没有经过验证

过去做一个新功能,我们会在理解需求、画数据流、定义接口的过程中不断暴露问题。AI Coding 改变了这个节奏:需求还不够清楚,目录、类、接口和测试已经生成,方案只讨论了一个大概,代码却能先在本地运行。

这不是说先做 Demo 一定错误。问题在于,Demo 被误认为最终方案的起点,后续所有新情况都通过补丁叠加,而不是回头重新审视边界。

每个补丁都合理,合起来却不可维护

翻车项目通常不是某一次修改特别离谱,而是每次局部决策都很有理由:

  • 为了兼容旧输入,增加一个转换层;
  • 为了处理异常,增加一套重试和兜底;
  • 为了支持新场景,扩展一个状态分支;
  • 为了不影响旧逻辑,再包一层适配器;
  • 为了赶进度,先把判断写在调用方,之后再说抽象。

这些动作短期都能减少阻塞,长期却会让职责不断漂移。数据在哪一层改变,状态由谁维护,异常由谁兜底,已经没有清晰答案。

当一个新同事或者新的 Agent 接手时,它看到的是一张能运行的网,却找不到这张网为什么要这样织。于是每一次修复都会继续增加新的分支,复杂度开始自我增长。

真正失败的是维护性

很多团队判断项目是否成功,只看功能有没有完成、接口能不能返回、演示能不能通过。

但软件项目还要回答另外几个问题:

  • 新需求进来时,能不能找到正确的修改位置;
  • 一个模块发生变化时,会不会牵连其他模块;
  • 出现异常时,能不能定位是输入、状态还是依赖出了问题;
  • 原作者不在场时,别人能不能安全接手;
  • 发现方案走偏时,能不能在低成本阶段回退。

这些问题如果没有答案,代码跑通只是暂时的成功。最终项目失败,往往不是因为没有实现能力,而是因为后续维护成本已经高到没人愿意继续承担。

代码变快之后,方案评审才是最大杠杆

以前,写代码可能占掉一项任务的大部分时间,方案评审容易被压缩成几句口头讨论。现在,生成代码、补测试、改接口的时间大幅缩短,反而是判断方案是否值得长期维护,决定了项目的总成本。

阶段 发现问题后的主要代价
需求与方案 改文字、改图和验收条件
小模块验证 重做一个局部实验或接口
整体编码 重构多个模块,重新联调
上线运行 故障排查、数据修复和回滚

同一个问题,越早发现,修正成本越低。AI 让编码变快,本质上是把“从方案到代码”的距离缩短了;如果我们不调整工作节奏,错误方案就会更快跨过这段距离。

所以,评审不是项目的减速带,而是 AI Coding 时代最有效的限速器。它把人的判断放在最有价值的位置:决定做什么、为什么这样做、哪些事情暂时不做。

不是所有任务都要开正式评审。低风险、重复性、边界稳定的小改动可以直接执行;涉及状态、数据、权限、公共接口和长期维护的任务,则应该把评审前置。判断标准不是代码量,而是错误方案落地后会造成多大返工。

AI 给出的方案,先当候选,不当答案

AI 很擅长快速给出一个看起来完整的方案。它可以列出模块、接口、类和流程,也能把常见模式拼接成一套能运行的实现。

但“完整”不等于“适合当前项目”。方案里最危险的部分,往往不是明显的错误,而是没有被说出来的假设:

  • 默认数据总是完整、调用一定成功;
  • 默认状态可以放在内存里,重试不会造成重复执行;
  • 默认未来需求可以继续加分支,团队也能维护这些抽象。

这些假设如果没有被人挑出来,AI 就会把它们直接写进代码。

因此,在让 AI 开始编码前,我更建议先让它输出一份“方案说明”,至少包含以下内容:

  1. 任务目标和明确不做的事情;
  2. 输入、输出以及数据归属;
  3. 模块边界和模块之间的依赖;
  4. 失败、重试、超时和回滚策略;
  5. 权限、兼容性和外部依赖;
  6. 验收标准、观测指标和人工确认点;
  7. 可能导致复杂度失控的地方。

这一步的目的不是让 AI 写一份漂亮文档,而是把隐藏假设提前暴露出来。方案说明写不清楚的地方,通常也是代码最容易失控的地方。

分小模块验证可行性,再确定最终方案

方案评审之后,不要马上让 AI 一次生成整套代码。更稳妥的做法,是先把方案拆成若干个最小可验证模块。

这里的“模块”不一定是微服务,也不一定要新建很多类。它可以是一个接口契约、一段状态流转、一次工具调用,或者一个最容易出错的边界。关键是:它要能单独验证,验证结果也能明确说明方案是否成立。

以一条 Agent 工作流为例,可以先拆成:

  1. 输入和上下文如何进入系统;
  2. Agent 如何选择并调用一个工具;
  3. 工具返回结果如何校验和转换;
  4. 中间状态如何保存、恢复和重试;
  5. 最终输出如何经过人工确认再交付。

每个模块先做一个最小实验,记录四件事:

  • 用什么输入验证;
  • 期望得到什么结果;
  • 失败时系统如何表现;
  • 这个结论能否支持下一步设计。

如果工具调用的返回结构不稳定,就先验证契约,不要继续扩展后面的编排。如果状态恢复还没有想清楚,就不要先堆更多自动化分支。如果权限边界无法验证,就先停在测试环境,不能因为 Demo 能跑就默认可以接入生产。

分模块验证的价值,是把“我觉得这个方案可行”变成一组可以检查的事实。关键模块和异常路径都说得清楚之后,再进入整体编码和集成。

这个过程其实也是人重新理解和筛选需求的过程:哪些必须实现,哪些可以暂缓,哪些边界还需要继续确认。

方案评审不能只靠一个人拍板

一个人看方案,很容易只看到自己熟悉的那一层。开发关注代码结构,测试关注异常路径,产品和业务关注规则与例外,运维关注权限、监控和回滚。每个人带进来的问题不同,方案才有机会接近真实运行环境。

多人评审的价值,不是把会议开得更长,而是在代码生成前,把不同角色会遇到的问题提前问出来。

比如一条 AI 工作流,开发可能会问“状态由谁维护”,测试会追问“超时后会不会重复执行”,业务方会确认“这个结果能不能直接作为业务事实”,运维则会关心“出了问题能不能看见、能不能停下来”。这些问题如果等到代码完成甚至上线后再问,代价就已经变高了。

可以用下面四组问题做一轮快速评审:

角色 重点追问
业务 / 产品 目标是什么,哪些场景不在范围内,规则和例外是否明确
开发 模块边界在哪里,数据和状态由谁负责,是否引入了不必要的抽象
测试 正常、异常、重复提交和超时怎么验证
运维 / 安全 权限是否够小,如何观测,如何暂停和回滚

评审时尤其要盯住三件事。

状态和责任是否清楚

要明确状态在哪里创建、谁能更新、什么时候持久化、失败后如何恢复。一个状态如果可以被多个模块随意修改,后续就很难定位问题。

失败后是否会重复做事

重试不是简单地“失败后再调用一次”。要问清楚请求是否幂等,超时后到底执行成功没有,重复调用会不会重复扣费、写数据或发送消息。

复杂度是否超过团队承受范围

每引入一层抽象,都应该说明它解决了什么问题,以及未来是否真的会复用。一个小需求如果同时引入多套状态机、全局上下文和多层适配器,就应该先退回重新评审。

不要只问“能不能实现”,还要问“谁能维护、出了问题谁能定位、方向错了能不能退回来”。

记录好人与 Agent 之间的桥梁

方案评审结束后,结论不能只停留在会议或聊天记录里。否则下一次换会话、换同事、换 Agent,还是会从头猜测。

真正值得留下的,不是所有讨论,而是会影响下一次判断的内容:

  • 目标和非目标;
  • 已确认的约束;
  • 选择过哪些方案;
  • 为什么放弃某个方案;
  • 哪些模块已经验证;
  • 当前方案的失败边界;
  • 下一步要做什么,什么情况下必须找人确认。

可以用一页纸记录下来:

1
2
3
4
5
6
7
8
9
10
11
## 任务交接

- 目标:
- 非目标:
- 已知约束:
- 候选方案:
- 已验证模块:
- 被否决方案及原因:
- 最终选择:
- 未决风险:
- 下一步动作:

这份记录就是人与 Agent 之间的桥梁。它让新的 Agent 会话知道为什么这样做,也让人能够在关键节点修正 Agent 的判断。

记录的重点不是保存全部聊天,而是保存决策和验证结果。特别是失败记录,不能只写“不可行”,还要写清楚在哪个条件下失败、失败表现是什么、因此形成了什么限制。

更稳妥的协作节奏:先慢一步,再持续加速

把这套方法落到项目里,可以形成一个并不复杂的节奏:

  1. 先问方案:让 AI 输出目标、边界、候选方案和风险,不直接生成整套代码;
  2. 再做评审:人重点检查状态、数据、权限、失败路径和复杂度预算;
  3. 验证小模块:优先验证最不确定、最容易造成返工的部分,并记录结论;
  4. 最后集成:关键边界稳定后,再让 AI 批量生成和重构代码;
  5. 小范围交付:先在可观测、可回滚的范围内运行,再逐步扩大自动化权限。

这个节奏把 AI 的高速生成放在已确认的方向上,减少后面反复推倒重来的次数。

以后再遇到“要不要先让 AI 把代码写出来”的问题,可以先问三个问题:

  • 这个方案的关键假设,是否已经被说清楚;
  • 最危险的模块,是否已经有最小验证结果;
  • 如果方向错了,是否能在代码扩散前停下来。

如果这三个问题还没有答案,最值得做的工作通常不是继续敲代码,而是再花一点时间把方案评审清楚。

总结:把速度放在正确的阶段

AI Coding 正在把“写出代码”变成越来越低成本的事情。真正拉开项目差距的,是能不能把问题拆对、边界说清,并在复杂度失控前及时停下来。

这次翻车案例给我的提醒很直接:不要因为 AI 写得快,就跳过方案评审;不要因为 Demo 跑通,就默认架构成立;不要因为每个补丁都合理,就忽略整体复杂度。

代码可以让 AI 帮我们更快地写,但方向、边界和最终方案,仍然需要人慢一点想清楚。

我是大伟/Wei•Will,专注 AI 应用落地与 Agent 开发,关注我,我们一起成长。