Claude Code子代理怎麼分工？角色設定、平行與驗收

Claude Code 的子代理（subagent）在自己的 context 裡工作，做完只把結果交回主對話。每個子代理是 .claude/agents/ 裡的一個 Markdown 檔，可以指定工具與模型。分工的重點是工具給到剛好、互不相依的工作平行派，交件後另派代理獨立查證。

本文用一個假案例示範：假設你在做一個記帳網站，叫做豪享記帳，前端是 Next.js、後端是 Go。內容包括角色設定檔、內建子代理、平行派工與 worktree，以及交件後怎麼驗收。

延伸閱讀：Claude Code Skills 怎麼寫

Claude Code 子代理是什麼？和主對話差在哪？

子代理是主對話派出去的分身，在全新的 context 裡做一件事。它看不到你和 Claude 的對話歷史，也看不到主對話讀過的檔案。做完以後，只有最後的回報會回到主對話。

子代理啟動時只拿到這幾樣：

• 系統提示：代理檔的本文，加上工作目錄等環境資訊，不含 Claude Code 預設的系統提示。
• 派工提示：Claude 依你的要求寫的任務說明。
• CLAUDE.md：主對話載入的各層都會載入，內建的 Explore 與 Plan 除外。
• git 狀態：啟動當下的快照，Explore 與 Plan 同樣不拿。
• 預載的 skill：skills 欄位列出的 skill 全文。

子代理從全新的 context 開始，只有最後的回報回到主對話

對話歷史、主對話的自動記憶與輸出風格，都不會帶進子代理。子代理也不能反問你，所以派工提示要一次寫齊目標、範圍與交件格式。需要它看到整段對話時，用 /subtask 開一個 fork，fork 會繼承完整的對話。

什麼時候該用子代理？

官方的建議是：要來回討論的事留在主對話，輸出很長、能獨立完成的事交給子代理。

主對話、子代理與 skill 怎麼選

資料來源：Claude Code 官方文件 Subagents

內建的 Explore、Plan 和 general-purpose 各做什麼？

Claude Code 內建幾個子代理，不用設定，Claude 會在適合的時候自己派。最常用的是下面三個。

Claude Code 內建的子代理

資料來源：Claude Code 官方文件 Subagents

Explore 與 Plan 不載入 CLAUDE.md，是為了讓搜尋又快又省。代價是專案規則到不了它們身上，像「略過 web/.next/」這種規則，要寫進派工提示。

呼叫 Explore 時，Claude 會指定搜尋深度：quick、medium 或 very thorough。Explore 與 Plan 是一次性的，做完不能接續；要接續的工作，改用 general-purpose 或自訂代理。

想讓 Explore 改用比較省的模型，可以在專案建一個同名的 Explore 代理。代理檔寫上 model: haiku，就會蓋過內建的版本。

子代理的角色設定檔怎麼寫？

子代理是一個帶 YAML frontmatter 的 Markdown 檔。frontmatter 只有 name 和 description 必填，--- 下面的本文就是它的系統提示。

設定檔放在哪裡？

子代理設定檔的位置與優先順序

資料來源：Claude Code 官方文件 Subagents

同名時，優先順序高的生效。專案的代理可以提交到 git，和團隊共用同一套角色。

建立的方式有兩種：請 Claude 幫你寫，或自己建檔。agents 資料夾如果是會話開始後才建的，要重開 Claude Code 才讀得到。

豪享記帳的審查員怎麼寫？

下面是豪享記帳的審查員，存成 .claude/agents/reviewer.md：

---
name: reviewer
description: 豪享記帳的程式碼審查員。改完 Go API 或 Next.js 頁面後主動使用。只審查、不改檔。
tools: Read, Grep, Glob, Bash
model: opus
skills:
  - api-conventions
---

你是豪享記帳的程式碼審查員，只審查這次的改動，不修改任何檔案。

## 開始時
1. 用 git diff 看這次改了什麼。
2. 讀改到的檔案全文，不只看片段。
3. 對照預載的 api-conventions 檢查 API 寫法。

