Claude Code Subagents（子代理）怎麼用：創建、調用與最佳實踐

本文根據 Claude Code 官方文檔《Create custom subagents》整理，核對日期 2026-10-07。示例改寫自官方示例。

適用於誰

• 用 Claude Code 跑測試、翻日誌、搜代碼時，主對話很快被大段輸出塞滿的人；
• 想要一個「只讀的代碼審查員」「專門修測試的助手」並反覆使用的人；
• 搜「claude code subagents 如何使用」「subagent 最佳實踐」「subagent model config」的人。

結論先說

1. 子代理（subagent）= 一個有獨立上下文的專用助手：有自己的系統提示詞、可用工具和權限。它在自己的上下文裏幹完髒活，只把結論交回主對話，所以主對話不會被搜尋結果、日誌撐爆。
2. 子代理的請求和主對話算在同一份用量裏，並行開很多個會更快消耗額度。
3. 創建方法：在 .claude/agents/（當前項目）或 ~/.claude/agents/（所有項目）放一個帶 YAML 頭的 Markdown 文件；也可以直接讓 Claude 幫你寫。
4. 調用有三種：自然語言點名、@ 提及（保證一定用它）、claude --agent 名字 讓整個會話以它的身份運行。
5. description 決定 Claude 什麼時候自動委派給它，要寫清楚、寫簡短。

內置的子代理

不用配置就有，Claude 會在合適的時候自動使用：

官方說明：Explore 和 Plan 為了快和省，不讀取你的 CLAUDE.md；其他內置和自定義子代理會讀取。想禁用某個內置子代理，在權限裏加 deny 規則，例如 "deny": ["Agent(Explore)"]。

第一步：創建一個子代理

方法一：讓 Claude 幫你寫

在會話裏直接說：

text
在 ~/.claude/agents/ 裏幫我建一個個人用的 code-improver 子代理：掃描文件，
從可讀性、性能、最佳實踐三方面提改進建議，每條都說明問題、貼出原代碼、給出改進版。
它只能讀不能改，使用 sonnet 模型。

Claude 會生成一個包含 name、description、tools、model 和系統提示詞的文件。注意：現在的 /agents 命令只會提醒你「讓 Claude 創建或直接編輯目錄」，舊版本（v2.1.197 及以前）才有交互式嚮導。

方法二：自己寫文件

.claude/agents/code-reviewer.md：

markdown
---
name: code-reviewer
description: 代碼審查專家。在寫完或修改代碼後主動使用，檢查質素、安全與可維護性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一名資深代碼審查員。被調用時：
1. 運行 git diff 查看最近的改動
2. 只關注被修改的文件
3. 立即開始審查

檢查清單：命名清晰、無重複代碼、錯誤處理完善、沒有暴露密鑰、做了輸入校驗、測試覆蓋充分。

按優先級輸出：
- 嚴重問題（必須修）
- 警告（應該修）
- 建議（可以改進）
每條附上具體修改示例。

這個審查員只給了讀文件和執行命令的工具，沒有 Edit / Write，所以它只能提意見、改不了代碼。文件儲存後幾秒內就會被識別，不用重啟；唯一例外是 agents 目錄本來不存在、本次會話裏才新建的，需要重啟一次。

放在哪裏

同名時用優先級高的那個。

第二步：常用 frontmatter 字段

只有 name 和 description 是必填的；字段名要和官方表格完全一致（駝峰寫法），拼錯會被靜默忽略。

模型怎麼決定：按順序取第一個有值的——本次調用時 Claude 傳的 model 參數 → 子代理文件裏的 model → 環境變量 CLAUDE_CODE_SUBAGENT_MODEL → 主對話的模型。想把所有子代理統一跑在某個便宜模型上，在設定的 env 裏同時設 CLAUDE_CODE_SUBAGENT_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1。運行中用 /tasks 可以看到每個子代理實際用的模型。

第三步：調用子代理

1. 自然語言點名（Claude 決定要不要委派）：

text
用 test-runner 子代理把失敗的測試修好
讓 code-reviewer 子代理看看我最近的改動

2. @ 提及（保證這次一定用它）：輸入 @ 從列表裏選，或手動輸入 @agent-code-reviewer 看一下登入模組的改動。

3. 整個會話都用它：

bash
claude --agent code-reviewer

此時主線程直接採用它的工具限制、模型和系統提示詞。想在某個項目裏預設這樣，在 .claude/settings.json 寫 "agent": "code-reviewer"。

前台與後台：前台子代理會阻塞主對話直到完成；後台子代理和你並行工作，需要權限時會在主會話裏彈出確認並標明是哪個子代理在問。交互式會話裏預設後台運行；按 Ctrl+B 可以把正在運行的任務放到後台。

官方推薦的幾種用法

• 隔離大量輸出：「用一個子代理跑完整測試，只彙報失敗的用例和報錯訊息」。測試日誌留在子代理裏，主對話只拿到結論。
• 並行調研：「分別用獨立的子代理並行研究認證、數據庫、API 三個模組」。適合彼此不依賴的調查。
• 串聯：「先用 code-reviewer 找性能問題，再用 optimizer 子代理修掉」。
• 限制權限：只讀的審查員、只能跑 SELECT 的數據庫查詢員（官方示例用 PreToolUse Hook 攔截寫操作）。
• 控制成本：把簡單、量大的工作交給用 Haiku 的子代理。

什麼時候不要用子代理（官方建議留在主對話）：需要頻繁來回溝通、多個階段共享大量上下文、只是改一個小地方、對響應速度敏感（子代理從零開始，要花時間收集上下文）。對已經在對話裏的內容提個小問題，用 /btw 更合適。想複用的是一段提示詞或流程而不是隔離環境，用 Skills。

常見問題

Q：新建的子代理 Claude 找不到？

檢查文件開頭第一行就是 ---、有 name 和 description、YAML 能正常解析；agents 目錄是本次會話中途新建的話要重啟。用 claude --debug 啟動可以在調試日誌裏看到被跳過的原因。

Q：一次能同時跑多少個子代理？

官方預設同一會話最多 20 個子代理同時運行，再開會報 Concurrent subagent limit reached，等數量降下來才能繼續；可以用環境變量 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整。會話總共能開多少個沒有上限。

Q：子代理會不會更費額度？

會。每個子代理都在消耗 token，並且結果回到主對話也占上下文。並行開很多個、每個都返回長篇結果，消耗會明顯變快。額度規則詳見本站《Claude 使用限制與額度：用量怎麼看、什麼時候重置（Free / Pro / Max / Claude Code）》。

Q：插件帶的子代理為什麼不能配 hooks / mcpServers？

官方出於安全考慮，插件子代理會忽略 hooks、mcpServers、permissionMode 三個字段。需要的話把文件複製到 .claude/agents/ 或 ~/.claude/agents/。

Q：子代理、後台會話、Agent Teams 有什麼區別？

子代理在一個會話內部工作、向主對話彙報；後台會話是多個獨立會話並行；Agent Teams 是由 Claude 創建並監督的一組會話互相協作。規模越大越往後選，詳見官方《Run agents in parallel》。

參考資料

• Create custom subagents（官方）：https://code.claude.com/docs/en/sub-agents
• Run agents in parallel（官方）：https://code.claude.com/docs/en/agents
• Orchestrate teams of Claude Code sessions（官方）：https://code.claude.com/docs/en/agent-teams
• Configure permissions（官方）：https://code.claude.com/docs/en/permissions