Multi-agent 架構：Subagents 與任務分派完整教學

當你的專案規模越來越大，一個 Claude Code 對話要同時處理搜尋程式碼、撰寫測試、執行部署等多項任務時，Context Window 很快就會被塞滿，效率也會大幅下降。Claude Code 的 Multi-agent 架構透過 Subagents（子代理）機制，讓你可以將複雜任務拆分給多個獨立的 Agent 分別執行，每個 Subagent 擁有自己的 Context Window、工具權限和專屬系統提示。主 Agent 只需接收精簡的執行結果，大幅節省 Token 用量，同時提升任務品質與執行效率。

什麼是 Subagents

Subagents 是在 Claude Code 主對話中產生的子代理程序，每個 Subagent 擁有獨立的 Context Window，在自己的環境中完成指定任務後，將精簡的結果回傳給主 Agent。你可以把它想像成一個團隊主管（主 Agent）將不同工作分配給專業成員（Subagents），每位成員各自完成工作後回報結果，主管不需要了解每個人的所有工作細節。

這個機制帶來三大核心優勢：

Context 隔離：Subagent 的詳細執行過程（如搜尋了哪些檔案、讀取了哪些內容）留在自己的 Context 中，只有最終結果回傳主 Agent，大幅減少主對話的 Token 消耗
專業分工：每個 Subagent 可以擁有不同的工具權限、系統提示和模型設定，針對特定任務進行最佳化
並行執行：多個 Subagent 可以同時執行不同任務，縮短整體工作時間

內建的 Subagent 類型

Claude Code 預設提供四種內建的 Subagent 類型，各自適合不同的使用場景：

Subagent 類型	預設模型	可用工具	適用場景
Explore	Haiku	唯讀（Glob、Grep、Read、Bash）	快速搜尋程式碼、探索專案結構
Plan	繼承主 Agent	唯讀	研究階段、規劃實作方案
general-purpose	繼承主 Agent	所有工具	複雜的多步驟任務
Claude Code Guide	Haiku	知識查詢	回答 Claude Code 功能相關問題

其中 Explore 是最常被自動使用的類型。當 Claude Code 需要在大型程式庫中搜尋特定程式碼時，它會自動產生一個 Explore Subagent 來執行搜尋，避免將大量搜尋結果塞入主 Agent 的 Context Window。

如何觸發 Subagent

觸發 Subagent 有幾種方式：

自然語言指派

最簡單的方式是在對話中用自然語言描述你想要的分工：

# 讓 Claude 自動選擇適合的 Subagent 類型
用 subagent 分別搜尋 authentication、database 和 API 模組的程式碼結構

# 明確指定使用特定類型
使用 Explore subagent 搜尋所有包含 TODO 的檔案

@ 提及方式

如果你有自訂的 Subagent，可以使用 @ 符號直接指定：

@code-reviewer 請檢查 src/auth/ 目錄下的所有檔案

CLI 啟動整個 Session

使用 --agent 參數可以讓整個 Claude Code Session 以特定 Agent 身份運行：

claude --agent code-reviewer

自訂 Subagent

除了內建類型，你可以建立完全客製化的 Subagent 來滿足團隊的特定需求。自訂 Subagent 定義檔使用 Markdown 格式搭配 YAML frontmatter，存放在以下位置：

存放位置	適用範圍	說明
`.claude/agents/`	當前專案	可加入版本控制與團隊共享
`~/.claude/agents/`	所有專案	個人全域使用
Plugin 的 `agents/` 目錄	啟用該 Plugin 的專案	隨 Plugin 安裝

Subagent 定義檔範例

以下是一個 Code Reviewer Subagent 的完整定義範例：

# 檔案路徑：.claude/agents/code-reviewer.md
---
name: code-reviewer
description: 專業程式碼審查員。主動檢查程式碼品質、安全性和可維護性。
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: dontAsk
maxTurns: 50
memory: project
---

你是一位資深程式碼審查員，專注於以下面向：
1. 程式碼品質：命名規範、函式長度、重複程式碼
2. 安全性：SQL Injection、XSS、敏感資料外洩
3. 效能：不必要的迴圈、N+1 查詢、記憶體洩漏
4. 可維護性：註解品質、模組化程度、測試覆蓋率

請用繁體中文回報審查結果，並以嚴重程度排序。

Frontmatter 設定欄位完整參考