## 檢查重點
- 金額的加總與四捨五入是否正確
- 使用者只能讀寫自己的帳本
- 錯誤訊息不帶出資料庫的原始訊息

## 回報格式
每個問題寫：嚴重度、檔案與行號、為什麼是問題、建議修法。
最後給結論：放行，或退回並說明要修什麼。

這份設定檔的每個欄位各有用途：

• name：唯一名稱，不能有冒號；檔名不必和它一樣。
• description：寫「什麼時候該派它」，Claude 靠這段決定派不派。
• tools：白名單。審查員只給讀檔、搜尋與 Bash，不給 Write 與 Edit。
• model：要做判斷的審查員用 opus。
• skills：啟動時就把 API 規範的全文放進 context，不必在本文叮嚀「先去讀某份文件」。

注意：Claude Code 會默默略過認不得的欄位，不會報錯；沒有 name 的檔案會被當成說明文件，整個不載入。懷疑欄位拼錯時，用 claude --debug 啟動，除錯紀錄會列出認不得的欄位。

常用的欄位有哪些？

子代理 frontmatter 常用欄位

資料來源：Claude Code 官方文件 Subagents

description 怎麼寫才會被派到？

Claude 會綜合你的要求、每個代理的 description 與目前的情境，決定要派給誰。想讓它主動派，description 裡寫明時機，例如「改完程式後主動使用」；官方範例的寫法是 use proactively。

每個 description 要具體到只對應一個代理。所有代理的 description 合計超過 15,000 tokens，啟動時會出現警告。

自己點名也可以，由弱到強有三種方式：

1. 用自然語言點名：例如「請 reviewer 子代理看一下這次的改動」，由 Claude 決定要不要派。
2. 用 @ 指定：一定派給這個代理，適合單次任務。
3. 整個會話當成這個代理：用 claude --agent reviewer 啟動，或在專案設定寫入 agent。

@"reviewer (agent)" 看一下這次預算 API 的改動

claude --agent reviewer

不想讓 Claude 用某個子代理，在 permissions.deny 加上 Agent(名稱)。內建與自訂的子代理都適用，例如 Agent(Explore)。

tools 白名單和 model 怎麼選？

工具只給這個角色需要的。tools 是白名單，省略就繼承子代理能用的全部工具；disallowedTools 是黑名單，兩個都寫時先套用黑名單。

豪享記帳可以設四個角色，工具與模型各不相同：

豪享記帳的子代理分工

判斷型的角色用較強的模型，照規格動手的角色用較快的模型。model 省略時，先用派工時指定的模型。沒有指定，再看環境變數 CLAUDE_CODE_SUBAGENT_MODEL；都沒有，才用主對話的模型。

注意：tools 只能整個開或整個關，給了 Bash 就能跑任何指令。要擋 git push 這類特定指令，在權限規則的 deny 加上 Bash(git push *)，或改用 hook。這條權限規則對主對話和子代理都有效。

下面是寫手的設定檔。它開了 memory: project，會自己累積筆記：

---
name: writer
description: 豪享記帳的說明文件寫手。要寫或改使用說明、更新日誌時使用。
tools: Read, Grep, Glob, Write, Edit
model: sonnet
memory: project
---

你替豪享記帳寫使用說明，放在 docs/help/。

- 步驟照畫面上的按鈕名稱寫，先讀 web/ 的頁面程式確認
- 一篇只講一個功能，第一段先說這個功能能做什麼
- 開始前先看你的記憶；收到修改意見後，把通用的規則記下來

交件時回報：檔案路徑、寫了哪些步驟、哪些地方不確定。

記憶存在 .claude/agent-memory/writer/。代理啟動時，會讀進其中 MEMORY.md 的前 200 行或 25KB。範圍可以選 user、project 或 local；選 project 時，記憶會跟著 git 和團隊共用。

怎麼平行派工？前景、背景與同時上限

互不相依的工作，可以一次派好幾個子代理同時做。直接用自然語言交代就好：

