配置 Subagents

Subagent 的價值不是“多開一個 AI”，而是把會汙染主會話的大量搜尋、日誌、檔案閱讀和專項判斷，隔離到另一個上下文裡，最後只把結論帶回來。——翔宇

這一章用 17 分鐘換什麼：上一章講了 Skills。Skills 解決“可複用知識和流程”；Subagents 解決“隔離上下文裡的專門 worker”。讀完你應該能判斷什麼時候用內建 Explore、什麼時候寫自定義 subagent、怎麼限制工具、怎麼預載入 Skills、怎麼處理後臺任務和 worktree 隔離。

1. Subagent 解決什麼問題

Subagent 是 Claude Code 裡的專門 AI assistant。它有自己的上下文視窗、系統提示詞、工具訪問和許可權設定。

適合用 Subagent：

讀很多檔案，但主會話只需要摘要。
搜尋大量日誌、測試輸出、文件或程式碼。
並行驗證多個獨立假設。
讓一個專門 worker 做安全審查、效能審查、測試審查。
用更快或更便宜的模型處理低風險探索。
給某類任務固定工具邊界，例如只讀 reviewer。

不適合用 Subagent：

單檔案小修改。
需要你頻繁來回確認的任務。
多階段共享大量上下文的主線實現。
需要 subagent 再繼續 spawn subagent 的巢狀流程。
只是想“看起來更自動化”的簡單任務。

第一性原理：Subagent 用來隔離中間過程，不是替代主會話。主會話負責目標、判斷和整合；Subagent 負責自包含子任務。

flowchart TD
    Task["當前任務"]
    Verbose["會產生大量中間資訊？"]
    NeedSummary["主會話只需要結論？"]
    Independent["子任務能獨立完成？"]
    NeedsChat["需要頻繁來回確認？"]
    UseSubagent["用 Subagent"]
    Main["留在主會話"]

    Task --> Verbose
    Verbose -->|否| Main
    Verbose -->|是| NeedSummary
    NeedSummary -->|否| Main
    NeedSummary -->|是| Independent
    Independent -->|否| Main
    Independent -->|是| NeedsChat
    NeedsChat -->|是| Main
    NeedsChat -->|否| UseSubagent

    style UseSubagent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Main fill:#e0f2fe,stroke:#0284c7,stroke-width:2px

2. 內建 Subagents

Claude Code 自帶幾個常用 Subagents。大多數時候你不需要手動配置它們，Claude 會自動判斷。

Explore：

快速、只讀。
官方定位是檔案發現、程式碼搜尋、程式碼庫探索。
模型偏快，適合低延遲探索。
不能寫檔案、不能編輯檔案。

Plan：

plan mode 裡使用。
用於正式給方案前收集程式碼庫上下文。
只讀，避免計劃階段誤修改。
防止 plan mode 中出現無限巢狀。

General-purpose：

能處理複雜多步任務。
可以探索，也可以修改。
使用主會話模型。
適合需要探索和行動結合的任務。

其他 helper agents：

statusline-setup：配置狀態列時使用。
claude-code-guide：回答 Claude Code 功能問題時使用。

新手預設策略：只讀探索先用 Explore；複雜多步但仍在一個會話內的子任務用 general-purpose；需要長期複用的角色再寫自定義 subagent。

3. Subagent 和 Skill 怎麼區分

Skill 和 Subagent 經常一起出現，但職責不同。

Skill：

是可複用知識或流程。
預設在主會話上下文裡執行。
可以由 /skill-name 呼叫。
適合 checklist、參考資料、釋出流程。

Subagent：

是一個獨立 worker。
有自己的上下文視窗。
最後把摘要返回主會話。
適合大量搜尋、專項審查、隔離探索。

組合方式：

Skill 透過 context: fork 啟動 subagent。
Subagent 透過 skills 欄位預載入指定 Skills。

判斷句：你要複用一套流程，用 Skill；你要隔離一個子任務，用 Subagent；你要兩者兼得，就讓 Skill fork 到 Subagent 或讓 Subagent 預載入 Skills。

4. Subagent 和 Agent team 怎麼區分

Subagent 執行在單個 Claude Code session 內，由主會話管理，只把結果回報給主會話。

