别再让AI一次写完整个功能：拆成四个检查点的Agent编程流程

把需求一整段扔给AI编程工具，然后去泡杯咖啡回来一看：代码写了八百行，测试没写，错误处理是假的，还顺手改了三个不相关的文件。

这种体验很普遍。问题不在于模型能力不够，而在交付粒度——你让它一次交付了太多东西。

人写代码也是分步的：先想接口，再搭骨架，再填实现，最后收拾边界。AI编程也该照这个节奏走，只是每一阶段让它停一下，让你验收。

一、为什么”一把梭”会失败

一次交付整个功能，有三个结构性问题：

第一，错误会被放大并隐藏。 AI在第一步误解了需求，后面所有代码都建立在错误假设上。因为最后交付物是一个完整可运行的模块，你很难一眼看出哪个假设错了。

第二，它替你做了太多决策。 数据结构、错误处理策略、是否要缓存、日志格式——这些本来该你定的事，它按最常见做法填了默认值。等你想改，已经牵一发动全身。

第三，验收成本转移到了你身上。 八百行代码里找问题，比写八百行代码还累。这就是所谓的”审查债务”。

二、四个检查点

检查点一：契约（Contract）

只让它输出接口，不写实现。

要它给出：

• 函数签名与参数类型
• 输入输出的数据结构（用代码里的类型定义写）
• 错误类型清单——什么情况抛什么错
• 外部依赖列表——要调哪些库、哪些内部服务
• 3个典型调用示例

你验收什么： 这个接口能不能表达你的需求？错误类型够不够？有没有引入你不想要的依赖？

这一步的产出通常不到50行，审查只要五分钟，但它决定了后面所有代码的形状。接口对了，实现错了只是返工；接口错了，实现再漂亮也是白写。

检查点二：骨架（Skeleton）

让它写结构和测试，不写业务逻辑。

具体要求：

• 所有函数都建好，函数体先 throw new Error('not implemented') 或直接返回占位值
• 每个函数配一个测试占位，写清测试意图
• 把流程串起来的主函数要完整——它调用谁、按什么顺序、失败怎么走

你验收什么： 测试用例覆盖的是不是你要的行为？主流程分支对不对？有没有遗漏的场景？

这一步价值极高。测试先写出来，等于你提前定义了”完成”的标准，后面AI填实现时就有了明确靶子，不会自由发挥。

检查点三：实现（Implementation）

按函数逐个填充，一次不要超过一个文件。

提示词可以很具体：

实现 parseInvoice() 这个函数，只改这个函数，不改签名、不加新依赖。让 parseInvoice.test.ts 里现有的测试全部通过。如果有测试本身写错了，先停下来告诉我。

关键约束是**“只改这个函数”**。不约束的话，AI为了让它跑通，很容易顺手改掉相邻代码、修改测试断言、或者给类型加 any。

你验收什么： 测试是否真的通过（自己跑一遍，别信它的报告）？有没有偷偷放宽测试？新增的依赖合理吗？

检查点四：收口（Hardening）

这一步专门让它找自己的问题。

• 列出所有未处理的异常路径
• 补边界值测试：空输入、超大输入、格式错误、超时、并发
• 检查日志和可观测性：出错时能不能定位
• 生成一份改动说明：改了哪些文件，影响哪些调用方

也可以用另一个模型来审查，专门找漏洞。同一模型自己审自己，盲区往往还在。

三、每步该交给AI什么

把需求按”确定程度”分层，对应到不同检查点：

内容	交给AI	你自己定
数据结构的具体字段	✅
是否引入新依赖		✅
测试用例的场景	✅ 起草	✅ 审核
错误处理策略		✅
函数内部实现	✅
日志格式与埋点		✅
边界条件清单	✅ 起草	✅ 补充

规律很清楚：AI负责”展开”，你负责”定标准”和”说不”。

四、检查点能省下的时间

看起来四个检查点比一把梭慢，实际算下来更快，因为省的是返工。

一次典型的中等功能（约500行代码）：

• 一把梭：生成15分钟 + 调试返工90分钟 + 审查找问题60分钟 ≈ 165分钟
• 四检查点：契约10分钟 + 骨架15分钟 + 实现40分钟 + 收口25分钟 ≈ 90分钟

差的这75分钟，几乎全部来自”不知道它错在哪”。

而且四检查点的产出可维护性明显更好——因为你参与了每个决策点，代码里的每一处”为什么”你都知道答案。

五、三个容易走形的信号

流程跑着跑着会变形，这三种情况要警觉：

• “这次太简单了，直接让它写完吧”——简单功能的返工成本低，可以放宽；但如果它每次都能完美一把梭，说明你给的活太简单了，该提升难度。
• “契约阶段改了三轮”——说明需求本身没想清楚。停下来，先去和业务对齐，别指望AI帮你理清需求。
• “测试一直过不了，我让它改测试”——这是最危险的信号。测试是你的标准，改标准等于放弃验收。

六、给非专业开发的精简版

如果你不是专业程序员，四个检查点可以压缩成三步：

1. 让它先描述怎么做（不写代码），你看逻辑对不对
2. 让它写一小块并解释，你手动验证一次
3. 最后让它自查一遍，列出可能的坑

核心原则不变：每次只让它交付你现在就能验收的东西。

结语

AI编程工具真正改变的不是”写代码的速度”，而是”谁来定标准、谁来验收”这件事的分工。

你从执行者变成了验收者。 验收者的活不轻松，但比逐行读一堆自己都没参与设计的代码强得多。

四个检查点不是标准答案，但它把”信任”换成了”证据”——每一段的代码，都有一个你已经点头过的接口在托着。