Sub-agents：自動委派與平行執行

Sub-agents 是 Claude Code 的核心功能之一。Claude 會自己決定何時呼叫 sub-agents，不需要你手動觸發。

運作機制

Claude 自動決定

當你給 Claude 一個任務，它會：

1. 分析任務需求
2. 判斷是否適合委派給 sub-agent
3. 如果適合，自動呼叫對應的 sub-agent
4. Sub-agent 在獨立 context 中工作
5. 只把結果摘要回傳給主對話

你：幫我了解這個專案的架構

Claude（內部決策）：
  → 這是探索任務
  → 需要讀取很多檔案
  → 委派給 Explore agent 比較好
  → 這樣主對話不會被檔案內容淹沒

Claude：我來探索一下這個專案結構...
[Explore agent 在背景工作]
[只回傳精煉的摘要]

為什麼要自動委派？

Context 污染問題：

❌ 沒有 sub-agents：
你：分析這個專案
Claude：[讀了 50 個檔案，context 爆滿]
Claude：[開始忘記早期的重要資訊]

✅ 有 sub-agents：
你：分析這個專案
Claude：委派給 Explore agent...
Explore agent：[在獨立 context 中讀 50 個檔案]
Claude：[只收到精煉的摘要，context 保持乾淨]

Claude Code 內建 Sub-agents

Claude Code 自帶幾個內建的 sub-agents：

Explore Agent

用途：快速探索和分析代碼庫

Claude 會在這些情況自動使用：

• 「這個專案的結構是什麼？」
• 「找出所有處理認證的檔案」
• 「這個函數在哪裡被使用？」

特點：

• 只讀（不會修改檔案）
• 快速（優化過的搜尋）
• 有三種深度：quick、medium、very thorough

Plan Agent

用途：設計實作方案

Claude 會在這些情況自動使用：

• 進入 Plan Mode 時
• 需要規劃複雜功能的實作步驟

特點：

• 支援平行探索多種策略
• 產出結構化的實作計畫

General-Purpose Agent

用途：處理複雜、多步驟的任務

Claude 會在這些情況自動使用：

• 任務需要探索 + 修改
• 需要複雜推理
• 多個相依步驟

自訂 Agents

除了內建的，你可以定義自己的 agents。放在 ~/.claude/agents/ 目錄後，Claude 會根據任務描述自動決定是否使用它們。

運作原理

你在 ~/.claude/agents/senior-code-reviewer.md 定義了一個 agent
↓
description: "Use this agent when you need an experienced
senior engineer to review and directly improve recently
written code..."
↓
當你說「幫我審查剛寫的程式碼」
↓
Claude 比對任務和 agent descriptions
↓
自動決定使用 senior-code-reviewer agent

Agent 定義格式

---
name: agent-name
description: Claude 用這段描述來決定何時使用這個 agent。
  描述越清楚，Claude 的判斷越準確。
model: inherit  # 或 haiku/sonnet/opus
---

[Agent 的 system prompt - 定義它的行為和專業]

重點：description 欄位是給 Claude 看的，它會根據這個描述來判斷什麼情況該使用這個 agent。

範例：讓 Claude 自動使用審查 Agent

---
name: senior-code-reviewer
description: Use this agent when you need an experienced senior engineer
to review and directly improve recently written code. This agent should
be invoked after completing a logical chunk of code, a feature implementation,
or when you want a thorough code quality assessment.
model: inherit
---

You are an experienced senior software engineer...

有了這個定義後：

你：我剛寫完登入功能，幫我看看有沒有問題

Claude（內部決策）：
  → 用戶完成了一個功能
  → 想要程式碼審查
  → 這符合 senior-code-reviewer 的描述
  → 委派給它

Claude：我會請資深工程師 agent 來審查你的程式碼...

Commands 的角色

Commands（/review、/debug 等）不是呼叫 sub-agents 的唯一方式。它們只是：

