Claude Code Subagent怎麼用？3分鐘建好第一個子代理，判斷何時該多Agent分工
一個任務想同時檢查安全性、效能和測試，只能一件一件問AI？本文說明Subagent（子代理）的分工模式，帶你用一個Markdown檔建立第一個官方Subagent，再用一張表判斷什麼任務適合多Agent協作。本文節錄自《Claude Code全攻略》。
文／曾慶良（阿亮老師）
本文目錄（點擊可快速前往）
編按：本文收錄Subagent觀念與官方Subagent實作；以Python自製Orchestrator的逐步教學未收錄，文末附「進階實作提示詞」，可直接讓Claude Code幫你建好。
什麼是Subagent？官方Subagent、自製Orchestrator差在哪？
一般使用Claude Code的互動是一對一的：你問一個問題，Claude回答，然後再問下一個。
Subagent（子代理）改變了這個模式：
你的指令
↓
Orchestrator Agent（協調者）
├──> Subagent A：分析安全性
├──> Subagent B：分析效能
└──> Subagent C：分析測試覆蓋率
↓（三個同時執行）
Orchestrator 收集結果，合併報告
為什麼要用多Agent？
- 速度：3個任務同時跑，比依序執行快3倍
- 專注：每個Agent只做一件事，提示詞更精準
- 隔離：一個Agent失敗不影響其他Agent的結果
- 規模：一個人管不完的工作，交給Agent軍團
「Subagent」其實有兩種
在Claude Code的語境裡，「Subagent／子代理」這個詞指兩件不同的東西，別混在一起：
| 官方Subagent | 自製Orchestrator | |
|---|---|---|
| 本體 | .claude/agents/*.md 定義檔（YAML frontmatter + system prompt） | 你自己寫的Python腳本 |
| 執行方式 | 在互動session內，由主Agent自動委派或你明確指名 | 用 claude --print 開多個獨立進程平行呼叫 |
| 上下文 | 每個Subagent有獨立context，結果回傳主對話 | 每個進程完全獨立，由腳本收集輸出 |
| 適合 | 重複使用的專職角色（審查員、測試員、文件寫手） | 大量平行任務、CI/CD整合、跨專案批次處理 |
官方Subagent是Claude Code內建、最正規的子代理機制（下文會帶你從零建立）；自製Orchestrator則是當你需要一次派遣大量Agent、或把Claude塞進自動化管線時用。
建立第一個官方Subagent：直接寫.claude/agents/檔案
若走「Python orchestrator + --print CLI」的程式化路線，可以一次派遣大量Agent平行工作。但你的第一個Subagent不應該寫Python——官方Subagent只是一個Markdown檔案，3分鐘就能建好。
舊版備註：舊版Claude Code曾提供 /agents 互動式精靈（7步驟引導建立Agent），該精靈已於v2.1.198（2026-07-01）移除。現在的做法是直接建立定義檔，反而更快、更透明；細節以官方文件為準。
官方Subagent的本體是一個放在以下位置的Markdown檔案：
| 位置 | 範圍 | 適合場景 |
|---|---|---|
| .claude/agents/（專案根目錄下） | 只有目前專案能用 | 跟專案綁定的Agent（如Flask app的API tester） |
| ~/.claude/agents/ | 所有專案都能用 | 跨專案通用的Agent（如「程式碼審查員」） |
第一次練習建議放專案級，玩壞了不會影響其他專案。
建立資料夾與定義檔
# Windows PowerShell（在專案根目錄下）
New-Item -ItemType Directory -Force .claude\agents
notepad .claude\agents\security-reviewer.md
# macOS / Linux（在專案根目錄下）
mkdir -p .claude/agents
nano .claude/agents/security-reviewer.md
security-reviewer.md 完整內容（可直接貼）
---
name: security-reviewer
description: 安全性審查專家。當使用者要求檢查安全漏洞、SQL injection、硬編碼密碼、eval/exec 濫用、輸入驗證問題時使用此 agent。
tools: Read, Grep, Glob
model: sonnet
---
你是一位資安專家，專門審查 Python 程式碼的安全性。
分析範圍：
- 注入攻擊（eval、exec、shell injection、SQL injection）
- 敏感資料處理（明文密碼、硬編碼金鑰、個資）
- 不安全的函式使用
- 缺少輸入驗證
輸出格式：Markdown 報告，每個問題標注嚴重度（🔴嚴重/🟠中等/🟡輕微）、檔案與大約行數、問題描述、具體修正建議。
只報告確定的問題，不要猜測。
frontmatter欄位說明：
| 欄位 | 作用 | 填寫要點 |
|---|---|---|
| name | Agent的識別名稱 | 小寫加連字號，如 security-reviewer |
| description | 決定觸發時機 | 主Agent根據這段描述判斷「什麼時候該委派給它」，把使用情境寫清楚 |
| tools | 允許使用的工具 | 最小權限原則：安全性審查只需要讀（Read、Grep、Glob），不給Write/Edit/Bash |
| model | 使用的模型 | sonnet（平衡，推薦）/ opus（最強）/ haiku（最快最省）/ inherit（跟主Agent相同） |
模型怎麼選：安全性審查建議sonnet（對應目前的claude-sonnet-5）——haiku（claude-haiku-4-5）太簡略容易漏掉細節；opus（claude-opus-4-8）或旗艦fable-5留給真正需要深度推理的任務，這類審查用不到。
觸發你的Subagent
存檔後重新啟動Claude Code（讓它重新讀取agents資料夾；是否需要重啟以實際版本為準），有兩種觸發方式：
- 自動委派：你的要求符合description描述時，主Agent自動把工作交給它
- 明確指名：直接說「用security-reviewer幫我審查calculator.py」
這裡拿calculator.py當練習對象，裡面故意留了eval()、shell=True等資安問題。你也可以換成手邊任何一支.py。
[模擬]觸發該Agent的對話：
> 用 security-reviewer 幫我審查 calculator.py
● security-reviewer(審查 calculator.py 的安全性)
完成
發現 2 個問題：
嚴重：calculate_from_string 使用 eval() 執行未驗證輸入
存在任意程式碼注入風險，建議改用 ast.literal_eval()
中等：run_calculator_script 以 subprocess.run(..., shell=True) 執行外部指令
若 script_path 來源可控則有 shell injection 風險，建議改為 shell=False 並拆成清單
官方Subagent vs.自製Orchestrator：什麼時候用哪個？
| 你的目標 | 推薦方式 |
|---|---|
| 第一次建Subagent練手 | .claude/agents/定義檔（本文示範） |
| 重複呼叫同一個專職Agent | .claude/agents/定義檔即可 |
| 一次平行派遣3+ 個Agent | Python orchestrator |
| 整合進CI/CD pipeline | Python orchestrator |
| 跨專案複用同一套Agent | 定義檔放~/.claude/agents/ |
結論：先用定義檔把「一個Agent一個職責」的概念跑通；自製Orchestrator是進階用法，學會了能應付更大規模的協作場景。
Subagent適用情境：什麼任務適合多Agent協作？
不是所有工作都適合Subagent架構。這張表幫你判斷：
| 情境 | 建議架構 | 原因 |
|---|---|---|
| 分析一個檔案的bug | 單一Agent | 任務小，不值得overhead |
| 同時分析多個面向（安全/效能/測試） | Multi-Agent | 面向獨立，可平行 |
| 處理50個檔案，每個需要翻譯 | Multi-Agent | 大量獨立子任務 |
| 寫一個複雜的功能，步驟有依賴 | 單一Agent | 步驟有前後依賴，無法平行 |
| 每天掃描新增的PR | 定時Orchestrator | 結合Routines定時執行 |
| 跨語言文件翻譯（10種語言同時） | Multi-Agent（10個） | 語言翻譯互相獨立 |
核心原則：任務之間沒有依賴關係、可以獨立完成，才值得用Multi-Agent。
【進階提示詞】讓Claude Code幫你建好Orchestrator
複製以下提示詞，直接貼進Claude Code開始操作。提示詞裡的檔名／路徑是示意，請換成你自己專案裡實際存在的。
開始前，請先確認兩件事：
- 系統已裝Python 3——Orchestrator是Python腳本。先驗證 python --version（沒反應試 py --version）。
- claude指令在PATH裡——腳本會呼叫claude。先在終端機直接打 claude --version，確認叫得動。
Step 1：建立Orchestrator腳本
請幫我建立 orchestrator.py，能夠同時啟動 3 個子 Agent 分別執行：安全性掃描（偵測硬編碼密碼和 SQL injection）、效能分析（統計函式長度和巢狀層數）、測試覆蓋率報告。完成後合併三份報告輸出總結。Step 2：執行並驗證結果
請執行 orchestrator.py，等待所有子 Agent 完成後，顯示最終整合報告，並標出最需要優先修正的問題。
節錄自：博碩出版《Claude Code全攻略：從一句話到部署上線，打造你的AI Agent開發團隊》／曾慶良（阿亮老師） 著
