AI 协作与代码评审：Agent 代码怎么审

读完这一节，你能做到

1. 说清 AI 写 Agent 代码时最容易漏掉什么。
2. 在需求里补上"工具清单"与"兜底行为"两段。
3. 用五个检查点审出权限、幂等、预算与注入面的问题。
4. 用评估集而不是"试一下"来验收。

一、强项与盲区

它很擅长	它经常漏
工具函数的包装与参数转换	权限校验（它默认"调用方可信"）
检索管道的常规实现	预算与重试上限
结构化输出与解析	幂等设计
日志与埋点样板	错误路径（catch 里静默吞掉）
评估脚本骨架	上下文构造中的注入面

判断原则：AI 写得对"怎么实现"，写不出"允许做到什么程度"。 后者是设计决策，必须你来定。

二、上下文：比普通需求多两段

四件套照旧：目标、现状、约束、验收。

Agent 特有的两段：

1. 工具清单

每个工具给：名字、参数与类型、返回值、错误码、不该用的场景。不给清单，AI 会自己编工具名与参数。

2. 兜底行为

明确三类情况的处理：

• 工具失败（可重试 / 不可重试分别怎么做）
• 信息不足（追问还是拒答）
• 越权请求（拒绝话术 + 转人工）

一个反例

"做一个能查订单、能退款的客服 Agent。"这句话会让 AI 写出一个没有权限校验、没有幂等、没有步数上限的版本——本地测一次成功，线上一次异常就出事。

三、拆任务：契约先行，编排在后

① 工具契约（schema + 错误码）
② 单步实现（一个工具能正确调用与校验）
③ 编排（步数、重试、终止条件）
④ 评估（用评估集跑通，而不是手点）

为什么把编排放第三步

编排决定了"什么时候停"，这是最容易出错也最需要你自己设计的一层。让 AI 一次写完"工具 + 编排 + 提示词"，你很难判断哪一层出的问题。

四、五个检查点

1. 权限

• 工具是否最小权限？
• 身份是否来自服务端会话（而不是模型自述）？
• 写操作有没有人审或强校验？

2. 幂等与重试

• 写操作有幂等键吗？键由谁生成？
• 重试只针对可重试错误吗？
• 超时后是查状态还是直接重做？

3. 预算

• 步数、token、工具调用次数有上限吗？
• 超限后返回已有结果还是报错？

4. 错误路径

• catch 里是记录并上报，还是吞掉继续跑？
• 工具返回失败时，模型看到的是结构化错误还是"failed"？

5. 注入面

• 外部内容（检索、工具返回、用户上传）有没有被拼进指令区？
• 系统指令与数据区是否分开？

五、验证：三道闸

1. 静态闸：编译 + 类型 + lint。能拦住明显的 API 误用。
2. 评估闸：跑评估集，看工具选择准确率、答案要点覆盖、兜底率。
3. 成本与链路闸：看单次 token、平均步数、trace 里有没有异常重试。

第三闸最容易被跳过：功能"看起来没问题"，但步数从 3 涨到 7、单次成本翻倍，上线后才发现。

六、算例：一个退款 Agent 的两种做法

任务：查订单 + 发起退款，要求幂等、可审计。时长示意。

做法 A：一次要完

项	耗时
写需求、等生成	3 分钟
review 220 行	25 分钟
发现没有幂等键，退款可能重复	返工 30 分钟
发现退款直接执行没人审	返工 20 分钟
合计	78 分钟

做法 B：拆三轮

轮次	交给 AI 的	自己做的	耗时
① 契约	两个工具的 schema 与错误码	定幂等键与权限边界	10 分钟
② 实现	单步调用与参数校验	补人审与审计日志	15 分钟
③ 编排	步数与终止条件骨架	定兜底话术与升级规则	12 分钟
合计			37 分钟

净收益 = 生成节省的时间 −（审查 + 返工 + 事故成本）

AI 项目的事故成本还有一条：信任损失。一次重复退款或一次数据泄露，用户对产品的信任很难恢复。

七、常见坑

1. 只测 happy path。 工具失败、权限不足、检索为空这些分支才是事故来源。
2. 让 AI 顺手改权限与鉴权。 这是安全边界，必须自己写。
3. 不设预算。 一次异常就烧掉一天额度。
4. 把检索内容直接拼进系统提示。 注入口子。
5. 用"试一下"验收。 模型有随机性，单次成功没有意义。
6. prompt 不版本化。 改坏了无法回滚，也无法归因。

八、面试怎么讲

怎么用：先把工具契约与兜底行为写清，再让它实现，编排单独一轮
怎么验：评估集 + 成本与步数看板，三闸都过才上
踩过什么坑：它写的退款工具没有幂等，超时重试会导致重复退款；后来改成幂等键 + 查状态
换来什么：同类功能从 78 分钟降到 37 分钟，线上零重复退款

一句加分项："我审 AI 写的 Agent 代码，先看权限和幂等，因为这两块不报错，出事就是真金白银。"

九、动手任务：自写 → AI 写 → 对比 → 取舍

四步不跳：① 自己写（限时，关掉补全）→ ② 让 AI 写同一题 → ③ 逐条比对 → ④ 说出保留谁的写法。

① 自己写

1. 写一份 Agent 需求书：工具清单（含错误码）+ 三类兜底行为 + 验收标准。
2. 给这份需求写一张评审清单：五个检查点各两问。

② 让 AI 写同一题

把第 1 题交给 AI，补一句 按“目标 / 工具清单 / 约束 / 兜底 / 验收”五段输出，工具要带“不该用的场景”。

③ 对比要盯的点

• 它有没有写兜底行为？没有就是只覆盖 happy path。
• 工具清单有没有错误码与"不该用"的场景？
• 验收写的是"能用"还是可测的指标？

④ 一句话取舍

它写的东西，能不能直接交给另一个人实现？不能的话，缺的是哪一段。

十、自测

1. AI 写 Agent 代码最常漏的五件事是什么？
2. 需求里必须多写哪两段？
3. 为什么把编排放在最后一步？
4. 五个检查点分别是什么？
5. 三道闸分别拦什么？
6. 为什么"试一下能用"不能作为验收？

参考答案要点：权限、预算重试、幂等、错误路径、注入面；工具清单与兜底行为；它决定什么时候停，必须自己设计；权限、幂等、预算、错误、注入；编译、评估集、成本与链路；模型有随机性且失败模式静默。

配套题目

★ 越多越该先背；点题目可看完整答案与深入版。

• ★★★★★ 用 AI 写 Agent 代码，你会重点审什么？
• ★★★★☆ 怎么给 AI 描述一个 Agent 需求，才能一次做对？
• ★★★★☆ AI 生成的 prompt 和工具 schema，怎么验证？
• ★★★★☆ 哪些 Agent 相关的活你会交给 AI，哪些坚持自己写？