欄位	類型	預設值	說明
`name`	string	必填	唯一識別名稱（小寫）
`description`	string	必填	描述何時應該委派給此 Agent
`tools`	array	繼承全部	允許使用的工具白名單
`disallowedTools`	array	無	禁止使用的工具黑名單
`model`	string	繼承	使用的模型（sonnet、opus、haiku）
`permissionMode`	string	繼承	權限模式（default、auto、dontAsk 等）
`maxTurns`	integer	無限制	最大執行回合數
`memory`	string	無	持久記憶範圍（user、project、local）
`isolation`	string	無	設為 worktree 啟用 Git Worktree 隔離
`background`	boolean	false	是否在背景執行
`effort`	string	繼承	推理深度（low、medium、high、max）
`skills`	array	無	啟動時注入的 Skill 內容
`mcpServers`	array	無	可使用的 MCP Server
`hooks`	object	無	生命週期事件掛鉤

工具權限控制

Subagent 的工具權限控制是安全性的關鍵。你可以使用白名單或黑名單模式來精確控制每個 Subagent 能使用哪些工具。

白名單模式

明確指定 Subagent 可以使用的工具：

---
tools: Read, Grep, Glob, Bash
---

這種模式適合需要嚴格限制的場景，例如只讀的程式碼審查 Subagent。

黑名單模式

繼承主 Agent 的所有工具，但排除特定工具：

---
disallowedTools: Write, Edit
---

這種模式適合大部分工具都需要使用，只需排除少數高風險工具的情況。

限制可產生的 Subagent

你甚至可以控制一個 Subagent 能夠產生哪些其他 Subagent：

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

上面的設定只允許該 Subagent 產生名為 worker 和 researcher 的子代理。

權限模式詳解

每個 Subagent 可以設定不同的權限模式，決定它在執行工具時如何處理權限請求：

模式	行為	適用場景
`default`	標準權限檢查，需要使用者確認	需要互動確認的工作
`acceptEdits`	自動接受檔案編輯（受保護目錄除外）	受信任的自動化修改
`auto`	背景分類器自動審核並批准	高量操作
`dontAsk`	自動拒絕所有權限請求	純唯讀操作
`bypassPermissions`	跳過所有權限檢查	完全受信任的操作（謹慎使用）
`plan`	唯讀探索模式	僅限研究的 Agent

權限模式有繼承規則：如果主 Agent 使用 bypassPermissions，則該設定具有最高優先權，Subagent 無法覆寫；如果主 Agent 使用 auto 模式，Subagent 也會繼承 auto 模式。

Worktree 隔離

當多個 Subagent 同時對程式碼進行修改時，可能會產生檔案衝突。Worktree 隔離機制透過 Git Worktree 為每個 Subagent 提供獨立的工作目錄副本，避免互相干擾。

啟用方式

在 Subagent 定義的 frontmatter 中加入 isolation: worktree：

---
name: parallel-worker
description: 可並行執行的工作者
isolation: worktree
---

Worktree 運作機制

Subagent 啟動時會自動建立一個新的 Git Worktree checkout
所有檔案修改都在這個獨立的 Worktree 中進行，不會影響主 Session 或其他 Subagent
如果 Subagent 沒有做任何變更，Worktree 會自動清除
如果 Subagent 提交了變更，Worktree 會保留，讓你可以檢視或合併這些變更

Worktree 隔離特別適合需要多個 Subagent 同時修改不同模組的場景，例如一個 Subagent 負責重構 API 層，另一個 Subagent 同時處理資料庫遷移。

持久記憶機制

Subagent 可以透過持久記憶（Persistent Memory）在不同 Session 之間保留知識。這讓 Subagent 能夠累積專案相關的經驗，隨著時間變得越來越「了解」你的專案。

記憶範圍

範圍	存放位置	用途
`user`	`~/.claude/agent-memory/<agent-name>/`	跨所有專案的通用知識
`project`	`.claude/agent-memory/<agent-name>/`	專案特定知識，可透過版本控制共享
`local`	`.claude/agent-memory-local/<agent-name>/`	專案特定知識，不加入版本控制

啟用持久記憶後，Subagent 的 MEMORY.md 檔案前 200 行（或 25KB）會在啟動時自動注入到 Context 中。Subagent 會自動管理記憶內容的大小，確保最重要的資訊被保留。

---
name: code-reviewer
memory: project
---

前景與背景執行

Subagent 支援兩種執行模式：

前景執行（預設）

主對話會等待 Subagent 完成才繼續
權限請求會傳遞給使用者確認
適合需要互動回饋的場景

背景執行

在 Subagent 定義中加入 background: true 可啟用背景執行：

---
name: test-runner
description: 在背景執行測試套件
background: true
---

Subagent 與主對話並行執行
只能使用預先核准的權限（啟動後不再提示）
未預先核准的工具呼叫會自動失敗（但 Subagent 會繼續執行）
適合高量並行操作，如執行測試、批次搜尋

你也可以在 Subagent 執行中按下 Ctrl+B 將前景 Subagent 切換到背景執行，或者在對話中說「在背景執行」來觸發背景模式。

