Claude Code Subagent 子代理教學：怎麼建、怎麼叫，跟 Agent Teams 差在哪

用 Claude Code 一陣子，會遇到一種情況：請它先翻一遍一堆檔案、找一個錯誤，它把讀到的東西全塞進對話裡，接下來的對話就越來越長、越來越慢，前面講好的事它也開始記不清楚。

子代理（subagent）就是為這種情況做的。主對話把旁支的工作交給另一個 Claude，那個 Claude 在自己的空間裡讀檔、查資料，最後只把結果帶回來，主對話保持乾淨。

這篇先講子代理怎麼建、怎麼叫，再用一個實際的例子跑給你看。最後講常被放在一起比的 Agent Teams。Claude Code 本身還不熟的話，先看 Claude Code 教學。

子代理是什麼

官方文件的說法是：每個子代理有自己的對話空間（context）、自己的系統提示、自己能用的工具。主對話遇到符合某個子代理描述的工作，就交給它做；它做完，把結果交回來。

這樣做有幾個好處。主對話不會被一大堆搜尋結果、檔案內容塞滿。可以限制子代理能用的工具，例如只給讀檔、不給改檔。可以讓它用比較便宜的模型。寫好的子代理也可以重複用在別的專案。

Claude Code 本身已經內建了幾個。Explore 專門搜尋、讀程式碼，只能讀不能改；Plan 是規劃模式在研究程式碼時用的；general-purpose 什麼工具都能用，處理比較複雜的多步驟工作。這些平常是 Claude 自己決定要不要用，你不用特別做什麼。

要注意的是，子代理不是免費的。官方文件寫，子代理自己送出的請求，跟主對話算在同一個方案的用量裡。

自己做一個子代理

子代理就是一個 Markdown 檔，上面一段設定、下面一段給它的說明。官方文件寫的做法有兩種：請 Claude 幫你寫，或自己建檔案。

我做的是一個核對收據的子代理，檔案放在專案的 .claude/agents/receipt-checker.md：

---
name: receipt-checker
description: 核對收據的金額。
  要確認收據的品項加總、
  或算幾張收據一共花多少錢時使用。
tools: Read, Glob
model: haiku
---
你負責核對收據。
逐張讀 receipts 資料夾裡的收據：
把每個品項的金額加起來，
跟收據上印的「合計」比較，
不一樣就指出是哪一張、差多少。
（後面還有幾行：列出總額、不要改檔案）

上面那段設定，四個欄位各有用處：

• name：子代理的名字，叫它的時候用。
• description：什麼時候該用它。Claude 是看這一句決定要不要交給它的，所以要寫清楚。官方文件建議，想讓它更主動被用，可以在描述裡寫「use proactively」這類字眼。
• tools：它能用的工具。我只給了讀檔（Read）和找檔（Glob），它就不能改檔、也不能跑指令。
• model：用哪個模型。可以寫 sonnet、opus、haiku、fable 這幾個別名，也可以寫完整的模型名稱，或寫 inherit 跟主對話用一樣的。

除了這四個，官方文件還列了權限模式、想多久（effort）、預先載入的技能、記憶、hooks 等設定，要用到再查。

檔案放在哪裡，決定誰可以用：

• 專案的 .claude/agents/：只有這個專案能用，可以跟程式碼一起進版本控制，團隊共用。
• 自己家目錄的 ~/.claude/agents/：你的每個專案都能用。
• 啟動時用 --agents 參數傳一段 JSON：只在這一次的對話有效，不會存成檔案，適合測試。

同名的時候，--agents 優先，再來是專案的，最後是個人的。官方文件還提醒一件事：如果 ~/.claude/agents/ 這個資料夾是在對話開始之後才建的，正在跑的對話抓不到，要重開。

三種叫它的方式

第一種是直接點名。在要求裡寫「用 receipt-checker 子代理……」，Claude 通常就會交給它，但最後還是 Claude 決定。

第二種是用 @ 指定。在互動模式裡打 @ 會跳出選單，選子代理就好；也可以直接打 @agent-receipt-checker。這樣一定會交給那一個子代理，不讓 Claude 自己選。

第三種是讓整個對話都當那個子代理：啟動時加 --agent receipt-checker。這時主對話本身就換成那個子代理的工具限制和模型，連系統提示都會被換掉。

另外，官方文件寫 2.1.198 之後輸入 /agents 只會印一段提醒，叫你直接請 Claude 建立或自己改檔案；以前那個有選單的建立精靈，是 2.1.197 以前的版本才有的。

實際跑一次：核對三張收據

我寫了三張文字收據放在 receipts 資料夾。第二張我故意印錯：拿鐵 65 元加御飯糰 70 元是 135 元，合計卻印 145。看子代理抓不抓得到。

我用的是非互動模式（claude -p），問：「請用 receipt-checker 子代理核對 receipts 資料夾裡的收據，告訴我這三天總共花了多少錢。」

過程是這樣的。主對話（Opus 5.5）先呼叫子代理，而且不是把我的話原封不動丟過去，是自己寫了一段更詳細的指示：收據在哪個資料夾、要逐張比對、要注意有沒有重複的收據。