Agent team 是多個獨立 Claude Code sessions 組成的團隊。一個 lead 負責協調，teammates 各自有獨立上下文，並且可以互相通訊。

Subagent 適合：

結果比過程重要。
worker 不需要互相交流。
子任務聚焦、短期、自包含。
你想降低主會話上下文汙染。

Agent team 適合：

多個 worker 需要互相挑戰、共享發現、協調任務。
大功能拆分。
多假設除錯。
前後端測試等跨層並行。

官方說明 Agent teams 目前仍是 experimental，需要顯式開啟，並且 token、協調和衝突成本更高。

不要把 Agent team 當預設並行方式：普通隔離和簡單並行先用 Subagent。只有 worker 需要彼此通訊時，才考慮 Agent team。

5. 建立入口：優先用 `/agents`

官方推薦入口：

/agents

這個介面可以：

檢視內建、user、project、plugin subagents。
建立新 subagent。
用 Claude 生成配置。
編輯 tool access。
刪除自定義 subagent。
看同名定義裡哪個當前生效。
在 Running tab 檢視正在執行的 subagents。

命令列只列出配置：

claude agents

手動寫檔案也可以，但直接改磁碟上的 subagent 檔案後，要重啟會話才會載入。透過 /agents 建立或編輯通常會立即生效。

先用 /agents 生成，再手動修：介面能幫你選 scope、tools、model、color、memory，減少 YAML 配錯。

6. Subagent 檔案放哪裡

Subagent 是 Markdown 檔案，帶 YAML frontmatter。

常見路徑：

Managed：組織級下發，優先順序最高。
CLI --agents：只在當前啟動會話生效。
Project：.claude/agents/<agent-name>.md，當前專案可用，可提交。
User：~/.claude/agents/<agent-name>.md，所有專案可用。
Plugin：<plugin>/agents/<agent-name>.md，外掛啟用時可用。

優先順序從高到低：

Managed settings
--agents CLI flag
Project .claude/agents/
User ~/.claude/agents/
Plugin agents

注意：

Project subagents 會從當前工作目錄往上發現。
--add-dir 只給檔案訪問，不會掃描裡面的 subagents。
Plugin subagents 會出現在 /agents，但有安全限制。

Project subagent 是團隊資產：如果一個 worker 是這個程式碼庫專用的，放 .claude/agents/ 並提交；如果只是你個人習慣，放 ~/.claude/agents/。

7. 最小檔案格式

一個基本 subagent：

---
name: code-reviewer
description: Reviews code for quality, security, maintainability, and missing tests. Use after code changes.
tools: Read, Glob, Grep, Bash
model: inherit
---

You are a senior code reviewer.

When invoked:

1. Inspect the recent changes.
2. Focus on modified files.
3. Identify correctness, security, maintainability, and test risks.
4. Return findings ordered by severity.

Output:

- Critical issues
- Warnings
- Suggestions
- Tests to run

Frontmatter 是配置。正文是 subagent 的 system prompt。

官方提醒：Subagent 不會繼承完整 Claude Code system prompt。它收到的是自己的 system prompt，加上基礎環境資訊，例如 working directory。CLAUDE.md 和專案 memory 會按正常訊息流載入。

正文要寫成角色說明，不是使用者請求：Subagent 檔案定義的是“這個 worker 是誰、何時做什麼、怎麼輸出”，不是某一次任務。

8. Frontmatter 欄位速覽

常用欄位：

name：唯一標識，必填，小寫字母和連字元。
description：Claude 判斷何時委派的依據，必填。
tools：允許使用的工具列表。省略時繼承主會話全部工具。
disallowedTools：從繼承或指定工具中移除。
model：使用 sonnet、opus、haiku、完整 model ID 或 inherit。
permissionMode：許可權模式，例如 default、auto、plan。
maxTurns：最多 agentic turns。
skills：啟動時預載入的 Skills。
mcpServers：只給這個 subagent 的 MCP server。
hooks：只在這個 subagent 生命週期內執行的 hooks。
memory：持久記憶 scope，支援 user、project、local。
background：設為 true 時預設後臺執行。
effort：該 subagent 的 reasoning effort。
isolation：設為 worktree 時使用臨時 git worktree。
color：UI 中顯示顏色。
initialPrompt：當它作為 main session agent 執行時自動提交的第一條使用者訊息。

