---
title: "配置 Subagents"
description: "Claude Code Subagents 用隔離上下文處理專門任務。學會內建 agents、自定義 frontmatter、工具邊界、MCP 限域、skills 預載入、memory、background 和 worktree。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-05"
---

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

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

## 1. Subagent 解決什麼問題

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

適合用 Subagent：

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

不適合用 Subagent：

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

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

```mermaid
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 功能問題時使用。

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

## 3. Subagent 和 Skill 怎麼區分

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

Skill：

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

Subagent：

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

組合方式：

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

> [!IMPORTANT]
> **判斷句**：你要複用一套流程，用 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、協調和衝突成本更高。

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

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

官方推薦入口：

```text
/agents
```

這個介面可以：

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

命令列只列出配置：

```bash
claude agents
```

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

> [!TIP]
> **先用 `/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`，外掛啟用時可用。

優先順序從高到低：

1. Managed settings
2. `--agents` CLI flag
3. Project `.claude/agents/`
4. User `~/.claude/agents/`
5. Plugin agents

注意：

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

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

## 7. 最小檔案格式

一個基本 subagent：

```markdown
---
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 會按正常訊息流載入。

> [!WARNING]
> **正文要寫成角色說明，不是使用者請求**：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 執行時自動提交的第一條使用者訊息。

> [!TIP]
> **新手先用五個欄位**：`name`、`description`、`tools`、`model`、`maxTurns`。其他欄位等需求明確再加。

## 9. description 決定自動委派

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

弱描述：

```yaml
description: Helps with code.
```

強描述：

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

寫法原則：

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

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

## 10. 模型選擇和優先順序

`model` 欄位可以設定：

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

官方模型解析優先順序：

1. `CLAUDE_CODE_SUBAGENT_MODEL` 環境變數。
2. 某次 invocation 傳入的 model。
3. subagent 檔案裡的 `model`。
4. 主會話模型。

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

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

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

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

```yaml
tools: Read, Grep, Glob, Bash
```

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

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

```yaml
disallowedTools: Write, Edit
```

邊界：

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

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

## 12. 限制能 spawn 哪些 Subagents

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

```bash
claude --agent coordinator
```

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

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

這表示只能 spawn `worker` 和 `researcher`。

如果寫：

```yaml
tools: Agent, Read, Bash
```

表示可以 spawn 任意 subagent。

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

> [!IMPORTANT]
> **Subagent 不能再 spawn subagent**：這個限制主要用於 `claude --agent` 讓某個 agent 成為主執行緒時。

## 13. MCP 限域：只給某個 Subagent

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

例子：

```yaml
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`。

> [!TIP]
> **高噪音 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。

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

## 15. 預載入 Skills

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

```yaml
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。

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

## 16. Persistent memory

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

```yaml
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` 適合個人本機經驗。

> [!CAUTION]
> **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 生命週期。

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

## 18. 顯式呼叫 Subagent

有三種層級。

自然語言：

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

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

`@` mention：

```text
@agent-code-reviewer look at the auth changes
```

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

整場會話使用某個 agent：

```bash
claude --agent code-reviewer
```

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

```json
{
  "agent": "code-reviewer"
}
```

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

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

## 19. 前臺和後臺執行

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

前臺：

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

後臺：

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

你可以要求後臺：

```text
Run this in the background.
```

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

關閉後臺任務功能：

```bash
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude
```

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

## 20. Worktree isolation

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

```yaml
isolation: worktree
```

效果：

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

適合：

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

> [!CAUTION]
> **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` 調整觸發比例。

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

## 22. Forked subagents

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

```bash
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。
- 你不想使用實驗功能。

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

## 23. 常見使用模式

隔離高輸出任務：

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

並行研究：

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

串聯 worker：

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

只讀審查：

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

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

## 24. 什麼時候留在主會話

留在主會話：

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

用 Subagent：

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

用 Skill：

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

用 `/btw`：

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

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

## 25. 一個好 Subagent 的寫法

好的 subagent 檔案應該說明：

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

示例結構：

```markdown
---
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
```

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

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

排查順序：

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

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

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

原因：

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

修法：

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

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

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

常見原因：

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

改法：

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

> [!IMPORTANT]
> **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 組成的協作團隊。

## 31. 官方資料

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams)
- [Extend Claude Code](https://code.claude.com/docs/en/features-overview)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Configure permissions](https://code.claude.com/docs/en/permissions)
- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide)

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/02-extensions-automation/hooks" title="Hooks" description="Subagent 的工具邊界只能粗分；要做確定性阻斷、校驗和事件自動化，下一章進入 Hooks。" />
  <Card href="/zh-Hant/docs/claude-code/official/02-extensions-automation/skills" title="Skills（上一篇）" description="Skill 負責可複用知識和流程；Subagent 負責隔離執行。兩者可以透過 skills 欄位或 context: fork 組合。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/08-multi-agent" title="深度理解：多 Agent 協作" description="想繼續理解為什麼要拆 worker、什麼時候並行、怎麼避免主上下文汙染，讀理解篇多 Agent。" />
</Cards>