並行任務執行模式

Multi-agent 架構最強大的應用之一就是並行任務執行。以下是幾種常見的並行模式：

模式一：多個研究 Subagent

同時派出多個 Subagent 探索不同模組：

# 在 Claude Code 對話中輸入：
請分別用 subagent 搜尋以下三個模組的程式碼結構：
1. authentication 模組
2. database 模組
3. API 模組
每個用獨立的 subagent 並行處理

每個 Subagent 獨立探索，最後由主 Agent 整合所有結果。

模式二：鏈式 Subagent

一個 Subagent 的輸出作為下一個的輸入：

# 先用 code-reviewer 找出問題，再用 optimizer 修復
先用 code-reviewer subagent 找出效能問題，
然後用 optimizer subagent 修復這些問題

模式三：高量隔離操作

將產生大量輸出的操作隔離在 Subagent 中：

# 測試套件的輸出留在 Subagent 中，只回傳摘要
用 subagent 執行測試套件，只回報失敗的測試和錯誤訊息

這種模式能有效避免冗長的測試輸出塞滿主 Agent 的 Context Window。

Subagent 生命週期 Hooks

你可以透過 Hooks 在 Subagent 的生命週期中插入自訂邏輯，分為兩個層級：

Subagent 層級 Hooks（在 frontmatter 中定義）

---
name: db-migrator
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-sql.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
  Stop:
    - matcher: ""
      hooks:
        - type: command
          command: "./scripts/cleanup.sh"
---

專案層級 Hooks（在 settings.json 中定義）

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          {"type": "command", "command": "./scripts/setup-db.sh"}
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {"type": "command", "command": "./scripts/log-completion.sh"}
        ]
      }
    ]
  }
}

專案層級的 SubagentStart 和 SubagentStop 事件可以用 matcher 過濾特定的 Subagent 名稱，讓你針對不同 Subagent 執行不同的初始化或清理邏輯。

Agent Teams：多 Session 協作（實驗性功能）

除了單一 Session 內的 Subagent，Claude Code 還提供了實驗性的 Agent Teams 功能，允許多個獨立的 Claude Code Session 協同工作。

啟用方式

# 設定環境變數啟用 Agent Teams
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Subagent vs Agent Teams 比較

特性	Subagent	Agent Teams
架構	單一 Session 內的子代理	多個獨立 Session 協作
溝通方式	只回報結果給主 Agent	成員之間可直接訊息溝通
共享資源	無	共享任務清單和訊息系統
Token 成本	較低（結果摘要回傳）	較高（每個成員獨立 Context）
適用場景	獨立、專注的子任務	需要跨成員討論的複雜協作
穩定性	正式功能	實驗性功能

Agent Teams 適合需要多個 Agent 互相討論和協作的大型任務，例如讓一個 Agent 專注 UX 設計、一個負責技術架構、一個扮演魔鬼代言人來挑戰方案。但由於 Token 成本較高且功能仍在實驗階段，建議大多數場景優先使用 Subagent 模式。

實戰範例：建立完整的 Code Review 工作流

以下是一個使用多個 Subagent 組成完整 Code Review 工作流的實際範例：

步驟一：建立安全檢查 Subagent

# .claude/agents/security-checker.md
---
name: security-checker
description: 安全性漏洞掃描專家。檢查常見安全漏洞如 SQL Injection、XSS、CSRF。
tools: Read, Grep, Glob
model: sonnet
permissionMode: dontAsk
memory: project
---

你是一位資安專家，專注於檢查以下安全漏洞：
- SQL Injection
- Cross-Site Scripting (XSS)
- Cross-Site Request Forgery (CSRF)
- 敏感資料硬編碼（API Key、密碼等）
- 不安全的依賴套件

回報格式：
1. 嚴重程度（Critical/High/Medium/Low）
2. 檔案路徑和行號
3. 問題描述
4. 建議修復方式

步驟二：建立效能分析 Subagent

# .claude/agents/performance-analyzer.md
---
name: performance-analyzer
description: 效能分析專家。找出潛在的效能瓶頸和最佳化機會。
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: dontAsk
---

你是一位效能最佳化專家，專注於：
- N+1 查詢問題
- 不必要的迴圈和重複計算
- 記憶體洩漏風險
- 未最佳化的資料庫查詢
- 可快取但未快取的操作

步驟三：在對話中組合使用

# 在 Claude Code 對話中這樣指示：
請幫我做完整的 Code Review，使用以下流程：
1. 先用 security-checker 檢查安全漏洞
2. 同時用 performance-analyzer 分析效能問題
3. 最後幫我彙整兩份報告，按嚴重程度排序產出一份完整的 Review 報告

