構建Claude Code的經驗教訓：從智能體的視角觀察

作者 | Michael Redlich

譯者 | 劉雅夢

策劃 | 褚杏娟

構建智能體工具帶中最困難的部分之一是構建其動作空間。

Claude 通過工具調用來執行操作，但是在 Claude API 中有很多方法可以使用原語，比如 bash、skills 和最近添加的代碼執行來構造工具（閱讀 @RLanceMartin 的新文章，了解更多關于 Claude API 的編程工具調用）。

考慮到所有這些選項，你如何設計智能體的工具？你是否只需要一個像代碼執行或 bash 這樣的工具嗎？如果你有 50 個工具，每個工具對應一個智能體可能遇到的用例，那會怎么樣？

為了將自己置于模型的思維中，我喜歡想象被給予一個困難的數學問題。你想用什么工具來解它？這要看你自己的技術了！

紙張是最基本的，但你將受限于手動計算。計算器會更好，但你需要知道如何操作更高級的選項。最快和最強大的選擇是計算機，但你必須知道如何使用它來編寫和執行代碼。

這是一個設計智能體的有用框架。你想給它提供適合它自身能力的工具。但你怎么知道這些能力是什么呢？你要集中注意力，閱讀它的輸出，進行實驗。你要學著像智能體一樣看問題。

以下是我們在構建 Claude Code 時從關注 Claude 中學到的一些經驗教訓。

改進 Elicitation 和

AskUserQuestion 工具

在構建 AskUserQuestion 工具時，我們的目標是提高 Claude 提問的能力（通常稱為啟發）。

雖然 Claude 可以直接問問題，但我們發現回答這些問題似乎花費了不必要的時間。我們怎樣才能降低這種摩擦，增加用戶和 Claude 之間的交流帶寬呢？

嘗試 1：編輯 ExitPlanTool

我們首先嘗試的是向 ExitPlanTool 添加一個參數，以便在計劃旁邊放置一系列問題。這是最容易實現的事情，但這讓 Claude 感到困惑，因為我們同時要求制定一個計劃，并提出一系列關于計劃的問題。如果用戶的回答與計劃內容相沖突怎么辦？Claude 需要調用 ExitPlanTool 兩次嗎？我們需要另一種方法。

（你可以在我們關于提示緩存的文章中閱讀更多關于我們為什么 要創建 ExitPlanTool 的信息）

嘗試 2：改變輸出格式

接下來，我們嘗試修改 Claude 的輸出指令，以使用稍微修改的 markdown 格式來提問。例如，我們可以要求它輸出一個帶有括號中替代選項的要點問題列表。然后，我們可以解析該問題并將其格式化為用戶的 UI。

雖然這是我們能做的最通用的更改，Claude 甚至似乎能夠很好地輸出這個，但這并不能保證。Claude 會附加額外的句子，省略選項，或者完全使用不同的格式。

嘗試 3：AskUserQuestion 工具

最后，我們決定創建一個 Claude 可以在任何時候調用的工具，但特別提示在計劃模式期間這樣做。當工具觸發時，我們會顯示一個模態框來顯示問題，并阻止智能體的循環直到用戶回答。

這個工具允許我們提示 Claude 進行結構化輸出，并幫助我們確保 Claude 給用戶提供多個選項。它還為用戶提供了組合此功能的方法，例如在代理式 SDK 中調用它或在技能中引用它。

最重要的是，Claude 似乎很喜歡調用這個工具，我們發現它的輸出效果很好。即使是最好的設計工具，如果 Claude 不知道如何調用它，也是行不通的。

這是 Claude Code 中啟發的最終形式嗎？我們不確定。正如你將在下一個例子中看到的，適用于一個模型的方法可能不適用于另一個模型。

更新能力：任務和待辦事項

當我們第一次發布 Claude Code 時，我們意識到模型需要一個待辦事項列表來保持它的正常運行。可以在開始時編寫待辦事項，并在模型工作時進行檢查。為此，我們給了 Claude TodoWrite 工具，它可以編寫或更新待辦事項并將其顯示給用戶。

但即便如此，我們也經常看到 Claude 忘記了它的職責。為了適應這種情況，我們每 5 個回合就會插入系統提醒，提醒 Claude 它的目標。

