Claude Code 子代理：結構、五種角色與協調

Claude Code 的子代理是什麼？為什麼它「不只是另一種 Skill」？#

Claude Code 文件的定義如下：

用企業家聽得懂的方式來說，可以想像一家房仲公司。裡面有主管、行銷人員、律師和業務經理。同一位員工輪流扮演所有角色，並不算一個團隊，而是一個過度負荷的人。當每個人都有自己的脈絡和職責範圍，而主管只負責分派工作、整合成果時，團隊才真正成形。

Claude Code 的子代理也是同樣的運作方式。主聊天是主管，子代理則是負責明確工作、擁有自身脈絡和工具組合的專家。當工作符合某位專家的說明時，主管就會把工作委派出去，不會陷入細節之中。

Anthropic 設計子代理的 5 個目的

Anthropic 的文件明確列出建立自訂子代理的五個理由：

對非程式設計師來說，這份清單中最實用的一項是成本控管。你可以把耗費大量資源的研究工作交給價格較低的 Haiku 模型，同時在主對話中繼續使用 Sonnet 或 Opus。節省的 Token 會與此成正比。

檢查已安裝版本的巢狀支援

本文範本由一個主工作階段直接委派工作者。不要把舊文件「子代理不能再啟動其他子代理」當作永久規則；巢狀行為取決於安裝版本與允許工具。巢狀子代理指南 討論特定版本做法，規劃深層委派前先驗證自己的安裝。

子代理與 Skill、斜線指令和 Hook 有什麼不同？#

先前介紹 Skills 的指南說明，Claude Code 的 Skills 和斜線指令實際上已整合為同一種格式。但子代理是不同的東西，不只是「更大型的 Skill」。

四種機制的摘要表：

用英文指南中常見的說法來比喻：Skills 是食譜，子代理是專門領域的同事。

Skills 就像食譜；子代理就像專門領域的同事。

實際運作方式如下：當 Skill 的說明符合工作內容時，它會自動啟用；子代理則需要明確呼叫——由主聊天決定是否委派，或由你指定名稱呼叫。

決策樹：「我該選哪一種？」

當你想著「我需要 Claude 做 X」時，先用以下四個問題判斷：

1. 這是應該隨時可用的知識嗎？ 例如「依照使用者偏好的語言進行在地化」或「不使用 em dash」。把它放進 CLAUDE.md。
2. 這是目前需要手動執行、由特定條件觸發的方法嗎？ 例如「我每週一都會寫銷售報告」。建立一個 skill。
3. 這項工作會耗用主聊天的脈絡，或可以平行執行嗎？ 例如「深入研究 30 個來源」或「我撰寫新功能時，同時進行安全稽核」。建立一個 子代理。
4. 你需要 Claude Code 對事件自動回應嗎？ 例如「每次 Edit 後執行 linter」。撰寫一個 hook。

企業家的工作有 90% 屬於前兩類。子代理是進階工具，適用於從「一次做一項工作」邁向協調工作的階段。

子代理放在哪裡？哪個設定優先？#

子代理階層共有五層，依優先順序由高至低排列如下：

優先順序的邏輯與 Skills 和 CLAUDE.md 相同：組織設定覆寫 CLI，CLI 覆寫專案，專案覆寫個人設定，個人設定覆寫外掛程式。

載入時需要注意的事項

Claude Code 工作階段啟動時會載入子代理。如果你手動編輯磁碟上的代理檔案，必須重新啟動工作階段才會套用變更。透過互動式 /agents UI 編輯則會立即生效。

每個範圍只會有一個子代理，也就是一個檔案。如果 .claude/agents/ 有 code-reviewer.md，旁邊又有另一個同名檔案（例如舊備份），Claude Code 會靜默忽略其中一個，不會顯示通知。

外掛程式的子代理另有安全限制：不支援 hooks、mcpServers 和 permissionMode 欄位。這可以避免安裝第三方外掛程式時，讓它取得在你的電腦上執行任意程式碼的權限。

子代理檔案的結構：Frontmatter 和本文#

