AI Agent 工具翻车 9 次之后：我总结的 11 条设计原则

2026-05-27·7 分钟阅读AI Agent方法论工程

写在前面：这篇是给已经在做 tool-calling agent 的工程师看的。如果你正在第 N 次改 prompt、第 N 次发现 AI 还是按错的写法翻车——这篇就是写给你的。

一个真实翻车现场

我在做一个「在线设计编辑器」的 AI 助手——AI 通过 tool calling 在画布上创建 / 修改节点，渲染出复杂的结构化内容。第一周跑下来，AI 翻车了 9 次。每一次都让我以为「再改一版 prompt 就好了」。

具体场景：编辑器有个字段叫 autoWidthPosition，我在 SKILL 文档里写它是「开启文本宽度自适应的开关」。AI 跟着写、用户跑测、渲染翻车——文本宽度根本没自适应。我以为是 prompt 不够清楚，又加了三段说明。AI 还是翻车。

直到我打开引擎源码，看到那一段：

childWidth =
  autoWidthPosition && horizontalAlignment === 'stretch'
    ? availableWidth - mL - mR
    : child.width ?? 0

autoWidthPosition 必须配合 horizontalAlignment: 'stretch' 才生效，单独传它完全无效。

我教错了。 我一直在改 prompt，但根因不是 AI 不懂——是我教错了，AI 在认认真真按错的教法跑。

这个发现让我意识到：AI Agent 工具优化的主要矛盾，根本不在 AI 那一侧。从那以后，我建了一份手册，把每次翻车都拆解成方法论。半个月后，这份手册有 11 条原则、3 个思想支柱、和一份「自我批评活页」。

为什么「再改一版 prompt」永远不够

Tool calling 项目里有一个反复出现的失败模式：

AI 调用工具出错
工程师改 prompt 或 SKILL 文档
AI 还是出错（同类问题换个角度复发）
回到第 1 步

我自己掉进这个循环至少 3 次。直到反思才发现：prompt 是建议，工具实现才是合约。 AI 不一定会读完 4000 行 prompt，但工具返回的 ok:false 它必然处理。把「硬规则」写在 prompt 里指望 AI 自觉遵守，这本身就是优化方向错了。

翻车闭环 6 步

每次 AI 翻车，按下面 6 步走，不要停在「修了就完事」：

翻车
  ↓ 下载 session log（用户一键导出，不要让他 console.log）
  ↓ 提取真实参数（AI 实际传了什么 vs SKILL 教什么）
  ↓ 对比引擎源码（不是文档、不是直觉、是源码）
  ↓ 修 tool + 改 SKILL + 加 example（三处同步）
  ↓ 用户验证 + 更新方法论手册（不只是修 bug，是积累认识）

第 6 步是关键。修了 bug 不写下来 = 下次同类问题再翻一次车。把每次翻车作为一条 entry 写进手册，标注：哪里写错过、真相是什么（带源码引用）、真正的坑在哪、修复 commit、触发原因。

这份手册越长，意味着主观主义的残骸被持续清扫——这才是真复利。

三大支柱

11 条原则是「术」，下面三件事是「道」。如果你只能记三件事，记这三件。

支柱一：实事求是，反对本本主义。 我（写 SKILL 的人）最大的诱惑是凭「我以为」——凭训练集印象、凭通用知识、凭旧文档。对治：写每条规则前自问「这是从源码读到的，还是我编的？」后者立刻打上「待源码核对」或删除；数据先于结论，用 grep -c 数真实统计推架构，不要用「我觉得应该这样」。

支柱二：抓主要矛盾，一分为二。 当前主要矛盾不是「AI 不会写代码」，是「AI 在跟着错误的 SKILL 写代码」。所以战术不是教更多技巧，而是先把已有 SKILL 的真实性核对到 100%——错的少一条，胜过新增十条。 还要分清字段属于哪一层（布局 / 渲染 / UI）、硬规则 vs 软建议——把建议写成硬规则是教条，把硬规则写成建议是放任。