新手先用五個欄位：name、description、tools、model、maxTurns。其他欄位等需求明確再加。

9. description 決定自動委派

Claude 會根據任務描述、當前上下文和 subagent 的 description 決定是否自動委派。

弱描述：

description: Helps with code.

強描述：

description: Reviews recently changed code for security issues, missing tests, risky migrations, and unclear error handling. Use proactively after code edits.

寫法原則：

寫任務型別。
寫觸發場景。
寫不負責什麼。
放關鍵詞在前面。
如果希望主動使用，寫清 Use proactively。

description 是路由規則：寫得越泛，越容易誤觸發；寫得越窄，越可能需要你顯式點名。

10. 模型選擇和優先順序

model 欄位可以設定：

haiku：快速、便宜，適合只讀探索。
sonnet：平衡質量和速度，適合 review、除錯、專項分析。
opus：更強推理，適合複雜架構判斷。
完整 model ID：精確指定。
inherit：繼承主會話。

官方模型解析優先順序：

CLAUDE_CODE_SUBAGENT_MODEL 環境變數。
某次 invocation 傳入的 model。
subagent 檔案裡的 model。
主會話模型。

成本策略：探索類用更快模型；關鍵審查和複雜診斷用更強模型；不確定時 inherit。

11. 工具邊界：`tools` 和 `disallowedTools`

預設情況下，subagent 繼承主會話所有工具，包括 MCP tools。

如果你想做只讀 reviewer，用 tools allowlist：

tools: Read, Grep, Glob, Bash

這樣它不能 Edit、Write，也不能使用沒有列出的 MCP tools。

如果你想繼承大部分能力，只禁檔案寫入，用 disallowedTools：

disallowedTools: Write, Edit

邊界：

tools 是允許列表。
disallowedTools 是拒絕列表。
如果兩者都寫，先應用 disallowedTools，再按 tools 解析。
同時出現在兩邊的工具會被移除。

只讀 subagent 不等於無風險：如果允許 Bash，它仍可能透過命令讀取大量檔案或訪問網路。必要時繼續用 permissions 和 hooks 限制。

12. 限制能 spawn 哪些 Subagents

當某個 agent 作為主執行緒執行時，比如：

claude --agent coordinator

它可能透過 Agent tool 再 spawn subagents。可以用 Agent(agent_type) 限制：

tools: Agent(worker, researcher), Read, Bash

這表示只能 spawn worker 和 researcher。

如果寫：

tools: Agent, Read, Bash

表示可以 spawn 任意 subagent。

官方說明：v2.1.63 起 Task tool 重新命名為 Agent，舊的 Task(...) 引用仍作為 alias 可用。

Subagent 不能再 spawn subagent：這個限制主要用於 claude --agent 讓某個 agent 成為主執行緒時。

13. MCP 限域：只給某個 Subagent

mcpServers 可以讓某個 subagent 擁有專屬 MCP。

例子：

name: browser-tester
description: Tests UI behavior in a real browser.
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github

含義：

playwright 是 inline MCP，只在這個 subagent 啟動時連線，結束時斷開。
github 是引用父會話已有 MCP server。

如果你不想讓主會話載入某個 MCP tool description，就把它定義為 subagent inline MCP，而不是放在 .mcp.json。

高噪音 MCP 適合限域：瀏覽器、資料庫、日誌、監控工具如果只服務某個 worker，就放到 subagent 的 mcpServers。

14. 許可權模式：`permissionMode`

Subagent 可以設定 permissionMode：

default：標準許可權檢查。
acceptEdits：自動接受工作目錄和 additional directories 內的編輯及常見檔案系統命令。
auto：使用 auto mode 分類器。
dontAsk：自動拒絕需要確認的許可權請求。
bypassPermissions：跳過許可權提示。
plan：只讀計劃模式。

重要邊界：