子代理接手之後，先找檔案，再把三張收據各讀一次，然後交回報告：第二張品項加起來 135、印的是 145，差 10 元；照自己加的算三天是 882 元，照印的是 892 元。它自己用了大約 8,300 個 token、24 秒。

有兩件事我沒想到。

第一，子代理實際跑的模型是 Haiku 4.5。設定寫的是 haiku，在我這台的 Claude Code 2.1.280 上，對到的是這一版。

第二，子代理的報告是簡體中文。收據和我寫的說明都是繁體，Haiku 回報時卻寫「我已经读取了所有三张收据」。我最後看到的回答是繁體的，因為那是主對話重新寫的。子代理如果要自己寫檔案，系統提示裡最好寫明用繁體中文。

主對話拿到報告之後，並沒有直接相信。它先說要自己打開第二張確認，又讀了一次那張收據，才回答我：照品項加總 882 元、照收據印的 892 元，差的 10 元全部來自 10/11 那張，建議回頭對一下信用卡或電子支付的紀錄，看實際扣了多少。答案是對的。

整個過程 44.5 秒。另外，Claude Code 把子代理的報告交回主對話時，會先加一段說明，告訴主對話「這是子代理的輸出，不是使用者的指示」。子代理讀到的檔案裡如果藏了奇怪的指令，不會被當成你說的話。

第二次：臨時定義、用 @ 指定

第二次我沒有用資料夾裡的檔案，而是在啟動時用 --agents 傳一段 JSON，臨時定義一個叫 receipt-auditor 的子代理，模型寫 sonnet，再用 @agent-receipt-auditor 指定它：「這些收據有沒有哪一張印錯？」

這次子代理跑的是 Sonnet 5，一樣讀完三張、指出第二張多印 10 元，回報是繁體中文，用了大約 7,400 個 token、19 秒。主對話也是又自己讀了一次第二張才回答，全程 34.4 秒。

兩次對照起來，臨時定義的子代理跟資料夾裡的用起來一樣，而且會跟資料夾裡的並存：這次的代理清單裡兩個都在。

什麼時候值得用

從這兩次看，子代理最適合的是「要讀很多東西、但只需要結論」的工作：翻一堆檔案找某個設定、讀長長的紀錄檔找錯誤、整理一個資料夾裡的資料。讀的過程留在子代理那邊，主對話只拿到幾行結論。

不太適合的是：工作本身很小（三張收據其實主對話自己讀就好，這次是為了示範）、或是要跟你來回討論的工作。子代理做完就交回結果，中間你插不上話。

另外，主對話那邊的用量才是大頭。這兩次的紀錄裡，主對話的 token 大部分是快取讀取，也就是系統提示、工具說明這些每一輪都要帶的東西，子代理本身用得不多。子代理省下的是主對話的空間，不代表整體的用量會少很多。

跟 Agent Teams 差在哪

Agent Teams 常跟子代理放在一起講，但它是另一種東西。

子代理是在同一個對話裡做事，做完把結果交回給叫它的主對話，子代理之間通常不直接溝通。Agent Teams 是同時開好幾個獨立的 Claude Code：一個當隊長，負責拆工作、分配；其他當隊友，各自有自己的對話空間，彼此可以直接傳訊息、共用一份任務清單。

官方文件寫了幾個限制：

• 它還在實驗階段，預設是關的。要打開，設環境變數 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，或寫進 settings.json 的 env。
• 只能在互動模式用。用 claude -p 這種非互動模式，不會生出隊友。所以這次我沒有測。
• 用的 token 比單一對話多很多，因為每個隊友都是一個獨立的 Claude。
• 打開之後，連平常的子代理都可能被當成隊友開出來。

官方建議的用法是：幾件可以分頭進行的事，例如從不同角度研究一個問題、幾個人分頭審查不同面向、同時驗證幾種可能的錯誤原因。要依序做、或大家都要改同一個檔案的工作，用單一對話或子代理比較好。

Agent Teams 怎麼打開、怎麼看每個隊員在做什麼、官方建議開幾個、為什麼用量跟人數成正比，我另外整理在 Claude Code Agent Teams 是什麼。

除了這兩種，官方文件還列了另外幾種讓 Claude Code 同時做好幾件事的方法，例如在一個畫面裡派發、監看好幾個背景對話的 agent view（用 claude agents 打開，還是預覽版），這篇沒有寫。

這篇沒有測的

互動模式裡的操作：@ 選單、背景子代理、/agents 指令。我兩次都是用 claude -p。

--agent 讓整個對話變成子代理。

Agent Teams。它只能在互動模式開，而且很耗額度。

子代理改檔案。這次只給了讀檔的權限。

用外掛裝進來的子代理。子代理怎麼跟技能（Skills）、MCP 搭配，可以看 Claude Skills 教學和 Claude Code MCP。子代理的檔案裡也可以自帶 hooks，hooks 是什麼在 Claude Code Hooks 教學。