用 3 個 writer 子代理平行寫三篇使用說明：記一筆支出、設定每月預算、匯出報表。
每篇寫在 docs/help/ 底下自己的檔案。
全部寫完後，派 fact-checker 逐篇查證，只回報問題。

子代理有前景與背景兩種跑法：

• 前景：主對話等它做完才繼續，權限詢問直接交給你。
• 背景：和你同時工作；需要權限時，詢問會出現在主對話，並標出是哪個子代理在問。

執行中的任務按 Ctrl+B 可以移到背景。背景子代理能用的內建工具比較少；它做完會送出完成通知，Claude 收到通知後才回報結果。

互不相依的工作同時派，改程式的代理放進自己的 worktree

前後相依的工作，就請 Claude 依序派。例如先讓 reviewer 找出問題，再交給另一個代理修，Claude 會把前一個的結果整理給下一個。

同時可以跑幾個子代理？

預設同時最多 20 個，額滿時再派會失敗，等有代理做完才能再派。要調整上限，在設定的 env 加上環境變數：

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5"
  }
}

補充：每個子代理做完，結果都會回到主對話。派得太多、回報寫得太長，一樣會塞滿主對話的 context，每個子代理執行時也各自消耗 tokens。

我的做法：寫系列文時，我一次派幾個寫手各寫一章，給同一份寫作指引，主對話只收每章的簡短回報。會呼叫外部服務的工作則不平行，只在主對話依序做，免得撞上對方的流量限制。

平行改檔怎麼避免互相覆蓋？用 worktree 隔離

幾個子代理同時改同一個 repo，可能改到同一個檔。解法是在 frontmatter 加上 isolation: worktree。子代理會在暫時的 git worktree 裡工作，拿到一份獨立的程式碼。

---
name: tester
description: 豪享記帳的測試員。新功能或修 bug 之後主動使用。補測試、跑測試，回報實際輸出。
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
isolation: worktree
---

你負責替這次的改動補測試，並且實際跑過。

- 後端：在 api/ 執行 go test ./...
- 前端：在 web/ 執行 npm test
- 只新增或修改測試檔，不改功能程式

回報：跑過的指令、通過與失敗的數量、失敗的錯誤訊息。
沒有實際輸出，就不算測過。

worktree 的規則有幾條要先知道：

• 從哪裡開分支：預設從 repo 的預設分支開，通常是 main，不是你目前的 HEAD。
• 要帶進手上的進度：在設定把 worktree.baseRef 設成 "head"，從目前的 HEAD 開分支；還沒 commit 的改動帶不過去，先 commit 再派。
• 沒改東西：子代理做完，worktree 會自動刪掉。
• 有改東西：worktree 留在磁碟上，你檢查過再把改動合併回來。
• 被 gitignore 的檔：.env 不會出現在 worktree；要複製的檔，列在專案根目錄的 .worktreeinclude。

{
  "worktree": {
    "baseRef": "head"
  }
}

api/.env
web/.env.local

不是每個代理都要設 worktree。只讀不寫的審查員，或各寫各檔的寫手，都不需要。

整個會話也能開在 worktree 裡嗎？

可以。下面的指令會建立 .claude/worktrees/budget-report/。新分支的名稱是 worktree-budget-report。

claude --worktree budget-report

記得把 .claude/worktrees/ 加進 .gitignore。這樣 worktree 的內容，才不會出現在主目錄的未追蹤檔案裡。

資料來源：Claude Code 官方文件 Worktrees

子代理交件後怎麼驗收？寫手平行加獨立查證

子代理說「做完了」，不等於做完了。可靠的做法是讓寫的和查的分開：寫手平行寫，寫完另派一個沒參與的代理查證。

查證員在全新的 context 裡啟動，看不到寫手的思路，只看成品和程式碼。它不必替成品辯護，比寫手自己檢查更容易抓到錯。