官方文件中的最精簡範例，只有 9 行：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

這樣就足夠了。如果使用者在主聊天中說「review my PR」，Claude 會將「reviewer / code / quality」與 description 比對，然後委派給子代理。子代理讀取差異、撰寫評論，再將摘要回傳給主聊天。主聊天不會被記錄和中間分析塞滿。

完整 Frontmatter Schema

model: haiku 欄位正是上述五個目的中的「成本控管」。如果研究代理要閱讀 50 頁文件，使用 Haiku 執行，相較 Opus 可節省 5–7 倍成本。

isolation: worktree 欄位可解決一項重要問題：子代理要進行可能有風險的變更（重構、遷移），但你不希望它碰到工作副本。設定 isolation: worktree 後，Claude Code 會建立專案的暫存 Git 副本；子代理在其中工作，並回傳差異供你檢查。

檔案本文就是系統提示

Frontmatter 後方是一般 Markdown，也就是子代理的系統提示。不需要特殊結構，但以下模式已經證實有效：

1. 你是誰 — 用一句話說明：「你是程式碼審查員」、「你是安全稽核員」、「你負責維護文件」。
2. 何時會呼叫你，以及你首先會做什麼 — 收到工作後的前 2–3 個動作。
3. 檢查項目或步驟清單 — 子代理應遵循的 5–10 個要點。
4. 你要回傳什麼 — 最終報告格式。這點很重要：若未指定格式，子代理會寫成「一篇文章」，而不是結構化摘要。
5. 你不會做什麼 — 明確列出限制。沒有這一節，子代理就容易自行發揮。

本文請控制在 200–500 行。如果內容更長，請將冗長的參考資料移至附近的獨立檔案，再於提示中連結。

如何撰寫說明，讓 Claude 一定會呼叫你的子代理#

常見的痛點是設定了程式碼審查子代理，但 Claude 完全自己處理，沒有使用代理。通常只有一個原因：description 寫成「程式碼審查助手」。Claude 無法理解何時應該觸發它。

有效說明的公式（3 個部分）

部分 1 — 代理的功能。 用一句話描述結果，而不是過程。不要寫「分析程式碼」，而要寫「找出程式碼漏洞，並回傳包含嚴重程度與修正方式的清單」。

部分 2 — 觸發時機。 加入 3–5 個實際使用者會提出的需求語句，並用引號括住。不要猜，查看聊天記錄和真實用語。

部分 3 — 不應觸發的時機。 寫出 1–2 種類似但不應由此子代理回應的工作。沒有這一部分，兩個相似的代理就會一直衝突。

魔法語句「Use Proactively」

Anthropic 官方文件直接提出以下建議：

換句話說，如果 description 沒有明確訊號，Claude 預設不太會呼叫子代理。加入「use proactively」或「完成程式碼後立即使用」，啟用機率就會大幅提高。

有效說明的範例

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

這個範例有效的原因：

• 動詞「reviews」和「returns」指出具體成果，而不是處理過程。
• 「Proactively」和「immediately after」是明確的觸發條件。
• 「Do not invoke for...」避免與相似子代理衝突。
• 說明使用英文是標準做法。Claude 使用英文比對的效果更好。

10 分鐘內可開始使用的 5 種子代理角色#

以下每個角色都是一個 .claude/agents/<name>.md 檔案。建立檔案後，重新啟動 Claude Code，開啟 /agents，確認新代理出現在清單中。接著就能使用 @agent-name 呼叫它。

1. code-reviewer — 每次變更後審查程式碼

這是 Anthropic 文件中的官方範例，依工作流程調整而成：

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

啟動時：
1. 閱讀主工作階段提供的 diff 與變更檔清單；若缺少，請主工作階段補上。
2. 使用 Read、Grep、Glob 檢查相關檔案。
3. 回傳發現，不修改檔案，也不執行 shell 指令。

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

關鍵是 tools: Read, Grep, Glob：審查員只有讀取與搜尋工具，沒有 Bash、Write 或 Edit。主工作階段準備並傳遞 diff。只在提示中要求執行 git diff，不能限制已完整授予的 Bash 工具。