支柱三：从实践中来，到实践中去。 用户每次报错就是一次反馈：跑测翻车 → 下载 log（调查）→ 对比源码（研究）→ 修三处（蒸馏）→ 回用户验证（到实践中去）→ 新发现入手册（积累认识）。两条战术准则：战略上相信 AI 能读长 prompt + 多 SKILL，不要因为「怕它蒙」而压缩到不严谨；战术上每个字段、每条错误信息都打磨到精确——错一个字，下游 AI 跟着错一千次。

6 条最反直觉的原则

原则 1：真理来源是引擎源码，不是文档、直觉、记忆。 当 AI 反复在某字段上翻车（≥2 次），写 SKILL 前必须读源码。验证标准：每条字段说明都要能回答「哪个文件、哪行决定这条规则」。答不出来 → 这条规则不能写。

原则 2：工具边界即教学边界。 任何「不能这么干」的硬规则，最稳的执行点是 tool execute 函数，不是 prompt：

if (args.type === 'RootContainer' && !isCanvasRoot) {
  return {
    ok: false,
    error: '根容器仅作整版最外层，不能挂到其它节点下。内层布局请改用子容器（接受同样的字段集）。',
  }
}

关键细节：错误消息必须带具体替代方案。AI 收到带方案的 ok:false 会在同一轮自我纠正；写「出错了」就要再多一轮，浪费 token 和时间。

原则 3：智能默认值 > 期望 AI 算。 能在工具里算出的合理默认值，绝不让 AI 自己算。我犯过的错：文本组件默认 width:200, height:100，AI 写 fontSize:572 → 渲染时撞死在 height=100，输出鬼畜。修复是把测算放进 tool 内部，AI 不传时用 estimateTextSize() 兜底。验证标准：每个默认值都问一遍「AI 不传时，这值能否覆盖 80% 场景」。

原则 4：保留 caller 显式意图，不无脑覆盖。 tool 的兜底逻辑仅在 caller 没传时启用。经典反例：AI 传了 name: '中文站名'，tool 末尾 node.name = getDefaultName() 无脑覆盖——用户图层面板看到的全是「图层 1 / 图层 2」。修复：所有「工具自动 X」的代码都加 if (!props.X) 守卫。

原则 5：修一处 = 校准三处。 发现一个误用，同步修三个地方：tool 实现（ok:false / 智能默认）、SKILL 文档（源码片段 + 正反例）、example（至少一个 good/ 一个 bad/）。只改 SKILL 不动 tool，规则失效；只改 tool 不动 SKILL，下次还按错的写法试。

原则 6：日志可下载 + token / 时长实时显示是 day-1 功能。 用户跑出问题时必须能一键导出可发回的诊断材料（不需要他学怎么 console.log），且任务进行中能感知成本。工程量极小（下载按钮约 25 行、状态条约 60 行），但没有它，每个 bug 至少要来回 3 轮「你能贴下控制台吗 / 我截图你看」。

自我批评活页

按「反对本本主义」，我专门建了一份活页，每次发现「我编的」被源码推翻就在这里登记。一个真实样本：

案例：「V4 引擎自动处理图片重叠 / 纵横比」是错的。 写过哪里：SKILL「特殊处理」段。真相：grep V4 路径，相关函数都无匹配——那是 V1/V2 历史代码，V4 重构时拆掉了。真正的坑：AI 看了 SKILL 以为「自动处理」，创建图片时不算重叠 → 出图错位。修复：标「可信度低 / 待源码核对」+ 改保守原则。

这份活页越长越值钱。 它是主观主义残骸被持续清扫的物证。

开你自己的活页

这套方法论不是从书上抄的，是 9 次翻车熬出来的。如果你正在做 AI Agent 工具，建议你：今天就在项目里建一份「翻车手册」，每次 AI 出错都拆解一次；加上「下载 session log」按钮，这是后续所有优化的素材源；建一份「自我批评活页」，登记每条被源码推翻的推测。

最后一句话：AI Agent 优化的主要矛盾不是 AI 不够聪明，是我们没把世界讲对。 改 prompt 永远不够，修世界——修 tool 实现、SKILL 真实性、example 准确性——才是真的优化。