# 如何在 Claude Code 中使用巢狀子代理委派大型任務 > Anthropic 在 v2.1.172 中讓 Claude Code 子代理可以再產生自己的子代理，最多深入 5 層。本文說明如何委派大型任務。 Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-nested-subagents/ Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-nested-subagents/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-232 Revision: sha256-c51e34cb2777fc8a68df906589f0b2e504fb5160761c357c8d6ae8e3378ac5f9
[Ailoot 說明文件](https://ailoot.ai/docs/) — 使用此服務的參考資料。
## Claude Code v2.1.172 有哪些變更？
重點摘要 Anthropic 推出了 v2.1.172，並在變更記錄中用一句話移除了一條沿用兩年的規則。子代理現在可以再產生自己的子代理，最多深入 5 層。這項功能的重點不是速度，也不是增加 CPU。主要概念是讓嘈雜的準備工作不要塞滿你的主要上下文。
過去幾個月，只要你讀過任何關於 Claude Code 中 AI 代理的內容，就會看到同一句話。它出現在官方說明文件、我的[子代理指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-subagents/)以及每一份競品分析中。內容是：「子代理不能再產生另一個子代理。」截至 2026 年 6 月 11 日，`code.claude.com/docs/en/sub-agents` 上仍有三處寫著這句話。Anthropic 只是還沒更新它。 6 月 10 日 20:44 UTC，Claude Code v2.1.172 出現在 GitHub Releases 上。變更記錄的主要項目只有一句話：
子代理現在可以再產生自己的子代理，最多深入 5 層。
— Claude Code 變更記錄，https://github.com/anthropics/claude-code/releases/tag/v2.1.172
這次發布也修正了一個只有在巢狀情境中才會發生的錯誤：背景子代理啟動的巢狀子代理已停止後，它在代理面板中仍會被標示為作用中。 這是官方說明文件仍與已發布版本相矛盾的罕見情況。接下來我會說明巢狀與平行子代理有何不同、「深度 5」代表什麼，以及目前真正實用的三種情境。 ## 巢狀子代理與平行及循序子代理有何不同？
重點摘要 如果你感到困惑，你並不孤單。平行、串接和巢狀是三種彼此正交的拓撲。平行關乎速度，串接關乎建立執行順序，而巢狀關乎另一件事：它會把嘈雜的工作藏在主視窗之外。把它們混為一談，幾個小時內就會耗掉一堆 token，最後還找不到錯誤在哪裡。
我花了很長時間親手試這三種方式，以下是我的理解：委派有三個維度：寬度、長度和深度。每一種都解決不同問題。 **寬度——平行子代理。** 主對話會在同一層啟動 N 個互不依賴的子代理。每個子代理都會收到一項範圍狹窄的任務，在自己的隔離視窗中工作，並且只回傳結果。寬度解決速度問題：5 個子代理平行工作，完成所需時間與 1 個子代理循序完成相同工作一樣。這是我在[使用 worktree 的平行子代理指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-parallel-worktree-agents/)中介紹的模式。 **長度——子代理鏈。** A 工作，將結果交給 B；B 工作，再交給 C。每個子代理都會看到前一個子代理的輸入。長度建立順序：B 必須先取得 A 的資料才能開始。典型例子是：先由研究子代理收集來源，再由編輯子代理根據來源撰寫文章，接著由事實查核子代理檢查文章。這是一段平坦的序列；主對話掌握整個故事脈絡。 **深度——巢狀子代理。** A 啟動 B，B 啟動 C，C 啟動 D。每個子代理都在自己的父代理之內、於各自隔離的視窗中工作，並且只將**結果**回傳給父代理。主對話看不到子代理、孫代理和曾孫代理所做的任何事。這是 v2.1.172 的新功能。 最大的誤解是人們以為深度 5 代表「你可以同時啟動 5 個子代理」。並非如此。深度是樹狀結構中的垂直層級，不是同時啟動的子代理數量。每一層可以有一個子代理，也可以有一百個。深度 5 表示委派鏈可以向下延伸 5 步：主對話 → 曾孫代理-1 → 曾孫代理-2 → 曾孫代理-3 → 曾孫代理-4 → 曾孫代理-5。每一層都可以分支。 2.1.172 版本移除了子代理不能再產生另一個子代理的規則。 如果你追求速度，就需要寬度。如果你有嚴格的執行順序，就需要長度。深度只在一種情況下有用：當你的某項任務包含一個**嘈雜的子任務**（15 次網頁請求、遍歷日誌、讀取十幾個檔案），而你不希望這些雜訊湧進主視窗。 ## 「深度 5 層」實際上代表什麼？
重點摘要 5 層是從主對話到最遠的曾孫代理之間的垂直最大距離。這是伺服器端限制；你無法提高、降低，也無法用旗標將它關閉。官方來源也尚未說明主對話本身是否算在這 5 層之內。
這裡有個重要的坦白。我花了半天查閱說明文件和社群分析，才發現 Anthropic 沒有給出精確定義。你需要知道的是： **這是上限，不是設定。** 這項限制內建於伺服器端。對用戶端 v2.1.172 進行逆向工程，沒有發現 `MAX_DEPTH` 常數。這表示檢查發生在 Anthropic API 的某處，而不是你的本機電腦。你不能設定 `--max-depth 7` 讓樹長得更深，也不能設定 `--max-depth 2` 來設下更低、更安全的上限。你唯一能控制的是 frontmatter 中的 `Agent(agent_type)` 允許清單，但它限制的是子代理的**類型**，而不是深度。 **Anthropic 尚未精確定義「5」的含義。** 這是第二個重要之處： **Anthropic 並未明確定義「5」的意思。** 官方來源沒有說明 depth=5 代表根節點下方有五層，還是總共五個代理，包括根節點在內。 第三方整合目前有不同解讀。`ruvnet/ruflo` 專案中的 ADR-147 假設「根節點下方有 5 層子節點 = 鏈中有 6 個代理」。我在實驗中也採用相同慣例：主對話是第 0 層，它的直接子代理是第 1 層，依此類推到第 5 層。但這項慣例並未記載於公開說明文件中。 **限制已啟用，不需任何旗標。** 你不需要啟用任何設定。將 Claude Code 更新至 v2.1.172 後，只要在子代理的 `tools` 中加入 `Agent`，它就能啟動另一個子代理。關鍵是父代理必須允許這項功能（`tools: Agent(...)`）。 ## 你目前如何委派工作：寬度、長度，還是深度？
重點摘要 在實際的 vibe-coding 專案中，我幾乎總是看到寬度，偶爾看到長度。人們會手動處理深度：開一個新視窗、複製提示詞，完成後再把結果帶回來。6 月 9 日之前，這項功能並未內建。這就是為什麼多數人甚至沒發現自己少了它。
回顧你最近 5 個提示詞。有多少次發生過這種情況：任務開始後，Claude 就開始 grep 檔案、提出 10 次網頁請求、把整面牆的日誌倒進上下文——20 分鐘後你才發現視窗已經塞滿。最後的答案只能在所剩無幾的 token 預算下執行，因為 70 percent 的上下文都被中間輸出用掉了。 這種情況就需要**深度**。不是平行，也不是串接，而是深度。主對話應該把「研究」委派給一個子代理，接著由該子代理在內部啟動自己的子代理，分別進行特定的網頁搜尋、讀檔和 grep。子代理只回傳整理過的判斷。曾孫代理告訴父代理：「找到了，已確認」或「沒找到，原因是 X」。父代理將這些結果整理成單一摘要，再回傳給你。主對話保持整潔。 6 月 9 日之前，我是手動模擬這種做法。我開啟 Claude Code 的第二個執行個體，複製「研究這個」的提示詞，執行後再手動把結果轉回主視窗。我在關於委派程式撰寫給眾多 AI 代理的指南中詳細介紹過這套配置。使用 v2.1.172 後，你可以直接在協調器的系統提示詞中描述這套流程——Claude 會自行建立樹狀結構。 ## 巢狀子代理實際上在哪 3 種情境中有用？
重點摘要 不是每項任務都適用。當某次委派包含一個你不希望放進主視窗的嘈雜子任務時，深度才有其價值。我會介紹 vibe coder 中最常見的三種典型情境：深入研究並查核事實、分析大型儲存庫，以及稽核結構描述或契約變更的端到端相依項目。
### 情境 1. 深入研究並查核事實 假設你正在為一篇文章或銷售提案蒐集資料。你需要先從公開來源找出 5–10 項主張，再逐一查證——找出原始來源、確認引文精確無誤，並計算實際數字。 v2.1.172 之前，你有兩種選擇。你可以讓一個子代理全權處理，讓它辛苦完成 30 次網頁請求，把所有內容塞進自己的上下文；也可以手動拆分：用一個提示詞擷取主張，再逐一處理這些主張，每項都啟動一個獨立子代理。主對話會被一大堆中間清單塞滿。 下方配方中，主對話先委派 `research-orchestrator`（第 1 層），協調器自行擷取主張，逐項交給 `fact-verifier`（第 2 層），每位驗證者再將聚焦搜尋交給 `web-deep-search`（第 3 層）。主對話只會收到包含已查證主張和來源的陣列。其他內容都留在子代理視窗中，不會進入你的上下文。 ### 情境 2. 分析大型儲存庫 你收到一個有 200 個檔案的專案。你需要了解架構、找出主要模組，並評估技術債。手動執行 `Glob` 加上十幾次 `Read` 呼叫，10 分鐘內就會塞滿視窗。 深度能這樣解決問題：主對話啟動一個「architect」子代理。architect 在內部產生三個子代理——一個檢查目錄結構（執行 `Glob` 並整理摘要），第二個讀取 5 個關鍵設定檔，第三個 grep 主要模式。每個子代理都會把簡潔摘要回傳給 architect。architect 整理出全貌，再向主對話提供一份半個畫面長的報告。你能取得專案地圖，而不用讓所有檔案的 `cat` 輸出像一面牆一樣塞滿上下文。 ### 情境 3. 分析端到端相依項目 你正在變更資料庫結構描述、API 契約或共用設定檔。你需要了解哪些地方會受到影響。這項任務最容易耗盡上下文，因為相依項目很多，而且每一項都必須在原始碼中檢查。 使用深度時，主對話啟動一個「impact-analyzer」（第 1 層）。它會為每個受影響的檔案啟動一個 `dependency-tracer`（第 2 層）。每個 tracer 再於內部啟動一個 `consumer-finder`（第 3 層），在程式碼庫中 grep 這項相依內容的使用者。每個代理都只回傳摘要：「這三個地方會出問題。」主對話整理出「受影響檔案 → 影響」表格，而不必知道 grep 的結果細節。 ## 如何在 10 分鐘內設定巢狀子代理
重點摘要 不需要旗標，也不需要更新設定。只要在子代理的 `tools` 中加入 `Agent`，它就能啟動自己的子代理。若要避免代理樹變成賭場，請使用 `Agent(name1, name2)` 允許清單。接下來，我會提供一個可直接使用的三層協調器範本，供你複製。
**步驟 1. 確認你使用的是 v2.1.172 或更新版本。** ```bash claude --version ``` 如果版本較低，就進行更新。這次發布的主要功能在變更記錄中只有一句話：「子代理現在可以再產生自己的子代理，最多深入 5 層」（[完整內容](https://github.com/anthropics/claude-code/releases/tag/v2.1.172)）。 **步驟 2. 建立一個可以產生子代理的父代理。** 檔案 `.claude/agents/research-orchestrator.md`： ```markdown --- name: research-orchestrator description: Delegates research with a deep fact-check tools: Agent(fact-verifier), Read, WebFetch model: opus --- You are a research orchestrator. When you get a topic: 1. 閱讀提供的材料，或擷取提供的公開來源 URL。 自行擷取最多 5 項具體主張，逐項記錄主張文字、來源 URL 或檔案， 以及支持它的原文段落。若未提供來源材料，先詢問，勿直接委派。 2. For each claim call fact-verifier - it spawns its own child subagents for web search and cross-checking. 3. fact-verifier returns only the final verdicts to you - do not load intermediate dumps into your context. Final report - only an array { claim, sources[], confidence }. ``` `tools` 只授予 `fact-verifier` 子代理類型。擷取主張是協調器自己的第一步，因此不需要未定義的 `claim-extractor` 檔案。類型允許清單限制能叫誰，不限制同類型啟動次數；此配方仍應維持最多五項主張。 **步驟 3. 建立一個能自行產生曾孫代理的子代理。** 檔案 `.claude/agents/fact-verifier.md`： ```markdown --- name: fact-verifier description: Checks a claim through child web searches tools: Agent(web-deep-search), Read model: sonnet --- You are a fact-checker. When you get a claim: 1. Write 2-3 search queries. 2. For each one run web-deep-search - it will do WebSearch and WebFetch itself and return verified snippets. 3. Combine them into one verdict: { claim, sources[], confidence }. ``` 看到關鍵部分了嗎？`tools` 這行同樣寫著 `Agent(web-deep-search)`。這表示 fact-verifier（樹中的第 2 層）可以自行啟動另一個子代理（第 3 層）。以前這一行不起作用——說明文件中仍寫著：
子代理不能再產生其他子代理，因此 Agent(agent_type) 在子代理定義中不起作用。
— Claude Code 說明文件，https://code.claude.com/docs/en/sub-agents
在 v2.1.172 中，這句話已經過時。語法相同，但現在在樹狀結構的任何深度都能運作。 **步驟 4. 建立一個曾孫代理。** 檔案 `.claude/agents/web-deep-search.md`： ```markdown --- name: web-deep-search description: Runs a web search and returns snippets tools: WebSearch, WebFetch model: haiku --- You received a search query. Run WebSearch, pick the top 3 relevant URLs, use WebFetch to pull verbatim confirmations of the claim. Return an array { url, snippet, supports_claim: yes|no }. ``` 曾孫代理的 `tools` 中沒有 `Agent`，因此它不會繼續往下產生代理。 **步驟 5. 執行協調器。** ```bash claude --agent research-orchestrator ``` 接著在聊天提供來源文字或公開 URL：「從這些來源擷取並驗證最多 5 項具體主張，回傳主張、來源與信心。」以 `--agent research-orchestrator` 啟動時，工作階段本身就是協調器，下方有驗證與搜尋兩層委派；若一般主工作階段先委派協調器，下方則有三層委派。 ## 哪 5 種反模式會浪費 token 並破壞可觀測性？
重點摘要 深度很耗資源。每向下一層，token 數就會倍增，而且倍增效果會層層累積。以下是巢狀會造成傷害的五種情況。別這麼做——否則你會在一小時內耗盡每日預算，還會弄不清楚樹狀結構往下四層的錯誤在哪裡。
**反模式 1. 任務放在一個視窗就能完成。** 如果一個子代理就能在沒有雜訊的情況下處理，不要增加層級：巢狀只會徒增成本和延遲。 **反模式 2. 你追求的是速度，而不是隔離。** 如果你要速度，就需要**平行處理**，而不是深度。讓 5 個子代理在同一層並排啟動，而不是建立一條鏈。深度是為了把嘈雜的準備工作移到子代理視窗，不是為了加快速度。 **反模式 3. 工作本身很淺。** 「找到這個檔案並展示給我」是**兩步驟的要求**，不需要三層階層。只有在任務包含嘈雜的子任務時，巢狀才值得使用。沒有雜訊，就別增加子代理。 **反模式 4. 第一層提示詞含糊不清。** 這是最危險的情況。如果你給第 1 層協調器的提示詞很含糊，含糊程度就會跟著擴大。一個含糊的第 1 層提示詞會變成第 2 層的 4 個含糊提示詞，再變成第 3 層的 16 個。等曾孫代理開始工作時，它們甚至不知道自己要找什麼。 **反模式 5. 成本幾何級數成長。** 主要的經濟考量是：巢狀會讓 token 用量倍增，而倍增效果會隨深度累積。 粗略估算：每一層都以 3 個代理分支的深度 3 鏈，代表 27 個子代理。這至少會比簡單要求多消耗 27 倍的 token。使用 Claude 的 Pro 方案時，這樣的計算會在幾個小時內耗盡每日上限。如果你使用 Max 方案，一天就會用完一週的額度。 **額外反模式（我的經驗）：「50 個代理做無用功。」** 我看別人的專案時，常常會看到這種說法：「我有 50 個代理在工作。」我會問，它們在做什麼？結果那 50 個代理都在**做無用功**。它們產生一堆不必要的輸出、大量原始摘要、重複內容和整面牆的日誌。每個代理都在做一些「大致有用」的事，最後上下文被淹沒，token 帳單高得像小公司的開支。深度 5 解決不了這個問題——它只會**讓問題惡化**。如果在第 1 層就搞不清楚誰在做什麼，深度 5 代表五層混亂。 啟動任何子代理前，先花半分鐘回答 4 個問題： - 它確切會做什麼（一句話說明）？ - 它會碰哪些檔案？ - 它會回傳什麼給父代理？ - 誰會檢查它？ 如果你無法在 30 秒內回答，這個子代理就不該存在。我在[平行子代理指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-parallel-worktree-agents/)中另有說明這項規則。 ## 為什麼沒有上下文工程的巢狀會造成 5 層幻覺？
重點摘要 深層委派的主要陷阱是缺少任務背景。子代理不會自動得到父代理完整對話或所有已讀檔案；自訂子代理通常會載入適用的 CLAUDE.md 指示，除非設定略過，但不會因此自動讀取所有連結的業務檔案。每次交接都應傳遞確切材料、路徑與輸出契約。如果你的專案沒有穩固的上下文結構，樹越深，每個曾孫代理就越容易脫離現實。你會得到 5 層幻覺，每層各一層。
人們常常在這裡問我：「我更新了 Claude Code，也在 tools 加入了 Agent，代理樹也建立起來了——但最後的答案還是偏了。為什麼？」 答案很簡單。在 Claude Code 中，每個子代理都是**從頭開始**。官方說明文件指出：
每個子代理都會在全新、隔離的視窗中開始。它看不到對話歷史、你已呼叫的技能，也看不到 Claude 已讀取的檔案。
— Claude Code 說明文件，https://code.claude.com/docs/en/sub-agents
在第 1 層，這還可以掌控：協調器會把簡短的任務描述傳給子代理。但到了第 3 層，曾孫代理收到的是父代理傳來的委派訊息，而父代理也只有一則委派訊息。每一層傳下來的內容都少了一點。到了第 5 層，你會有一個視窗中只有「檢查主張 X」這句話的子代理，除此之外什麼都沒有。它不知道自己正在處理哪個專案、要解決什麼任務，也不知道應該關注什麼。 沒有 [CLAUDE.md](https://ailoot.ai/blog/zh-hant-tw/claude-md-template/) 的話，第五層的曾孫代理就像一名第一次到公司上班、完全沒有接受任何指引的員工。它會因為接到任務而做點事，但做的事不會符合專案需求。 ## 除了巢狀之外，v2.1.172 還改了什麼？
重點摘要 這次發布的內容全都圍繞子代理。除了主要功能之外，還包含 4 項委派基礎架構修正。其中一項修正了只有在巢狀情境中才會發生的錯誤。
開啟完整的 v2.1.172 變更記錄，就會看到整次發布都與子代理有關。 **修正 1.** 巢狀子代理停止後，背景子代理不會再一直「卡住」，在代理面板中維持作用中狀態。這個錯誤只會在巢狀情境中發生。 **修正 2.** `availableModels` 限制現在也會套用至子代理。以前，如果你限制團隊可使用的模型（例如禁止使用 opus 以節省費用），子代理可以在自己的設定中覆寫限制來繞過規則。v2.1.172 讓規則能套用到所有地方。 **修正 3.** 提示詞歷史中的向上箭頭現在會顯示子代理**目前**分頁中的提示詞，而不是主代理的提示詞。這是可觀測性方面的修整。 **修正 4.** 降低閒置時的 CPU 用量：閒置時，`/goal` 指示器不再以 5 Hz 重繪終端機，而平行子代理工作期間，UI 的重繪頻率也降低了。 我想指出，這四項修正都與子代理有關。這表示 Anthropic 發布的是整套巢狀基礎架構，而不只是變更記錄中的一行字。在公開之前，巢狀功能已經在 Anthropic 內部使用一段時間了。 ## 檢查清單：何時使用巢狀有幫助，何時有害
重點摘要 每次啟動新子代理前，都用 6 項檢查來評估任務。如果至少有 3 個答案是「是，使用深度」，就使用巢狀。如果不到 3 個，就採用平行處理或單一子代理。這能省下 token、精力，還有幾個小時的時間，避免你弄不清楚一串 27 次巢狀啟動到底在做什麼。
適合使用巢狀的情況： - 任務包含大量網頁請求、grep 或讀取檔案的子任務。 - 可以接受失去該子任務（如果曾孫代理回報「什麼也沒找到」，協調器可以繼續）。 - 你**不需要**在主視窗中查看中間結果。 - 你有 `CLAUDE.md` 和整理好的專案上下文，供子代理依據。 - 你能清楚描述每一層會回傳什麼（輸入、輸出、格式）。 - 你使用 Max 方案，或有足以負擔 ×27 token 的緩衝額度。 不適合使用巢狀的情況： - 一個子代理就能在沒有雜訊的情況下解決任務。 - 你需要在主視窗中查看中間結果（這表示你需要的是平行處理）。 - 專案沒有 CLAUDE.md，或只有零星的業務背景資訊。 - 第 1 層提示詞含糊（含糊程度會沿樹呈指數擴大）。 - 你需要速度——在結果相當的情況下，平行處理比深度更快。 - 你使用 Pro 方案而且整天都在工作——幾個小時內就會耗盡上限。
### 資料來源 - [Claude Code Release v2.1.172 - GitHub Releases](https://github.com/anthropics/claude-code/releases/tag/v2.1.172) - [建立自訂子代理 - Claude Code 說明文件](https://code.claude.com/docs/en/sub-agents)
更多資料請見 [Ailoot](https://ailoot.ai/)。 ## 常見問題：如何在 Claude Code 中使用巢狀子代理委派大型任務 ### 複製配方時需要另建 claim-extractor 嗎？ 不需要。修正後的 research-orchestrator 自行從提供材料擷取最多五項主張。建立 research-orchestrator、fact-verifier 與 web-deep-search 三個範例檔，再提供來源文字或 URL。 ### 只允許 fact-verifier，就會限制子代理啟動次數嗎？ 不會。代理類型允許清單限制可呼叫哪種類型，不限制呼叫幾次。此配方另外把初始擷取限制為五項主張，仍應監看實際呼叫與 token 用量。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。