2. security-auditor — 找出漏洞與資料外洩

這個角色以 opus 進行深入推理，並同樣限制為 Read、Grep、Glob。唯讀範本省略持續記憶，因為啟用代理記憶也會給它記憶寫入能力：

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

工具是唯讀的，並使用 model: opus 進行漏洞鏈等複雜檢查。

3. research-agent — 深入研究 8 個以上來源

Anthropic 在介紹多代理研究系統的文章中說明了這種模式。關鍵在於明確指定輸出格式，並禁止直接貼上原始結果：

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 是避免研究陷入無止盡反覆的防護措施。Anthropic 在多代理系統中報告了這個數字：

90% 指的是研究基準測試的任務。實際商務工作的提升幅度較小，但整體量級相近。

4. doc-maintainer — 讓文件與程式碼保持同步

這個角色使用 model: haiku，是「成本控管」的典型範例。文件工作不需要 Opus；Haiku 就能完成，價格只有三分之一：

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent — 透過 worktree 安全重構

這個角色使用 isolation: worktree，讓子代理在儲存庫的獨立副本中工作，只有確認沒問題後才合併：

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

使用這種角色，就能避免重構中最令人頭痛的情況——「我把程式弄壞了，還不知道怎麼還原」：原始副本會保持不變，子代理則在獨立的 worktree 中工作。

你不只想複製現成的子代理，還想組合出讓 Claude 成為穩定工具的配置嗎？子代理是你的AI 分身的一部分，也是讓 Claude 擁有一支依照你的邏輯工作的專業團隊的方法。這套方法論有三大支柱：AI 分身（Skills + Subagents）+ Second Brain + Context Engineering。這套組合能讓 Claude 從憑空猜測的助理，轉變為依照你的邏輯思考的工具。

平行啟動 5 個子代理：協調者 + 工作代理#

平行協調的配置就像「指揮家 + 管弦樂團」。指揮家掌握計畫，不負責寫樂譜，並檢查演奏成果。有人演奏錯誤時，指揮家會請他重來，而不是取代他完成演奏。

對企業家而言，更貼切的比喻是行銷公司為新客戶準備策略。一位分析師執行 SWOT 分析，另一位進行競爭者分析，第三位建立受眾輪廓；資深分析師排除不符合預算的假設，專案經理則整理最終簡報。在 Claude Code 中，這條流程只需一句話就能啟動，而且批判檢查已內建於流程中，不必等到事後才進行。

最簡單的協調提示

在主聊天中輸入一句話就足夠：

平行啟動五個子代理：三個 research-agent 分別研究不同來源
（Anthropic 文件、GitHub 儲存庫、AI 部落客），一個 critic-agent 篩除
薄弱結論，另一個 summary-agent 負責整理最終文件。

背景：我正在撰寫一篇關於 X 的指南。目標篇幅：2,000 字，附上來源。
開始前，每個代理都要先讀取 CLAUDE.md。

Claude 接著會委派給五個代理。每個代理都在自己的脈絡中工作：research-agent 使用各自的來源，critic 負責篩選，summary-agent 負責彙整。只有最終摘要會回到主聊天。

適合平行處理的工作

並非所有工作都適合。只有在以下情況，平行執行才有意義：

1. 工作彼此獨立。如果 research-agent #2 正等著 research-agent #1 的結果，就不算平行，而是實際上依序執行。
2. 工作需要較長時間。平行處理「刪除行尾空白」毫無意義，啟動子代理的額外成本會抵銷收益。
3. 你有足夠的使用額度。詳情見下方的獨立章節——平行子代理會快速消耗 Token。

Anthropic 的多代理 v2：再進一步

2026 年 5 月，Anthropic 推出了 Multi-Agent Orchestration v2。它與傳統的平行啟動子代理方式有三項重要差異，詳情見下一節。

多代理 v2 有哪些新功能：協調、成果和 Dreaming#