1. 拆工：主對話把工作拆成互不相依的幾份，每份寫清楚範圍與交件格式。
2. 平行寫：每份派一個寫手，各寫各的檔案。
3. 獨立查證：寫完派唯讀的查證員，逐項對照程式碼，只回報問題。
4. 彙整與修正：主對話整理問題，請 Claude 接續原本的寫手修改，修完再查一次。

寫的和查的分開，有問題就交回原寫手修，修完再查

接續原本的寫手，它會保留前一輪的完整脈絡，不必從頭說明。內建的 Explore 與 Plan 不能接續，所以要修改的工作，派給自訂代理或 general-purpose。

查證員的設定檔只給讀檔與搜尋：

---
name: fact-checker
description: 使用說明寫完後的獨立查證員。對照程式碼檢查每個步驟、按鈕名稱與數字，只回報、不修改。
tools: Read, Grep, Glob
model: opus
---

你沒有參與寫作，任務是找出文件和程式不一致的地方。
預設每一句都可能寫錯，找到程式碼證據才算正確。

## 回報格式
每個問題寫：文件位置、文件的寫法、程式的實際行為（附檔案與行號）、建議改法。
沒有問題，就回報「全部一致」。

交件要附什麼證據？

回報只寫「完成了」，主對話無從驗收。交件格式先寫進代理本文，每種角色要附的證據不同：

• 測試：跑過的指令與實際輸出，只寫「測試通過」不算。
• 文件：檔案路徑，加上每個步驟對照的程式位置。
• 審查：每個問題的檔案與行號、為什麼是問題、建議修法。

子代理的回報是資料，不是你的指令。官方會在回報前加上標頭，說明裡面的指示與核准說法都只是子代理的話；要不要上線、要不要 push，仍然由你決定。

我的做法：寫的和審的一定分開，審查員只回報、不改檔。嚴重的問題再派 3 個查證者，分別從觸發路徑、既有防護與實際影響嘗試推翻，過半成立才修。

這樣能少掉很多為了誤報而改的程式。官方也支援子代理再派子代理，例如審查員替每個問題各派一個查證者；審查員的 tools 要列上 Agent 才派得出去。完整流程寫在一人開發怎麼用AI團隊。

舊的代理寫法要怎麼改成官方寫法？

我把自己的代理設定和官方文件逐項比對，下面幾處可以換成官方的寫法。

子代理設定：舊寫法與官方寫法對照

資料來源：Claude Code 官方文件 Subagents

注意：開了 memory，官方會自動給代理 Read、Write、Edit，方便它管理記憶檔。要保持唯讀的審查員與查證員，不適合加 memory。

常見問題

Q1：Claude Code 子代理可以再派子代理嗎？

可以，預設最多到主對話底下 3 層。用環境變數 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 調整，設成 1 就關掉巢狀。要讓某個代理不能再派，tools 白名單不要列 Agent，或把它加進 disallowedTools。

Q2：子代理看得到主對話的內容嗎？

看不到。子代理從全新的 context 開始，拿到的是自己的系統提示、派工提示、CLAUDE.md 與預載的 skill。需要它看到整段對話時，用 /subtask 開 fork。

Q3：Claude Code 子代理和 skill 差在哪？

skill 是一份做事方法，在主對話的 context 裡執行。子代理是另開 context 的分身，有自己的工具與模型。兩者可以搭配，用 skills 欄位把 skill 預載進子代理。

Q4：同時最多能跑幾個子代理？

預設同時 20 個，用 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整。整場會話派的總數沒有上限，但每份回報都會占用主對話的 context。

延伸閱讀

• Claude Code Hooks與權限怎麼設？擋指令與沙箱：用 hook 與權限規則，把「不准改」從文字提醒變成硬限制
• Claude Code Skill怎麼建立？觸發描述與參考檔：description、when_to_use 與分層參考檔的寫法
• 一人開發怎麼用AI團隊？Claude Code分工與上版審查：一個人用代理分工、兩道閘門與上版前審查的實際流程
• AI寫部落格文章有哪些步驟？研究、配圖、審稿與短影片：主編加寫手子代理平行寫文章的產線