1. 明確提示：告訴 Claude「我現在就要用這個 agent」
2. 帶入 context：可以執行 shell 指令獲取額外資訊

Command 範例

---
description: Review and fix code
---

## Context
Recent changes: !`git diff --stat HEAD~1`

## Task
Use the senior-code-reviewer agent to review: $ARGUMENTS

這個 command 做的事：

1. 執行 git diff 獲取最近改動
2. 告訴 Claude 使用 senior-code-reviewer agent
3. 傳遞參數

但即使沒有這個 command，如果你說「幫我審查程式碼」，Claude 也可能自己決定使用 senior-code-reviewer agent（如果你有定義它）。

平行執行

Claude Code 可以同時呼叫多個 sub-agents（最多約 10 個）：

你：幫我全面檢查這個專案

Claude（可能會）：
├── 同時啟動 Explore agent 了解結構
├── 同時啟動 senior-code-reviewer 審查程式碼
├── 同時啟動 performance-hunter 找效能問題
└── 平行執行，大幅節省時間

如何觸發平行執行

你可以明確要求：

請同時（平行）幫我做：
1. 審查 UserService 的程式碼品質
2. 檢查效能問題
3. 掃描技術債

或者 Claude 自己判斷任務可以平行化時也會這樣做。

Sub-agents 的兩大好處

1. Context 隔離

主對話（你和 Claude）
├── 保持乾淨、專注
├── 只接收摘要結果
└── Context 不會被工作細節污染

Sub-agent（獨立工作）
├── 有自己的 context window
├── 可以讀大量檔案、做複雜分析
└── 只回傳精煉結果

2. 專業分工

每個 agent 可以有：

• 專屬的 system prompt（專業知識）
• 限定的工具權限（安全性）
• 特定的行為模式（一致性）

設置自訂 Agents

步驟

# 1. 建立目錄
mkdir -p ~/.claude/agents

# 2. 建立 agent 檔案
# 例如：~/.claude/agents/my-reviewer.md

# 3. 重啟 Claude Code 讓它讀取新 agents

Agent 放置位置

位置	適用範圍
~/.claude/agents/	所有專案（個人設定）
專案/.claude/agents/	特定專案（團隊共享）

最佳實踐

1. 寫好 description

Claude 靠 description 來判斷何時使用你的 agent：

# ❌ 不好 - 太模糊
description: Reviews code

# ✅ 好 - 清楚說明使用時機
description: Use this agent when you need an experienced senior
engineer to review recently written code. Ideal after completing
a feature, before PR, or when you want quality assessment.

2. 讓 Claude 自己決定

不需要每次都用 /review，你可以直接說：

「我剛寫完這個功能，幫我看看」
「這段程式碼好像有 bug」
「效能變很差，幫我找原因」

Claude 會自動選擇合適的 agent（如果有定義的話）。

3. 善用內建 agents

即使不定義自訂 agents，Claude 也會使用內建的：

• 探索專案時用 Explore
• 規劃功能時用 Plan
• 複雜任務時用 General-Purpose

完整流程圖

你提出任務
    ↓
Claude 分析任務需求
    ↓
┌─────────────────────────────────┐
│ 比對可用的 agents：              │
│ • 內建：Explore, Plan, General  │
│ • 自訂：你定義的 agents         │
└─────────────────────────────────┘
    ↓
符合某個 agent 的 description？
    ↓
┌─────┴─────┐
│ Yes      │ No
↓          ↓
委派給      Claude 自己
sub-agent   處理
↓
獨立 context
中執行
↓
回傳摘要
給主對話

延伸閱讀

• Claude Code 官方 Sub-agents 文件
• Claude Code System Prompts - 內建 agent 的 system prompts
• Sub-agents 平行化開發
• Agent 資料庫 - 可複製使用的 agents 和 commands

下一步

• Agent 資料庫 - 複製現成的 agents 和 commands
• Commands 詳解 - 了解如何用 commands 提示 Claude
• Debug 技巧 - 詳細的除錯方法