Claude Code 核心工程師自曝：調教 AI Agent，我們踩了 5 個坑！
整理版優先睇
Claude Code核心工程師分享：設計AI Agent工具，要從模型視角出發，不斷迭代工具，避免成為模型進化嘅束縛。
呢篇文係由Claude Code核心工程師Thariq Shihipar寫嘅覆盤，佢喺MIT Media Lab出身，做過YC W20創業者。佢冇講點樣用Claude Code，而係講Claude Code點解設計成而家咁樣。佢想解決嘅問題係：點樣為AI Agent設計最啱用嘅工具。整體結論係：工具設計必須理解模型嘅能力邊界，而且工具會隨模型升級而需要調整，甚至要刪除。
Thariq用咗一個比喻：面對難嘅數學題，需要嘅工具取決於使用者嘅能力。畀AI設計工具都一樣，要理解模型嘅「能力邊界」，然後畀佢最匹配嘅工具。佢分享咗幾個具體案例，包括AskUserQuestion工具嘅三版迭代、TodoWrite工具點樣變成束縛、搜索工具從RAG到Grep嘅演變，同埋用子代理擴展能力嘅思路。
呢啲案例帶出咗幾個重要教訓：工具設計得再好，如果模型唔理解點樣調用，都係白搭；同一功能要從模型嘅自然使用角度去設計；工具會隨著模型變強而成為束縛，要定期檢討；比「幫模型準備好一切」更加有效嘅係「俾模型自己揾上下文」；透過子代理可以擴展能力，而唔需要增加新工具。整體嚟講，畀AI設計工具係技術活，高度依賴你用嘅模型、Agent目標同運行環境，要多做實驗。
- 工具設計嘅核心係理解模型嘅能力邊界，唔係越多工具越好，而係要令模型識得自然調用。
- 同一功能可能要去幾版先成功，例如AskUserQuestion最終要用獨立工具，因為模型鍾意直接調用。
- 工具會隨模型進化而變成束縛，例如TodoWrite係舊版Claude需要，但新版Claude反而被佢限制死，最終要換成Task工具。
- 俾模型自主搜尋上下文（如Grep工具）比被動接收RAG結果更有效，尤其係模型變聰明之後。
- 唔需要硬加新工具，可以透過子代理擴展能力，例如Claude Code Guide子代理專門解答自身功能問題。
核心觀點：從模型視角設計工具
Thariq開門見山話，造AI Agent最難嘅唔係選模型，亦唔係調系統提示詞，而係應該畀AI乜嘢工具。佢用咗個比喻：面前有條好難嘅數學題，你需要乜嘢工具？取決於你嘅能力。
基礎好嘅，一張紙一支筆夠曬，但手動計好慢。畀個計數器你，快咗，但要識用進階功能。最強方案係用電腦，但前提係你識寫Code。工具嘅選擇，取決於使用者嘅能力。
畀AI設計工具都係一樣，你要理解模型嘅「能力邊界」，然後畀佢最匹配嘅工具。
工具設計得再好，如果模型唔理解點樣調用，都係白搭。
AskUserQuestion：三版迭代，獨立工具先成功
Claude Code有個功能叫AskUserQuestion，等Claude喺做嘢途中主動問用戶問題。呢個功能改咗三版先成功。
- 第一版：將提問功能塞入一個已有嘅工具ExitPlanTool，加咗個「問題列表」參數。結果Claude好混亂，一邊要生成計劃一邊要提問，用戶嘅回答同計劃衝突咗，邏輯上搞唔掂。
- 第二版：改Claude嘅輸出格式，用一種特殊嘅Markdown格式提問。理論上最靈活，實際上唔穩定，有時多加幾句，有時漏咗選項，有時索性換咗格式。
- 第三版：做咗一個獨立工具。Claude隨時可以調用，彈個視窗展示問題同選項，暫停等用戶答完先繼續。呢次成功咗，因為Claude鍾意調用呢個工具，輸出質量明顯更好。
Even the best designed tool doesn't work if Claude doesn't understand how to call it. 工具設計得再好，如果模型唔理解點樣調用，都係白搭。
TodoWrite到Task：工具會變束縛
Claude Code最初有TodoWrite工具，開始任務時列清單，做完一項勾一項。但Claude成日走神，團隊又加咗每5輪對話自動提醒機制。
早期有效，但模型變強之後，問題反過來咗——新版Claude唔需要提醒，呢啲提醒反而令佢變得死板，唔敢靈活調整。加上Claude Opus 4.5用子代理嘅能力大增，一個Todo清單唔夠用，最終換成Task工具，支援依賴關係同跨代理同步。
Todo係幫模型「記住該做乜」，Task係幫多個Agent「互相溝通」，模型自己就能改任務、刪任務。
搜索工具：從RAG到Grep，再到子代理
Claude Code最早用RAG，將代碼庫切碎存入向量數據庫，搜索時匹配最相關嘅片段餵俾模型。速度快效果唔錯，但RAG需要創建索引、配置環境，換部機可能就Run唔起。更核心嘅問題係Claude被動接收信息。
後來團隊換咗個思路：既然Claude識得上網搜，點解唔可以搜代碼庫？俾佢一個Grep工具，等佢自己搜文件、自己組織上下文。隨着模型變聰明，「幫佢準備好一切」不如「等佢自己嚟」。
爆火嘅「小龍蝦」就係最好例子——模型自己揾上下文，效果遠超被動接收。
Anthropic後嚟推出Agent Skills，進一步體系化叫「漸進式披露」：Claude先讀一個技能文件，入面引用其他文件，逐層展開。呢個思路亦用嚟擴展能力，同時避免增加工具，例如做一個Claude Code Guide子代理專門解答自身功能問題，而唔係加新工具。
實驗與反思：沒有標準答案
Thariq強調，冇一套嚴格規則教你點樣設計Agent工具。呢件事高度依賴你用嘅模型、Agent目標同運行環境。要多做實驗、認真讀模型輸出、不斷嘗試新方法。
畀AI設計工具，係技術活，冇捷徑，只有不斷實驗同反思。
Claude Code，大約有 20 個工具。
想加多一個工具，門檻好高。因為每多一個選項，模型做決策嗰陣就會多咗一層思考負擔。
呢 20 個工具係點樣嚟㗎？
Thariq Shihipar 寫咗一篇覆盤長文。
佢係 Claude Code 嘅核心工程師，MIT Media Lab 出身，YC W20 創業者。
佢冇講點用 Claude Code，而係講 Claude Code 點解會被設計成而家呢個樣。
標題叫「Seeing like an Agent」。
翻譯一下，即係「學識從 AI 嘅角度睇問題」。」
整一個 AI Agent，最難嘅唔係揀模型，亦唔係調系統提示詞。
而係要俾 AI 乜嘢工具。
Thariq 用咗一個比喻。面前有一道好難嘅數學題，你需要啲乜工具？
數學基礎好，一張紙一支筆就夠，但手動計數好慢。俾你一個計數機，速度快咗，但你要識得點用啲高級功能。最強方案係一部電腦，但前提係你識寫 code。
工具嘅選擇，取決於使用者嘅能力。
幫 AI 設計工具都係一樣。你要理解模型嘅「能力邊界」喺邊，然後俾佢最匹配嘅工具。
舉個例子。
Claude Code 有個功能叫 AskUserQuestion，讓 Claude 喺做嘢嘅過程中主動向用戶提問。
聽落好簡單嘅功能，改咗三個版本。
第一個版本，將提問功能塞咗入一個現有嘅工具 ExitPlanTool 裏面。原本係用嚟生成執行計劃，加咗一個「問題列表」參數。
Claude 即刻呆咗。
一邊要生成計劃，一邊要提問，用戶嘅回答同計劃衝突咗點算？邏輯上係矛盾。
第二個版本，改 Claude 嘅輸出格式，叫佢用一種特殊嘅 Markdown 格式嚟提問。
理論上最靈活，實際上唔穩定。有時會加多幾句說話，有時會漏咗選項，有時直頭換咗格式。
第三個版本，做咗一個獨立嘅工具。
Claude 隨時可以叫佢出嚟，彈出一個視窗顯示問題同選項，成個流程暫停，等用戶答完先繼續。
成了。
Thariq 咁樣總結。
Even the best designed tool doesn't work if Claude doesn't understand how to call it.
就算工具設計得再好，如果模型唔明點樣調用，都係白做。
第三個版本之所以好用，係因為 Claude 好鍾意調用呢個工具。輸出質素亦明顯好咗。
有啲意思。
幫 AI 設計工具，唔可以淨係從產品經理嘅角度諗「功能應該點樣實現」，仲要從模型嘅角度諗「佢會唔會自然地用呢個工具」」。
另一個例子。
Claude Code 啱啱上線嘅時候，模型經常有啲唔記得自己做緊乜。
團隊做咗一個 TodoWrite 工具。開始任務嘅時候列清單，做完一項就剔一項。Claude 仍然會分心。後來仲加咗每 5 輪對話自動提醒嘅機制。
初期有效。
但係模型變強之後，問題反轉咗。
新版 Claude 唔需要俾人提醒。呢啲提醒反而令佢變得死板，覺得既然系統係咁提醒我要跟住清單做，咁我就照跟清單，唔敢靈活調整。
更大嘅變化係 Claude Opus 4.5 用子代理（Sub agents）嘅能力大幅提升。多個子代理之間要協調任務，一個 Todo 清單完全唔夠用。
TodoWrite 俾換咗做 Task 工具。
Todo 係幫模型「記住要做咩」。Task 係幫多個 Agent「互相溝通」，支援依賴關係、跨代理同步，模型自己就可以改任務、刪任務。
Thariq 喺呢度提煉出一個好重要嘅觀點。
「你喺某個能力階段為模型設計嘅工具，喺下一個階段可能會變成束縛。要不斷返轉頭睇嚇，邊啲需要升級，邊啲應該刪咗佢。。」
搜索工具嘅進化都係同一邏輯。
Claude Code 最早用 RAG，將 code 庫切成碎片放咗入向量數據庫，搜索嗰陣匹配最相關嘅片段餵俾模型。
速度快，效果唔錯。
但係 RAG 需要創建索引、配置環境，換咗機可能就執行唔到。更核心嘅問題係，Claude 係被動接收信息嗰一方。系統幫佢揾好上下文，然後餵俾佢。
後嚟佢哋換咗個諗法。既然 Claude 可以搜網頁，點解唔可以搜 code 庫？
俾佢一個 Grep 工具，等佢自己揾檔案、自己組織上下文。
隨住模型變聰明，「幫佢準備好一切」不如「等佢自己嚟」。爆紅嘅「小龍蝦」就係最好嘅例子。
後嚟 Anthropic 推出咗 Agent Skills，進一步將呢個思路系統化，叫「漸進式披露」」。
Claude 先讀一個技能檔案，裏面引用其他檔案，啲檔案又引用更加深嘅檔案。按需加載，逐層展開。
一年時間，Claude 由「基本上唔會自己揾上下文」進化到「多層嵌套搜尋，精準定位所需資訊」」。
呢個思路亦用嚟擴展能力，同時避免增加工具。
例如用戶成日問「點樣加 MCP 畀 Claude Code」「呢個斜槓命令係做咩㗎」呢類問題。Claude 答唔到。
將啲文檔全部塞入系統提示詞？越塞越亂，影響模型判斷。俾文檔連結等 Claude 自己查？佢又會一次過 load 太多嘢。
最終方案係做咗一個 Claude Code Guide 子代理。當被問到自己嘅功能時，Claude 會將問題轉俾子代理，子代理有專門嘅搜索指令，淨係返答案。
冇加新工具，透過子代理就擴展咗能力。
Thariq 話：
「如果你期望有一套嚴格規則教你點設計 Agent 嘅工具，呢篇文章唔係。」
幫 AI 設計工具，係技術活。高度依賴你用嘅模型、Agent 嘅目標、運行嘅環境。
多做實驗。認真讀模型輸出。不斷嘗試新方法。
最後，引用 Claude Code 之父 Boris Cherny 喺 YC 嘅 Lightcone 播客入面講嘅一句話。
「到今年年底，軟件工程師呢個 title 可能會逐漸消失。取而代之嘅，可能會係 builder，或者係產品經理。」
咁，你準備好未？
我係木易，Top2 + 美國 Top10 CS 碩士，而家係 AI 產品經理。
關注「AI信息Gap」，等 AI 成為你嘅外掛。
Claude Code，大約 20 個工具。
加一個新的，門檻極高。因為每多一個選項，模型在做決策時就多了一層思考負擔。
這 20 個工具是怎麼來的？
Thariq Shihipar 寫了一篇覆盤長文。
他是 Claude Code 的核心工程師，MIT Media Lab 出身，YC W20 創業者。
他沒有講怎麼用 Claude Code，講的是 Claude Code 為什麼被設計成現在這個樣子。
標題叫「Seeing like an Agent」。
翻譯一下，「學會從 AI 的視角看問題。」
造一個 AI Agent，最難的不是選模型，也不是調系統提示詞。
是該給 AI 什麼工具。
Thariq 用了一個比喻。面前有一道很難的數學題，你需要什麼工具？
數學基礎好，一張紙一支筆夠了，但手動計算很慢。給你一個計算器，速度快了，但你得知道怎麼用那些高級功能。最強方案是一台電腦，但前提是你會寫代碼。
工具的選擇，取決於使用者的能力。
給 AI 設計工具也一樣。你得理解模型的「能力邊界」在哪，然後給它最匹配的工具。
舉個例子。
Claude Code 有個功能叫 AskUserQuestion，讓 Claude 在幹活的過程中主動向用戶提問。
聽起來簡單的功能，改了三版。
第一版，把提問功能塞進了一個已有的工具 ExitPlanTool 裏。原本是用來生成執行計劃的，加了一個「問題列表」參數。
Claude 直接懵了。
一邊要生成計劃，一邊要提問，用戶的回答和計劃衝突了怎麼辦？邏輯衝突了。
第二版，改 Claude 的輸出格式，讓它用一種特殊的 Markdown 格式來提問。
理論上最靈活，實際不穩定。有時候多加幾句話，有時候漏掉選項，有時候乾脆換了格式。
第三版，做了一個獨立工具。
Claude 隨時可以調用，彈出一個窗口展示問題和選項，整個流程暫停，等用戶答完才繼續。
成了。
Thariq 這樣總結。
Even the best designed tool doesn't work if Claude doesn't understand how to call it.
工具設計得再好，如果模型不理解怎麼調用，也白搭。
第三版之所以好用，是因為 Claude 喜歡調用這個工具。輸出質量也明顯更好。
有點意思。
給 AI 設計工具，不能只從產品經理的角度想「功能該怎麼實現」，還要從模型的角度想「它會不會自然地使用這個工具」。
另一個例子。
Claude Code 剛上線的時候，模型經常忘記自己要做什麼。
團隊做了一個 TodoWrite 工具。開始任務時列清單，做完一項勾一項。Claude 還是會走神。後來又加了每 5 輪對話自動提醒的機制。
早期有效。
但模型變強之後，問題反過來了。
新版 Claude 不需要被提醒了。這些提醒反而讓它變得死板，覺得既然系統在提醒我遵守清單，那我就老老實實按清單來，不敢靈活調整。
更大的變化是 Claude Opus 4.5 用子代理（Sub agents）的能力大幅增強。多個子代理之間要協調任務，一個 Todo 清單完全不夠用。
TodoWrite 被替換成了 Task 工具。
Todo 是幫模型「記住該做什麼」。Task 是幫多個 Agent「相互溝通」，支持依賴關係、跨代理同步，模型自己就能改任務、刪任務。
Thariq 在這裏提煉出一個很重要的觀點。
「你在某個能力階段為模型設計的工具，在下一個階段可能變成束縛。得不斷回頭看，哪些需要升級，哪些該刪掉。」
搜索工具的進化也是同一個邏輯。
Claude Code 最早用 RAG，把代碼庫切成碎片存進向量數據庫，搜索時匹配最相關的片段餵給模型。
速度快，效果不錯。
但 RAG 需要創建索引、配置環境，換台機器可能就跑不起來了。更核心的問題是，Claude 是被動接收信息的那一方。系統幫它找好上下文，餵給它。
後來他們換了個思路。既然 Claude 能搜網頁，為什麼不能搜代碼庫？
給它一個 Grep 工具，讓它自己搜文件、自己組織上下文。
隨着模型變聰明，「幫它準備好一切」不如「讓它自己來」。爆火的「小龍蝦」就是最好的例子。
後來 Anthropic 推出了 Agent Skills，進一步把這個思路體系化，叫「漸進式披露」。
Claude 先讀一個技能文件，裏面引用其他文件，那些文件又引用更深層的文件。按需加載，逐層展開。
一年時間，Claude 從「基本不會自己找上下文」進化到了「多層嵌套搜索，精準定位需要的信息」。
這個思路也被用來擴展能力，同時避免增加工具。
比如用戶經常問「怎麼給 Claude Code 添加 MCP」「這個斜槓命令是幹嘛的」這類問題。Claude 答不上來。
把文檔全部塞進系統提示詞？越塞越亂，影響模型判斷。給文檔連結讓 Claude 自己查？它又會一次性加載太多東西。
最終方案是做了一個 Claude Code Guide 子代理。當被問到自身功能時，Claude 會把問題轉給子代理，子代理有專門的搜索指令，只返回答案。
沒有加一個新工具，通過子代理就擴展了能力。
Thariq 說：
「如果你希望有一套嚴格規則教你怎麼設計 Agent 的工具，這篇文章不是。」
給 AI 設計工具，是技術活。高度依賴你用的模型、Agent 的目標、運行的環境。
多做實驗。認真讀模型輸出。不斷嘗試新方法。
最後，引用 Claude Code 之父 Boris Cherny 在 YC 的 Lightcone 播客裏說的一句話。
「到今年年底，軟件工程師這個 title 可能會逐漸消失。取而代之的，可能是 builder，也可能是產品經理。」
那麼，你準備好了嗎？
我是木易，Top2 + 美國 Top10 CS 碩，現在是 AI 產品經理。
關注「AI信息Gap」，讓 AI 成為你的外掛。