Claude Code 會自動並行執行兩個 Subagent，然後整合它們的結果。由於每個 Subagent 的詳細搜尋過程都留在各自的 Context 中，主 Agent 只需要處理精簡的結果報告，整個過程既高效又節省 Token。

環境變數	說明
`CLAUDE_CODE_SUBAGENT_MODEL`	覆寫所有 Subagent 的預設模型
`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`	設為 1 啟用 Agent Teams 功能
`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`	設為 1 禁用背景執行

Subagent 最佳實踐

每個 Subagent 專注一項任務：將 Subagent 設計為專注於單一職責（如 code-reviewer、debugger、researcher），而非萬用型 Agent。專注的 Subagent 效果更好，也更容易維護
撰寫詳細的 description：Claude Code 會根據 description 決定何時自動委派任務給 Subagent，描述越精確，自動分派就越準確
最小化工具權限：只授予 Subagent 實際需要的工具。唯讀的 Subagent 就不要給 Write 權限，這既提升安全性也讓 Subagent 更專注
善用持久記憶：對於經常使用的 Subagent（如 code-reviewer），啟用 project 層級的持久記憶，讓它累積對專案的了解
將高量輸出隔離：任何會產生大量輸出的操作（如執行測試、搜尋日誌）都應該放在 Subagent 中執行，只回傳摘要結果
加入版本控制：將專案層級的 Subagent 定義（.claude/agents/）加入 Git，讓團隊成員都能使用同一套 Subagent 設定
需要並行修改時使用 Worktree：當多個 Subagent 可能修改同一個專案的不同檔案時，啟用 isolation: worktree 避免衝突
從簡單開始：先用內建的 Explore Subagent 體驗 Multi-agent 的效果，確認理解運作方式後再建立自訂 Subagent

常見問題

Subagent 可以再產生 Subagent 嗎？

預設情況下 Subagent 不能巢狀產生其他 Subagent。如果需要，你可以在工具白名單中明確允許 Agent 工具，並指定可產生的 Subagent 名稱。

Subagent 的結果如何回傳？

Subagent 完成後，它的最後一則回應會作為結果回傳給主 Agent。Subagent 執行過程中的所有中間步驟（搜尋、讀檔等）都留在 Subagent 自己的 Context 中，不會佔用主 Agent 的 Token。

可以恢復已完成的 Subagent 嗎？

可以。你可以透過 SendMessage 工具指定 Subagent 的 ID 來恢復已完成的 Subagent，它會保留完整的對話歷史和狀態。

如何控制 Subagent 使用的模型？

模型選擇的優先順序為：環境變數 CLAUDE_CODE_SUBAGENT_MODEL > 呼叫時的 model 參數 > Subagent frontmatter 的 model 欄位 > 繼承主 Agent 的模型。

總結

Claude Code 的 Multi-agent 架構是處理大型專案和複雜任務的利器。透過 Subagent 機制，你可以將工作拆分給多個專業的子代理分別執行，每個 Subagent 在自己的 Context Window 中獨立運作，只將精簡結果回傳主 Agent。結合 Worktree 隔離、持久記憶和生命週期 Hooks，你可以打造出高效且安全的自動化工作流程。

建議從使用內建的 Explore Subagent 開始，體會 Context 隔離帶來的效率提升。接著根據團隊需求建立自訂的 Code Review、安全檢查等專業 Subagent，逐步建立完整的 Multi-agent 工作流程。

延伸閱讀

ㄚ槌

什麼是 Subagents

內建的 Subagent 類型

如何觸發 Subagent

自然語言指派

@ 提及方式

CLI 啟動整個 Session

自訂 Subagent

Subagent 定義檔範例

Frontmatter 設定欄位完整參考

工具權限控制

白名單模式

黑名單模式

限制可產生的 Subagent

權限模式詳解

Worktree 隔離

啟用方式

Worktree 運作機制

持久記憶機制

記憶範圍

前景與背景執行

前景執行（預設）

背景執行

並行任務執行模式

模式一：多個研究 Subagent

模式二：鏈式 Subagent

模式三：高量隔離操作

Subagent 生命週期 Hooks

Subagent 層級 Hooks（在 frontmatter 中定義）

專案層級 Hooks（在 settings.json 中定義）

Agent Teams：多 Session 協作（實驗性功能）

啟用方式

Subagent vs Agent Teams 比較

實戰範例：建立完整的 Code Review 工作流

步驟一：建立安全檢查 Subagent

步驟二：建立效能分析 Subagent

步驟三：在對話中組合使用

相關環境變數

Subagent 最佳實踐

常見問題

Subagent 可以再產生 Subagent 嗎？

Subagent 的結果如何回傳？

可以恢復已完成的 Subagent 嗎？

如何控制 Subagent 使用的模型？

總結

延伸閱讀