Multi-Agent Orchestration：共用檔案系統 + 工作中途確認

Anthropic 對這項功能的描述如下：

與傳統子代理的主要差異是共用檔案系統。過去每個子代理都完全獨立工作，只能透過回傳摘要交換資訊。現在，專家可以寫入共用資料夾，主代理也能隨著工作進展讀取成果，而不必等到最後。這解決了「大家忙了一整天，最後才發現兩個人的做法彼此不相容」的問題。

第二項功能是工作中途確認。主代理可以暫停工作，詢問任何專家的進度，接著調整整體計畫。這與真實團隊經理的工作方式相當接近。

Outcomes：以評分標準取代逐步指令

使用 Outcomes 時，你只要撰寫成功標準，代理就會自行找出達成方法。獨立評分代理會在自己的脈絡中檢查結果，因此不會受到主代理推理的「污染」。

在具挑戰性的工作上提升 10% 是很大的進步。尤其是把任務描述為「撰寫一篇符合這些品質標準的長文」，而不是「依照步驟 1–7 操作」時。

Dreaming：代理會在工作階段之間累積經驗

這是概念上最新的功能。代理會檢視過去的工作階段，找出成功與失敗的模式，並更新記憶儲存區。你可以設定變更套用前由人工審查，也可以讓代理自行編輯記憶。

Anthropic 表示，法律科技公司 Harvey 在導入 Dreaming 後，法律文書撰寫工作的成功率提高了約 6 倍。這已經在正式環境運作，而不只是展示用的 Demo。

這對不寫程式的企業家代表什麼

目前必須透過 Claude Agent SDK 使用 Multi-Agent Orchestration，無法直接在 Claude Code CLI 中使用。不過方向很明確：協調方式正在從「你手動啟動 N 個子代理」轉變為「你描述任務，由主代理決定委派對象與方式」。如果你剛開始使用子代理，不必急著考慮 v2。先熟悉「1 個主聊天 + 3–5 個不同角色的子代理」這種傳統模式，3–6 個月後就能自然轉向 Managed Agents。

讓子代理失去作用的 7 個錯誤#

錯誤 1：「X 助手」這類說明不會觸發代理

症狀：你撰寫子代理、檢查結構，一切都有效，但 Claude 不會在使用者提出要求時呼叫它。原因幾乎總是相同：說明太抽象，例如「程式碼審查助手」。解決方法：直接在說明中加入 3–5 個實際的使用者用語並加上引號，再加上「use proactively」或「use immediately after」。

錯誤 2：需要 Skill 時卻建立子代理

子代理比 Skill 成本更高，因為它會建立自己的脈絡、載入自己的系統提示，並使用更多 Token。如果工作很短、不會消耗主脈絡，而且一次就能完成，那就應該使用 Skill，而不是子代理。反面範例：用 format-validator 子代理依據 20 條規則檢查 JSON Schema。這應該做成 Skill：只需要一個模型，不必隔離，也不必載入額外脈絡。

錯誤 3：一開始就啟動「60 個平行代理」

這是最普遍的錯覺。你看到有人發文說「我有 1,500 個代理正在工作」，就想著「我也應該這樣做」。實際上，60 個代理會在一小時內用完 Pro 方案的額度，產生一堆彼此衝突的結果，等到一天結束時卻什麼都沒完成。

一位 Medium 的實務工作者這麼說：

解決方法：先用一個子代理處理一項工作。熟悉後，再加入一個不同角色的子代理。熟悉兩個代理的協調方式後，再擴大為 3–5 人團隊。從「昨天才安裝 Claude Code」直接跳到「今天平行執行 20 個」，一定會弄壞程式碼並耗盡額度。

錯誤 4：讓每個代理都能使用所有工具

如果程式碼審查員能使用 Bash、Write 和 WebFetch，就會造成巨大的安全與成本漏洞。審查員不應該有權寫入檔案，更不需要上網。

