什麼是 Subagents

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

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

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

內建的 Subagent 類型

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

其中 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，存放在以下位置：

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 設定欄位完整參考

工具權限控制

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 可以設定不同的權限模式，決定它在執行工具時如何處理權限請求：

權限模式有繼承規則：如果主 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 能夠累積專案相關的經驗，隨著時間變得越來越「了解」你的專案。

記憶範圍

啟用持久記憶後，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 比較

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。

相關環境變數

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 工作流程。

延伸閱讀

• Claude Code 是什麼？完整介紹與安裝教學
• Claude Code 新手上路：第一次使用就上手
• CLAUDE.md 專案記憶：讓 Claude 記住你的專案規範
• Custom Skills：打造你的專屬自訂技能
• Hooks 事件掛鉤：自動化你的 Claude Code 工作流程
• Claude Code Sub-agents 官方文件

ㄚ槌

blog.che-ya.com