但隨著模型的改進，它們不僅不需要被提醒待辦事項列表，而且還會發現它的局限性。收到待辦事項清單的提醒使 Claude 認為它必須堅持而不是修改它。我們還看到 Opus 4.5 在使用子智能體方面做得更好，但是子智能體如何在共享的待辦事項列表進行協調呢？

看到這一點，我們用任務工具代替了 TodoWrite（閱讀更多 關于任務的內容）。待辦事項的作用是保持模型的正常運行，而任務的作用更多的是幫助智能體相互溝通。任務可以包括依賴關系，在子智能體之間共享更新，模型可以更改和刪除它們。

隨著模型功能的增加，你的模型曾經需要的工具現在可能會限制它們。重要的是要不斷地回顧之前關于需要什么工具的假設。這也是為什么堅持支持一小組具有相當相似的功能配置文件的模型是有用的。

設計一個搜索界面

對 Claude 來說，一組特別重要的工具是搜索工具，可以用來構建自己的上下文。

當 Claude Code 首次推出時，我們使用了一個 RAG 向量數據庫來查找 Claude 的上下文。雖然 RAG 功能強大且速度快，但它需要索引和設置，并且在許多不同的環境中可能很脆弱。更重要的是，Claude 被賦予了這個上下文，而不是自己找到上下文。

但如果 Claude 能在網絡上搜索，為什么不搜索你的代碼庫呢？通過給 Claude 一個 Grep 工具，我們可以讓它自己搜索文件和構建上下文。

這是我們看到的一個模式，隨著 Claude 變得越來越聰明，如果給它合適的工具，它就會越來越善于構建它的環境。

當我們引入智能體技能時，我們正式定義了漸進式披露的概念，它允許智能體通過探索逐步發現相關的上下文。

Claude 可以讀取技能文件，然后這些文件可以引用模型可以遞歸讀取的其他文件。事實上，技能的一個常見用途是為 Claude 添加更多的搜索功能，比如告訴它如何使用 API 或查詢數據庫。

在一年的時間里，Claude 從不能真正建立自己的上下文，到能夠在幾層文件中進行嵌套搜索，以找到它所需要的確切上下文。

漸進式披露現在是我們在不添加工具的情況下添加新功能的常用技術。

漸進式披露：Claude Code 指南智能體

Claude Code 目前有大約 20 個工具，我們不斷地問自己是否需要所有這些工具。添加新工具的門檻很高，因為這給模型提供了更多的選擇。

例如，我們注意到 Claude 對如何使用 Claude Code 了解不夠。如果你問它如何添加 MCP 或者斜杠命令的作用，它將無法回答。

我們本可以將所有這些信息放在系統提示中，但考慮到用戶很少詢問這些信息，這將增加上下文的腐朽并干擾 Claude Code 的主要工作：編寫代碼。

相反，我們嘗試了一種漸進披露的形式。我們給了 Claude 一個文檔的鏈接，他可以下載這個鏈接來搜索更多的信息。這是有效的，但我們發現 Claude 會把很多結果放到上下文中來找到正確的答案，而你真正需要的只是答案。

因此，我們構建了 Claude Code 指南子智能體，當你詢問它自己時，Claude 會被提示調用，子智能體有關于如何很好地搜索文檔以及返回什么內容的大量說明。

雖然這不是完美的，Claude 仍然會感到困惑，當你問它如何設置自己，它是比以前好得多！我們能夠在不添加工具的情況下向 Claude 的動作空間添加東西。

是藝術，不是科學

如果你希望有一套關于如何構建工具的嚴格規則，很遺憾，這不是本指南。為模型設計工具既是一門科學，也是一門藝術。這在很大程度上取決于你正在使用的模型，智能體的目標以及它所處的環境。

經常實驗，閱讀你的成果，嘗試新事物。像一個智能體一樣看待問題。

https://x.com/trq212/status/2027463795355095314

會議推薦

QCon 全球軟件開發大會·2026 北京站將于 4 月 16 日 -18 日正式舉辦。本屆大會以“Agentic AI 時代的軟件工程重塑”為主題，聚焦 100+ 重磅議題，匯聚來自阿里、騰訊、字節跳動、小米、百度等一線科技企業與創新團隊的技術專家，圍繞 AI 工程化、系統架構與研發模式演進展開深入探討。更多詳情可掃碼或聯系票務經理 18514549229 進行咨詢。

今日薦文

你也「在看」嗎？