父會話如果是 bypassPermissions 或 acceptEdits，會優先生效，subagent 不能覆蓋。
父會話如果是 auto，subagent 會繼承 auto mode，frontmatter 裡的 permissionMode 會被忽略。
bypassPermissions 風險很高，會跳過大多數許可權提示；根目錄和 home 目錄刪除仍會觸發 circuit breaker。

不要預設給 subagent bypass：worker 越獨立，越需要工具和許可權邊界清晰。

15. 預載入 Skills

Subagent 不會自動繼承主會話呼叫過的 Skills。要在 subagent 啟動時載入某些 Skills，用 skills：

name: api-developer
description: Implements API endpoints following team conventions.
skills:
  - api-conventions
  - error-handling-patterns

注意：

載入的是 Skill 全文，不只是 description。
這些內容在 subagent 啟動時進入它的上下文。
不能預載入 disable-model-invocation: true 的 Skills。
缺失或停用的 Skill 會被跳過並寫入 debug log。

這和 Skill 裡的 context: fork 是反方向：

Subagent 的 skills：以 subagent 為主，Skill 是參考資料。
Skill 的 context: fork：以 Skill 為主，把任務交給 subagent。

不要把所有 Skills 都預載入：只給這個 worker 真正需要的領域知識，否則只是把上下文汙染從主會話搬到 subagent。

16. Persistent memory

Subagent 可以有自己的持久記憶：

memory: project

三種 scope：

user：~/.claude/agent-memory/<agent-name>/，跨專案複用。
project：.claude/agent-memory/<agent-name>/，專案共享，可提交。
local：.claude/agent-memory-local/<agent-name>/，專案本地，不提交。

啟用 memory 後：

Subagent system prompt 會包含讀寫 memory 的說明。
會載入 memory 目錄裡 MEMORY.md 的前 200 行或 25KB，取較小值。
Read、Write、Edit 會自動啟用，讓 subagent 管理 memory 檔案。

官方建議 project 是常用預設，因為專案知識可以團隊共享。user 適合跨專案通用經驗，local 適合個人本機經驗。

memory 會自動啟用寫工具：如果你本來想做嚴格只讀 reviewer，啟用 memory 前要重新檢查工具邊界和儲存庫提交策略。

17. Hooks：給 Subagent 加動態規則

如果 tools 太粗，無法表達“只允許 SELECT，不允許 UPDATE”，就用 hooks。

典型場景：

PreToolUse 校驗 Bash 命令。
PostToolUse 編輯後執行 linter。
Stop 收尾。
主會話裡的 SubagentStart 和 SubagentStop 監聽某類 subagent。

Subagent frontmatter 裡的 hooks 只在該 subagent 生命週期內生效，結束後清理。

Project settings 裡的 SubagentStart / SubagentStop 則在主會話監聽 subagent 生命週期。

條件性安全規則用 Hook：tools: Bash 只能決定能不能用 Bash，不能判斷 Bash 裡是不是危險 SQL。細粒度檢查交給 PreToolUse hook。

18. 顯式呼叫 Subagent

有三種層級。

自然語言：

Use the code-reviewer subagent to review the auth changes.

這種方式通常能觸發，但最終仍由 Claude 判斷。

@ mention：

@agent-code-reviewer look at the auth changes

這會保證指定 subagent 執行。你也可以從 typeahead 裡選擇，plugin subagent 會顯示為 <plugin-name>:<agent-name>。

整場會話使用某個 agent：

claude --agent code-reviewer

也可以在專案設定裡設預設：

{
  "agent": "code-reviewer"
}

此時 subagent 的 system prompt 會替代預設 Claude Code system prompt；CLAUDE.md 和 project memory 仍按正常訊息流載入。

顯式呼叫適合排障：自動委派不穩定時，先用 @agent-name 驗證 subagent 本身是否工作正常。

19. 前臺和後臺執行

Subagent 可以前臺執行，也可以後臺執行。

前臺：

主會話等待 subagent 完成。
許可權提示和澄清問題會傳給你。
適合需要互動、許可權不確定、風險較高的任務。

後臺：

你可以繼續在主會話工作。
啟動前會預先請求該 subagent 需要的工具許可權。
執行後繼承這些許可權。
未預批准的許可權請求會自動拒絕。
澄清問題會失敗，但 subagent 會繼續。

