AI编程先写方案再写代码：避免翻车、提升代码质量的方法论

1. 为什么我坚持让 AI 先写方案再写代码1.1 一个让我彻底改变习惯的翻车现场去年帮一个做跨境电商的朋友改一套订单同步服务需求听起来很简单把三个平台的订单拉到一个中台库做去重和状态映射。我当时图快直接让 AI 生成了一版 Python 脚本跑起来看着挺顺结果上线第二天就出事了——某个平台的订单状态字段是字符串枚举另一个平台是数字码AI 在生成代码时自己猜了一套映射关系把已发货映射成了待付款。朋友那边客服被客户骂了一整天。事后复盘问题根本不在 AI 写得对不对而在我压根没让它先把映射规则、字段语义、异常分支这些事讲清楚。代码只是方案的落地方案没定代码写得再漂亮也是空中楼阁。从那以后我改了个习惯任何非玩具级的任务先让 AI 输出一份方案文档我审完、改完、确认无误再让它动代码。这个习惯救了我至少五次。1.2 方案先行到底解决了什么问题很多人对 AI 编程的理解还停留在我描述需求它吐代码。这在 LeetCode 级别的题目上没问题但真实项目里代码只占工作量的三成剩下七成是边界条件是什么、数据从哪来到哪去、失败了怎么回滚、并发下会不会打架、以后谁来维护。让 AI 先写方案本质上是把这七成的思考过程显性化。方案里会自然暴露出这些问题输入输出的契约字段类型、取值范围、空值怎么处理状态流转一个订单从创建到完成经过哪些状态哪些状态可以互相跳转异常路径网络超时、第三方返回错误码、数据格式不符预期时怎么办非功能需求QPS 大概多少、要不要幂等、日志打到什么粒度这些东西如果藏在代码里你得逐行读才能发现写成方案扫一眼就知道哪里没想清楚。我实测下来一份 800 字的方案能省掉后面至少两小时的调试和返工。1.3 这套方法适合谁不适合谁适合的人有一定工程经验、能判断方案好坏的开发者带小团队的技术负责人需要快速验证想法但不想埋雷的独立开发者。不太适合的人完全零基础、连变量作用域都还没搞明白的新手。因为方案审阅需要你有能力判断AI 说的这个方案对不对如果你判断不了那方案和代码对你来说都是一样的黑盒。新手可以先从让 AI 解释它写的代码开始等有了判断力再上方案先行。提示方案先行不是让你写八股文。一份好的方案应该控制在 500 到 1500 字超过这个长度说明你在写设计文档而不是方案效率反而下降。2. 方案到底该写什么一份可复用的模板拆解2.1 我常用的方案骨架经过几十次迭代我固定下来一套提示词模板让 AI 按这个结构输出。你可以直接抄请针对以下需求先输出一份技术方案不要写代码。 方案需包含 1. 需求理解用你自己的话复述一遍指出我描述里模糊或矛盾的地方 2. 输入输出定义数据结构、字段类型、示例值 3. 核心流程分步骤描述标注每步的输入输出 4. 异常与边界列出至少 5 种可能的异常情况及处理策略 5. 技术选型用什么语言/库/中间件为什么 6. 潜在风险这个方案可能在哪里出问题 7. 待确认问题你需要我补充哪些信息才能继续 需求如下[你的需求]这个模板的关键在于第 1 条和第 7 条。第 1 条逼着 AI 复述需求很多时候它复述出来的东西和你想的完全不一样这就是需求歧义的早期信号。第 7 条让 AI 主动提问把它不知道但假装知道的部分挖出来。2.2 需求理解环节把歧义扼杀在摇篮里我拿一个真实例子说明。之前要做扫盘代码类的文件扫描工具需求是扫描指定目录下所有文件找出重复文件。如果直接让 AI 写代码它会给你一个基于文件大小和 MD5 的脚本看起来没问题。但让它先写方案它在需求理解里会问重复的定义是什么内容完全相同还是文件名相同大文件比如 10GB 的视频要不要参与比对全量算 MD5 会很慢软链接和硬链接怎么处理要不要跟随扫描结果怎么输出控制台、文件还是数据库这四个问题里第三个和第四个我当初压根没想过。软链接如果处理不当可能造成无限递归结果输出方式决定了整个程序的结构。你看方案阶段花五分钟省掉的是后面重构的半天。2.3 输入输出定义契约先于实现这一块是方案里最硬的部分也是最容易被跳过但最不该跳过的。我要求 AI 用表格把数据结构列清楚包括字段名、类型、是否必填、示例值、备注。举个数据同步的例子AI 输出的契约表大概长这样字段名类型必填示例值备注order_idstring是SO20240115001平台订单号全局唯一statusint是21待付款 2已付款 3已发货 4已完成 5已取消amountdecimal是199.00单位元保留两位小数created_atstring是2024-01-15 10:30:00平台本地时间需转 UTC有了这张表后面写代码时字段映射就是照抄不会出现我开头说的那种AI 自己猜映射的事故。而且这张表可以直接拿去做单元测试的用例一举两得。2.4 异常与边界AI 最容易偷懒的地方说实话如果你不明确要求AI 写方案时对异常处理往往是敷衍的一句做好错误处理就带过去了。所以我在模板里强制要求列出至少 5 种异常情况。还是订单同步的例子强制要求后 AI 列出来的第三方接口超时超过 10 秒无响应第三方返回限流错误码429订单状态字段出现未定义的值比如平台新增了状态码 6金额字段为负数或超过合理范围同一订单号在两次拉取中状态回退已发货变回已付款第 3 条和第 5 条是真实项目里最坑的。平台悄悄加状态码你的程序如果没做兜底就会崩状态回退如果不处理中台数据就乱了。这些在方案阶段列出来写代码时自然就会加上对应的分支。注意异常列表不是越长越好重点是覆盖会导致数据错误和会导致程序崩溃这两类。纯粹的日志级别问题不用在这里展开。3. 从方案到代码怎么让 AI 按方案落地3.1 把方案作为上下文喂回去方案确认后下一步不是重新描述需求而是把方案原文贴回去让 AI 基于方案写代码。提示词大概是这样以下是我们确认过的技术方案请严格按照方案实现代码。 要求 - 每个函数上方用注释说明它对应方案里的哪一步 - 异常处理必须覆盖方案第 4 节列出的所有情况 - 关键逻辑处加日志日志级别按方案约定 - 先输出代码结构有哪些文件、每个文件负责什么我确认后再写具体实现 方案如下[粘贴方案]这里有个小技巧先让它输出代码结构别急着写实现。因为结构错了实现写得再好也得推倒重来。结构确认这一步通常只要一两分钟但能避免大量返工。3.2 分模块生成别一次性要全部代码我踩过的坑一次性让 AI 生成一个包含五个模块的完整项目结果它写到第三个模块就开始忘记前面的接口定义函数签名对不上变量名前后不一致。后来我改成按模块生成每个模块生成完立刻做一次接口对齐检查。具体做法是让 AI 先输出所有模块间的接口定义函数名、参数、返回值确认后再逐个模块实现。这样即使某个模块生成得不好也不会污染其他模块。3.3 代码诊断插件的配合使用方案落地阶段我习惯开着代码诊断插件比如静态分析工具实时看提示。AI 生成的代码经常有一些能跑但不规范的地方比如未使用的变量、可能的空指针、资源没关闭。这些诊断插件会直接标出来比人工 review 快得多。我的流程是AI 生成一个模块 → 诊断插件扫一遍 → 修掉明显问题 → 人工看核心逻辑 → 进入下一个模块。这个循环走下来代码质量比生成完再统一 review高不少因为问题在刚产生时就被修掉了不会累积。3.4 一个完整的落地示例拿文件去重工具举例方案确认后我让 AI 按这个顺序实现第一步它输出结构scanner.py - 目录遍历产出文件列表 hasher.py - 计算文件哈希带缓存 dedup.py - 分组比对输出重复组 cli.py - 命令行入口参数解析第二步我确认结构合理比如我要求 hasher 支持分块读取大文件。第三步逐个模块生成每个模块生成后跑一次诊断。第四步写一个小的测试脚本造几个重复文件验证。整个过程大概四十分钟其中方案阶段占了十分钟。如果跳过方案直接写我估计得花一个半小时而且大概率会漏掉大文件分块读取这个点。4. 实操中踩过的坑与排查技巧4.1 AI 方案看起来很对但实际跑不通这是最常见的问题。AI 写的方案逻辑自洽但落到具体环境就出问题。比如它建议用 Redis 做去重缓存方案里写得头头是道但你的环境根本没有 Redis或者版本太老不支持某个命令。排查思路方案确认阶段凡是涉及外部依赖的我都会追问一句这个依赖在我的环境里是 X 版本方案还成立吗。让 AI 针对你的实际环境做适配而不是给一个通用方案。4.2 方案和代码不一致有时候 AI 写代码时会自作主张偏离方案尤其是方案里没写死的细节。比如方案说超时重试 3 次代码里写成了无限重试。我的应对办法是在提示词里加一句如果实现时发现方案有问题先停下来告诉我不要自行修改方案。这句话很管用能把偏离扼杀在发生前。4.3 常见问题速查表问题现象可能原因处理方式方案里字段类型和代码不一致生成代码时没带方案上下文把方案原文贴回要求逐字段对齐异常分支代码里缺失方案异常列表不够具体方案阶段强制列 5 种以上异常大文件处理卡死方案没考虑分块方案阶段明确数据规模上限模块间接口对不上一次性生成太多模块先定接口再分模块实现依赖环境不匹配方案用了通用假设方案阶段声明实际环境版本4.4 几个我压箱底的小技巧第一个让 AI 在方案最后附一段如果我是 reviewer我会质疑这个方案哪里。这招能挖出 AI 自己都没把握的地方往往就是风险点。第二个方案里的每个技术选型都让它给一个不用这个会怎样的对比。比如为什么用消息队列而不是直接调用这个对比能帮你判断选型是否过度设计。第三个代码生成后让 AI 自己写一份这份代码和方案的对应关系表逐条列出方案里的要求对应代码的哪一行。这个表既是自检也是以后维护的索引。5. 把这套方法扩展到更复杂的场景5.1 多模块项目的方案拆分当项目大到单个方案装不下时我会做分层方案先出一份总方案定清楚模块划分和接口再针对每个模块出子方案。总方案控制在 1000 字以内子方案各 500 字左右。这样做的原因是AI 的上下文有限一份两万字的巨型方案它记不住生成代码时照样会丢细节。拆成小块每块都在它的注意力范围内质量稳定得多。5.2 涉及第三方服务的方案要点只要方案里涉及调用外部服务我一定会让 AI 补充这几项超时时间、重试策略、降级方案、鉴权方式、限流应对。这五项缺任何一项上线后都可能出问题。特别是降级方案很多人不写结果第三方一挂自己的服务也跟着挂。5.3 方案文档的长期价值方案不只是给 AI 看的它还是团队协作的载体。新人接手时看方案比看代码快十倍。我现在的习惯是方案确认后存进项目仓库的 docs 目录代码里引用方案章节号。半年后回头看这份方案就是最好的设计文档。而且方案是可以复用的。同类需求第二次做时把上次的方案调出来改改就行比从零开始快得多。我手上已经攒了十几份方案模板覆盖数据同步、文件处理、接口对接、定时任务这几类常见场景新项目基本是改模板而不是从零写。5.4 什么时候可以跳过方案也不是所有事都要写方案。我的判断标准是如果这个任务你闭着眼睛都能写对那就跳过。比如写个快速排序、格式化一段 JSON、改个配置这些直接让 AI 写代码就行写方案反而是浪费时间。但只要满足以下任一条我就一定先写方案涉及数据持久化、涉及外部服务调用、有并发或定时逻辑、代码量预计超过 200 行、需要别人维护。这几条基本覆盖了真实项目里 90% 的坑。说到底让 AI 先写方案再写代码核心不是流程本身而是逼着自己在动手前把问题想清楚。AI 只是把这个思考过程加速了、显性化了。我用了大半年最大的收获不是省了多少时间而是代码返工率明显下降晚上睡觉踏实多了。