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 準確性——才是真的優化。