你可以要求後臺：

Run this in the background.

也可以用 Ctrl+B 把正在執行的任務放到後臺。

關閉後臺任務功能：

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude

後臺任務要更保守：它不會在中途等你確認。許可權和任務邊界要在啟動前說清楚。

20. Worktree isolation

如果 subagent 可能改檔案，而你不想它直接寫當前 checkout，可以設定：

isolation: worktree

效果：

Subagent 在臨時 git worktree 裡工作。
檔案修改不會直接落到當前 checkout。
如果 subagent 沒有改動，worktree 會自動清理。
如果有改動，你需要後續檢查和整合。

適合：

並行實現不同方案。
高風險重構。
讓 worker 試驗修復。
不希望汙染主工作區的驗證。

worktree 隔離不是免審查：它保護當前 checkout，但最終合併前仍要 review diff、跑測試、處理衝突。

21. Resume 和 transcript

每次 subagent 呼叫預設是新例項、新上下文。

如果要繼續已有 subagent 的工作，可以讓 Claude resume 它。官方說明 resumed subagent 會保留完整會話歷史，包括工具呼叫、結果和 reasoning。

限制：

Resume 依賴 SendMessage。
SendMessage 目前只在 Agent teams 開啟時可用。
Subagent transcript 存在主專案 session 目錄下的 subagents/。
transcript 會按 cleanupPeriodDays 清理，預設 30 天。

Subagent compaction：

和主會話類似。
預設接近 95% 容量時自動壓縮。
可用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 調整觸發比例。

長任務要主動要摘要：不要等 subagent 巨量上下文後再救。讓它階段性返回 findings、風險和下一步。

22. Forked subagents

Forked subagents 是實驗能力，官方要求 Claude Code v2.1.117 或更高，並透過環境變數開啟：

CLAUDE_CODE_FORK_SUBAGENT=1 claude

Fork 與 named subagent 不同：

Fork 繼承當前主會話完整歷史。
Named subagent 從自己的定義和任務 prompt 開始。
Fork 的工具呼叫仍留在 fork 裡，最終結果回到主會話。
Fork 可以複用主會話 prompt cache。
開啟 fork mode 後，/fork 會建立 fork，而不是作為 /branch alias。

適合：

子任務需要完整上下文，重新解釋成本太高。
想從當前狀態並行嘗試幾個方向。
草擬測試、替代方案、review 觀點。

不適合：

你想保持輸入隔離。
你需要專門工具邊界和 system prompt。
你不想使用實驗功能。

Fork 犧牲輸入隔離：它看到完整主會話。需要嚴格角色、工具和許可權邊界時，用 named subagent。

23. 常見使用模式

隔離高輸出任務：

Use a subagent to run the test suite and report only failing tests with key error messages.

並行研究：

Research the authentication, database, and API modules in parallel using separate subagents.

串聯 worker：

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to propose fixes.

只讀審查：

Use the code-reviewer agent to review recent changes. Do not edit files.

子任務要自包含：給 subagent 明確範圍、輸入、輸出格式和禁止事項。不要只說“看看這個”。

24. 什麼時候留在主會話

留在主會話：

需要頻繁來回確認。
多個階段共享大量上下文。
你正在做小而精確的修改。
延遲很重要。
子任務結果會立即改變下一步。

用 Subagent：

輸出很長，但最後只需要摘要。
需要強工具限制。
子任務自包含。
要並行研究。
主會話上下文已經很重。

用 Skill：

你要複用的是提示詞、流程或參考資料。
任務仍然適合在主會話裡執行。

用 /btw：

只是問一個依賴當前上下文的小問題。
不需要工具。
不想把回答加入歷史。

不是所有 side question 都要 subagent：短問題先用 /btw，流程複用用 Skill，大量工具呼叫才用 Subagent。

25. 一個好 Subagent 的寫法

好的 subagent 檔案應該說明：

何時使用。
何時不要使用。
負責範圍。
禁止事項。
工具邊界。
輸出格式。
是否可以修改檔案。
是否可以呼叫外部系統。
如何處理不確定性。

示例結構：