解決方法：嚴格限制 tools。程式碼審查員只使用 Read, Grep, Glob。安全稽核員使用同樣的讀取／搜尋工具，diff 由主工作階段提供。加入 Bash 會授予 shell 能力，不會自動限制為 git diff。研究代理則使用 WebFetch, WebSearch, Read, Write。不要給子代理超出單一特定工作所需的權限。

錯誤 5：子代理把原始結果塞進主脈絡

如果研究代理把「我找到的 30 個頁面都在這裡，你自己整理」回傳給主聊天，你就失去了子代理最大的優勢：隔離雜訊。解決方法：在子代理的系統提示中明確要求輸出格式。「只回傳：3 點 TL;DR + 5 個來源清單。禁止貼上程式碼，禁止回傳原始搜尋結果。」格式應該嚴格，不要讓子代理有自由將內容「寫成一篇文章」。

錯誤 6：呼叫內容模糊，委派要求不清楚

子代理看不到主對話的歷史。它會以全新的脈絡開始，再加上 CLAUDE.md，以及你明確寫給它的內容。如果你只寫「修復驗證」，子代理就會自行編造。請改成：「修復 OAuth 重新導向迴圈：使用者成功登入後，會被導向 /login，而不是 /dashboard。檔案：src/lib/auth.ts。」

明確的原則是：委派工作時，提供的脈絡應該與剛加入專案的新承包商所需的脈絡一樣完整。

錯誤 7：建立以角色為基礎，而非以任務為基礎的代理

一種看似誘人的模式是：「我們來建立 frontend-developer、backend-developer 和 qa-engineer，讓他們組隊工作。」這行不通。每個「角色」都會失去整個專案的脈絡，而且彼此看不到對方，無法就細節達成共識。

解決方法：子代理應處理可重複執行、輸出明確的任務，而不是扮演某種角色。不要叫「frontend-developer」，而是叫「explore-ui-tree」、「refactor-component」、「audit-accessibility」。每個以任務為基礎的子代理只負責一項明確工作，並回傳一項明確成果。

平行子代理的成本是多少？什麼時候值得使用？#

如果在複雜任務中啟動 5 個平行子代理，Pro 方案會在一小時內用完。Max 5x（$100）是經常進行平行工作的實際最低方案。團隊和 Enterprise 的費用則在工具預算層級處理。

若想進一步了解如何在 Claude Code 節省 Token，請參閱額度指南。對子代理來說，重要原則是：只有在需要至少 10 分鐘專注處理的工作上，使用子代理才值得。如果工作時間更短，就不要建立子代理；在主聊天或使用 Skill 完成即可。

如何將子代理整合至 AI 分身與 Second Brain？#

建立第一個專門代理前，你的專案應該先準備好三項內容：

1. 適當的 CLAUDE.md。 子代理開始工作前會先閱讀 CLAUDE.md，它就像「聘僱契約」。沒有它，子代理就不知道專案脈絡、限制或語氣，會自行編造。

2. 基本的 Skills。 Skill 是封裝好的方法。子代理只會載入所需的 Skills，不會一次載入所有 Skills。沒有 Skills，子代理每次都會從頭重複工作。

3. Second Brain：知識架構。 business/ 資料夾（或你所屬領域的相應資料夾）是所有子代理都會查閱的資料庫。沒有它，子代理只能給出一般的 ChatGPT 答案，與任何人收到的答案都沒有差別。

顛倒順序只會帶來熱潮，沒有成果。若 business/ 資料夾空空如也，卻宣稱「我有 60 個平行子代理」，就只是用相同方法開了 60 個普通的 ChatGPT 工作階段。

完整組合——AI 分身 + Second Brain + Context Engineering——是讓 Claude 保持一致的三大支柱。子代理是 AI 分身的一部分，能讓 Claude 擁有依照你的邏輯工作的專業團隊。

最快的入門方式是將上方第一個範例中的 code-reviewer 複製到 .claude/agents/code-reviewer.md，重新啟動 Claude Code，並在下一次提交時呼叫 @agent-code-reviewer。只要 5 分鐘，你就會知道自己需不需要子代理，還是主聊天已經足夠。