---
name: security-reviewer
description: Reviews authentication, authorization, token handling, input validation, and secret exposure risks. Use after security-sensitive code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 12
---

You are a security reviewer.

Scope:

- Review only the files relevant to the requested change.
- Prefer evidence from code over speculation.
- Do not edit files.

Output:

- Critical findings
- Warnings
- Evidence with file paths
- Suggested tests
- Residual risk

不要寫萬能 Agent：general-purpose 已經存在。自定義 subagent 應該專門、清晰、可評估。

26. 常見故障：沒被自動使用

排查順序：

執行 /agents 看 subagent 是否存在。
確認直接改檔案後是否重啟了會話。
檢查 description 是否包含自然語言觸發詞。
用 @agent-name 強制呼叫測試。
檢查是否被更高優先順序同名 subagent 覆蓋。
檢查是否被 permissions deny：Agent(name)。
檢查 plugin subagent 是否使用了不支援欄位。

先強制呼叫：如果 @agent-name 能跑，問題通常是 description 太弱或任務不適合自動委派。

27. 常見故障：許可權提示太多

原因：

Subagent 工具範圍太寬。
後臺 subagent 沒有預批准需要的工具。
MCP tool 沒有寫 permissions allow。
Teammate / subagent 在多個檔案上反覆觸發確認。

修法：

用 tools 縮小能力範圍。
給常用只讀工具預批准。
把高風險工具保留 ask。
對後臺任務提前說明需要什麼工具。
對 Agent teams，在 spawn 前先補 permissions。

不要用 bypassPermissions 快速消音：提示太多是邊界設計問題，先收窄工具和任務。

28. 常見故障：結果不可用

常見原因：

任務範圍太大。
輸出格式沒定義。
Subagent 沒拿到必要背景。
工具太少，無法完成任務。
背景任務缺許可權，中途自動拒絕。
並行 subagents 返回了太多細節，反而汙染主會話。

改法：

讓子任務更小。
明確輸出格式。
在 prompt 裡給必要上下文。
只返回 findings，不返回完整過程。
高風險或需要互動的任務改前臺。
必要時用 worktree 隔離實現任務。

Subagent 的輸出應該是可行動結論：不是“讀了很多檔案”，而是“發現什麼、證據在哪、下一步怎麼做”。

29. 自檢清單

學完這一章，你應該能做到：

我能解釋 Subagent 解決的是上下文隔離。
我知道 Explore、Plan、general-purpose 的差別。
我知道什麼時候該寫自定義 subagent。
我知道 subagent 檔案位置和 scope 優先順序。
我能寫出一個最小 .claude/agents/<name>.md。
我知道 tools 和 disallowedTools 的區別。
我知道 mcpServers 可以把 MCP 只給某個 subagent。
我知道 permissionMode 會受到父會話模式影響。
我知道 Subagent 不會自動繼承主會話 Skills。
我知道 memory 會自動啟用讀寫工具。
我知道後臺 subagent 會預批准許可權並自動拒絕未批准請求。
我知道 isolation: worktree 的用途和邊界。
我知道 forked subagent 與 named subagent 的差別。
我知道 Subagent 和 Agent team 的邊界。

30. 術語速查

Subagent：在隔離上下文裡執行子任務的專門 assistant。
Explore：內建只讀探索 subagent。
Plan：plan mode 中用於上下文研究的只讀 subagent。
general-purpose：內建通用複雜任務 subagent。
/agents：建立、編輯、檢視 subagents 的互動入口。
tools：subagent 可使用工具 allowlist。
disallowedTools：從可用工具中移除的 denylist。
permissionMode：subagent 的許可權模式。
mcpServers：只給該 subagent 的 MCP server 配置。
skills：啟動時預載入進 subagent 上下文的 Skills。
memory：subagent 的持久記憶目錄。
background：讓 subagent 預設後臺執行。
isolation: worktree：讓 subagent 在臨時 git worktree 中工作。
Agent(agent_type)：限制主執行緒 agent 可 spawn 哪些 subagents 的工具語法。
@agent-name：顯式呼叫某個 subagent。
forked subagent：繼承完整主會話歷史的實驗性 subagent。
Agent team：多個獨立 Claude Code sessions 組成的協作團隊。