多代理深掘：subagent 到 Agent Teams

16.1　主代理規劃、子代理平行探索：orchestrator-worker 骨架

先建立這一章的核心畫面。傳統的「派子代理」是一對一：你叫主代理（lead）派一個子代理（subagent）去查件事、回報。多代理深掘要做的是「一對多、而且同時跑」——主代理像專案領班，先把問題拆成幾個彼此獨立的子題，spawn（派生）出多個子代理平行去查不同面向，最後自己把各路回報綜合成答案。這個分工模式有個正式名字叫 orchestrator-worker（指揮者—工人）。

Anthropic 自家的多代理研究系統就是這個骨架最完整的範例 ✅官方。主代理分析查詢、規劃策略、派出專門化的子代理各自探索，再綜合。關鍵在於：每個子代理拿到的不是一句模糊的「去查一下」，而是一份結構化的工作交辦（brief），講明四件事——目標、要回傳什麼格式、可以用哪些工具、以及明確的邊界（哪些不要碰）。官方的內部評測顯示，這種拆解在「廣度研究」這類任務上，比單一個 Opus 自己埋頭做高出 90.2%。

16.2　不只讓它自己判斷：三種明確呼叫子代理的方式，以及它挑模型的順序

第 10 章教過最常見的用法：你把子代理定義好，剩下的交給 Claude 自己判斷「這句話該不該派給誰」。多數時候這樣就夠了，但你會遇到兩種想親自下指令的時候——一種是「這次一定要用那個特定的助手，不准它自由發揮」，另一種是「我想讓整個對話從頭到尾都用某個子代理的身分跑」。官方留了三條路，份量由淺到深 ✅官方：

決定好「叫誰」之後，還有一件事你未必掌控得到：它到底跑在哪個模型上。第 10 章提過 CLAUDE_CODE_SUBAGENT_MODEL 環境變數的優先權比 frontmatter 的 model 欄位高，這裡把完整的解析順序攤開，值得背起來——它會悄悄決定你的帳單和回答品質 ✅官方：

1. 環境變數 CLAUDE_CODE_SUBAGENT_MODEL——一旦設定，優先權最高，會蓋過底下所有選項，而且悄悄蓋過、不會提醒你。
2. 呼叫當下傳入的 model 參數——例如透過 SDK 或某些呼叫介面明確指定這一次要用哪個模型。
3. 子代理 frontmatter 裡寫的 model 欄位——你在定義檔裡自己寫的那一行。
4. 主對話目前使用的模型——也就是 model: inherit，沒特別指定時的預設行為。

自 v2.1.198 起，子代理也會繼承主對話的 extended thinking（延伸思考）開關設定，不用另外再打開一次。

16.3　別過度 spawn：子代理的投入度縮放規則

知道能「開一群子代理」之後，新手最容易犯的錯就是什麼都想開一群。問一個簡單問題也派十個子代理去查，結果十個各自燒 token、各自回報，你花了十倍成本拿到一個本來一個代理就能答的答案。這不是厲害，這是浪費。

官方對這件事給了明確的縮放規則 ✅官方：子代理的數量要跟著任務複雜度走，而且這條規則要直接寫進主代理的提示裡，讓它自己照著配。下面這張表是官方給的對照量級，你可以當基準：

16.4　兩層平行：最大化省時間的槓桿，加一個專責附來源的子代理

16.1 講的平行是「主代理同時派出多個子代理」。但真正把牆鐘時間（你盯著螢幕等的實際秒數）壓到最低的，是再疊一層平行 ✅官方：主代理同時派出 3 到 5 個子代理，而且每一個子代理自己又同時發出 3 個以上的工具呼叫。兩層都在平行，等於把原本要一件一件排隊做的事攤平。官方說，複雜查詢用這招，牆鐘時間最多能省下大約 90%。

不過平行查得快，有個副作用：資料來得又多又雜，誰來確保最後的答案每一句都掛得回出處？官方的做法是另外設一個專責附來源的子代理（CitationAgent）✅官方。它不負責查，只負責在所有探索跑完之後，做後處理——把每個主張對回它的來源、補上引用。把「查資料」和「附來源」拆成兩種專職，比讓同一個代理邊查邊記出處更可靠。

16.5　委派決策框架：什麼時候該派、以及那個會害你的權限陷阱

前面都在講「怎麼派一群」，這節退一步問更基本的問題：一件事到底該不該委派出去？獨立實踐者 Hidekazu Konishi 整理過一套好用的判斷框架 👤達人。適合委派給子代理的工作有三種特徵：① 是「去查 X、回報給我」這種交辦得清楚的差事；② 過程會產生一大堆你最後用不到的中間輸出（讓子代理在它自己的 context 裡消化掉，別髒了你的主 context）；③ 任務本身獨立自足，不需要中途回頭問你。反過來，需要反覆迭代、或每一步都要你拍板的工作，留在主代理手上做反而順。

講框架之前，得先警告一個高價值的坑——它害過很多人，而且錯了你不容易發現。當你寫一個自訂子代理時，會在它的 frontmatter（檔案開頭的設定區）列出它能用哪些工具。直覺上你會以為「不寫 tools 這一行 = 不給它工具」。完全相反。

下面把「錯的省略」和「對的明寫」並排給你看。重點不是語法，是有沒有那一行 tools：

# ❌ 危險：省略 tools —— 這個「審查員」其實拿到了全部工具，能改你的檔
---
name: code-reviewer
description: 審查程式碼品質
---
你是一位嚴格的程式碼審查員……

# ✅ 安全：明寫 tools —— 鎖死成唯讀，它再怎樣都動不了你的檔案
---
name: code-reviewer
description: 審查程式碼品質
tools: Read, Grep, Glob
---
你是一位嚴格的程式碼審查員……

先看全貌：frontmatter 裡到底能寫哪些欄位

目前為止你看過 name、description、tools、model 這幾個欄位。事實上 frontmatter 能寫的比這多，只有 name 和 description 是必填，其餘全部選填、不寫就用預設值。下面列一份速查，之後遇到需求可以回來查 ✅官方：

白名單配黑名單：tools 與 disallowedTools 怎麼疊加

tools 是白名單（只准列出的這些），disallowedTools 是黑名單（明確擋掉列出的這些）。兩者都支援 MCP 伺服器層級的寫法：mcp__<server> 代表整個 server 的所有工具，mcp__<server>__* 效果相同；disallowedTools 還多支援一個 mcp__*，一次移除所有 MCP 工具。如果同時設定了兩者，套用順序是先套 disallowedTools 排除、剩下的工具池再套 tools 篩選——不是誰蓋過誰，是接力縮小範圍。✅官方

# 移除某個 MCP server 的全部工具，但保留其他工具照樣繼承
---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

整組工具開關不夠精準？用 PreToolUse hook 動手術

有時候你要的不是「整個 Bash 准或不准」，而是「Bash 准，但裡面某幾種指令不准」——這種粒度，tools／disallowedTools 做不到，得靠子代理 frontmatter 裡的 PreToolUse hook（第 8 章介紹過「動手前攔截」這個時機，第 19 章會更完整地展開 hooks 整套機制）動手術。這裡先給一個子代理層級的實例：整體放行 Bash，但用一支 shell script 檢查指令內容，擋掉非 SELECT 的 SQL：

# .claude/agents/db-reader.md —— 只准唯讀查詢的資料庫子代理
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

對應的 validate-readonly-query.sh 讀進 stdin 的 JSON、抓出 .tool_input.command，用 grep -iE 偵測 INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE 這類寫入指令，命中就把錯誤訊息印到 stderr 並 exit 2——子代理的 Bash 呼叫會被擋下，它拿到的是你給的錯誤說明，不是憑空失敗。比「整支工具准或不准」精準得多。👤達人

它能不能再往下 spawn 別的子代理？巢狀深度與白名單

子代理也能再往下 spawn 自己的子代理——前提是它的 tools 清單裡含 Agent。這個能力的細節其實走過一段版本演進，值得攤開講：從 v2.1.172 到 v2.1.216，巢狀 spawn 是預設開放的，深度上限固定 5 層且不可調。但這個「自動開放、固定 5 層」的行為只維持到 v2.1.216——目前官方文件記錄的現況是：巢狀 spawn 改回預設關閉，要設定環境變數 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 才會開啟，深度上限也變成可調整，不再是寫死的 5 層。✅官方 兩個常見的延伸說法本輪查證都沒能找到對應的官方文件段落，不確定就不寫死：一是「第 5 層的子代理不會拿到 Agent 工具、所以無法再往下開一層」這個機制細節；二是「16.6 會提到的延續對話側支任務，不能再對自己執行一次」——都只是流傳的說法，沒查到官方白紙黑字，好奇的話請自己在你安裝的版本上實測，別照抄任何一版說法當定論。如果你看到比較舊的說法講「子代理不能再叫子代理」，不必急著判定誰對誰錯——這條能力一路從「不能」→「預設開放、固定 5 層」→「預設關閉、深度可調」演進過來，不同時間點寫下的說法在寫作當下都可能是對的，只是你讀到的那篇文章剛好卡在哪個版本區間。實務上仍建議克制使用，把串接的指揮權盡量留在主代理，避免巢狀太深難以追蹤（16.6 的「管線」形狀就是這個克制思路的具體做法）。版本號變動快，實際行為請以你當下的官方文件為準。

想限制某個子代理只能再往下叫哪些人，在它的 tools 欄位用白名單語法（只在該子代理以 --agent 身分擔任主執行緒時生效）：

# 只准這個協調者再往下 spawn worker 或 researcher 兩種子代理
---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---
# 不限制類型、全部放行：tools: Agent, Read, Bash
# 完全省略 Agent：這個子代理沒辦法再 spawn 任何子代理

只想單純封鎖特定幾個、其餘照樣放行，改用 permissions.deny 的 Agent(name) 語法（settings.json 裡加一筆 "Agent(my-custom-agent)"），或 CLI 一次性旗標 --disallowedTools "Agent(Explore)"——跟後面關掉整個 Explore 是同一套語法，只是換成關掉某個自訂子代理。

還有一個容易踩到的相關行為要記住：在背景跑的子代理，碰到任何「需要你按確認」的工具呼叫時該怎麼辦。較舊版本會直接自動拒絕該次呼叫、沒辦法回頭問你；v2.1.186 起行為改了——官方 release notes 原句是「改成把權限提示浮現在主 session，不再靜默自動拒絕；對話框還會標明是哪一個子代理在問，按 Esc 只會拒絕那一次那個工具呼叫」。實際行為請以你當下安裝的版本為準，卡住先回主 session 看看有沒有一則等你回應的提示。另外，Claude Code 從 v2.1.198 起預設就會把子代理呼叫放到背景執行（等真的需要結果時才轉前景），你也可以在任何正在跑的任務上按 Ctrl+B 手動把它背景化，先去做別的事。背景執行的子代理，內建工具集也會跟著縮小一圈，只留下 Read、Grep、Glob、Bash、PowerShell、Edit、Write、NotebookEdit、WebFetch、WebSearch、TodoWrite、Skill、ToolSearch、EnterWorktree、ExitWorktree、Monitor、TaskStop、SendMessage、Artifact 這組；你設定的 MCP 工具則完整保留，不受影響。版本號變動快，實際行為請以你當下的官方文件為準。✅官方

Claude 不太主動委派？先檢查你的 description 有沒有寫夠白

自訂子代理建好卻一直沒被用到，多半不是 Claude 壞掉，是 description 沒寫到位。Claude 預設「很少主動」委派給自訂子代理，除非 description 裡有明確的鼓勵字眼——像 use proactively（主動使用）或 use immediately after code changes（改完程式碼立刻用）這類措辭，或是你在 CLAUDE.md 裡明講「什麼情境該委派給誰」。沒寫這些，主代理常常自己把活全包了，你養的子代理形同白建。另一個常見反效果是好幾個子代理的 description 寫得模糊、彼此重疊，這時 Claude 的路由容易選錯，甚至乾脆哪個都不委派、自己硬做——子代理數量一多，路由準確度反而下降，不是越多越好，這點跟 16.3 的縮放規則是同一種紀律。🌐社群

16.6　五種可重用的子代理「形狀」，外加一招 /fork

當你不再把子代理當成「臨時叫來跑一次的工具」，而是當成一套可以反覆套用的編排語彙時，它就升級了。Konishi 把實戰中好用的子代理歸納成五種「形狀」👤達人，你可以照場景挑：

第六招：/fork——延續對話脈絡的側支任務

前面五種形狀都是「開一個全新、context 乾淨」的子代理。但有時候你要的剛好相反：延續剛才這段對話的脈絡，去做一個側支小任務。例如你們剛一起改完一個 parser，你想「順便幫我把剛剛改的地方寫幾個 unit test」——這時開一個全新的子代理反而不順手，因為它看不到你們剛剛討論、修改的內容（16.7 會講到子代理預設看不到主對話歷史，就是這個原因）。

/fork（或設定環境變數 CLAUDE_CODE_FORK_SUBAGENT=1）建立的「fork」跟一般具名子代理不同：它完整繼承目前對話的全部歷史、系統提示、工具、模型。因為系統提示與工具定義跟主 session 一模一樣，第一次請求還能重用主 session 已經累積的 prompt cache（提示詞快取）——比重新 spawn 一個要從頭累積 context 的具名子代理更省成本。代價是它失去了「輸入隔離」這個好處。✅官方 至於它能不能再對自己執行一次（側支任務裡再開一支側支任務），這輪查證沒有找到對應的官方文件段落可以佐證，不確定就不寫死——想知道請自己在目前安裝的版本上實測，別照抄本節任何一版說法當定論。

這五種形狀加上 /fork，都是你自己動手拼出來的編排語彙。如果覺得每個子代理都要從零手刻太累，社群已經有現成的大型合集可以直接挑：wshobson/agents（github.com/wshobson/agents，GitHub 星數 38.2k，走 Unix philosophy——強調單一職責、小而專精，平均每個 plugin 只包 5.5 個元件，可跨引擎裝進 plugin marketplace）與 VoltAgent/awesome-claude-code-subagents（github.com/VoltAgent/awesome-claude-code-subagents，星數約 7.8k～8.5k，收錄範圍更廣的子代理清單）。挑現成的來改，往往比從一張白紙開始寫還快。🌐社群

16.7　子代理躲在哪裡：載入優先序、啟動時看得到什麼、逐字稿去哪找

前面幾節都在講「怎麼用」，這節退到機器房，看看子代理實際上是怎麼被找到、怎麼啟動、跑完去哪裡的。平常用不到這些細節，但踩到坑的時候——例如「我明明改了檔案，它卻好像沒生效」——這節能幫你少猜很多。

同名時誰贏：五層載入優先序

子代理的定義檔可以放在好幾個不同層級，Claude Code 會全部掃過去，同名時由靠前者勝出 ✅官方：

第 3 層要特別說明：Claude Code 會從你目前的工作目錄往上逐層掃描所有 .claude/agents/（跟第 5 章講過的 CLAUDE.md 往上找是同一套邏輯），越接近你目前工作目錄的定義優先。如果同一層目錄樹（含子資料夾）裡出現兩個同名的定義，Claude Code 只會載入其中一個，依檔案系統讀取順序決定，沒有文件化的優先序保證——這是新手很容易誤踩的坑：改了檔案卻感覺沒生效，很可能是撞名的舊定義被載入了，而不是你的檔案寫錯。/doctor（v2.1.205 起）能幫你抓出這種撞名並給建議，卡住先跑一次。版本號變動快，實際指令與行為請以你當下的官方文件為準。🌐社群

它醒來的時候，看得到什麼、看不到什麼

回顧 16.1 的 context 隔離原理，這裡把「子代理啟動當下的 context 裡到底裝了什麼」講得更具體一點 ✅官方：

• 它自己的系統提示（不是完整的 Claude Code 系統提示，是它 frontmatter 底下那段 Markdown）。
• Claude 幫你寫好的委派任務訊息（把你的原始需求轉譯成交給子代理的具體交辦）。
• CLAUDE.md 與 memory 階層——但 16.2 提過，Explore／Plan 這兩個內建子代理為了求快會跳過這一項。
• 主 session 起始時的 git status 快照——同樣 Explore／Plan 會跳過；不是 Git repo，或設定 includeGitInstructions: false 時，其他子代理也不會拿到這項。
• 如果 frontmatter 有寫 skills 欄位，列出的技能全文會一併載入。

反過來，它完全看不到主對話目前為止的完整歷史、你們之前呼叫過哪些工具、讀過哪些檔案——除非你用的是 16.6 提到的 /fork。這正是「context 隔離」名符其實的地方：它是真的從一塊乾淨的地方開始，不是接著主對話的記憶往下想。

跑完之後，逐字稿留在哪、能不能接著問

子代理的完整逐字稿會獨立存放在 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl，不受主對話 compaction（壓縮）影響，重開 Claude Code 後也能透過 resume 同一個主 session 存取到。這份逐字稿依 cleanupPeriodDays（預設 30 天）自動清掉，不會無限累積。✅官方

但有個例外：Explore 和 Plan 是一次性的，不會回傳可用於 resume 的 agent ID。如果你想要「延續剛才那次探索，繼續往下追問」，這兩個內建子代理做不到——得改用 general-purpose 或自己寫的子代理才能被接續。這也是第 10 章那句「一次性、不能之後接著問」背後的技術原因。

# macOS / Linux：直接在啟動指令內嵌整組子代理定義
claude --agents '{"code-reviewer": {"description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer...", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet"}, "debugger": {"description": "Debugging specialist for errors and test failures.", "prompt": "You are an expert debugger..."}}'

# Windows PowerShell 要改用 here-string 包住 JSON，不能直接單引號貼上

16.8　Agent Teams：不只是子代理，是會互相通訊的同儕

到這裡為止講的子代理，都有一個共同點：它們只對主代理回報，彼此之間不講話，像各自向領班交差的工人。2026 年登場的 Agent Teams（代理團隊）打破了這個限制 🧪研究預覽——它讓多個完整的 Claude Code 實例（每個都有自己的 context）組成一個團隊，從一份共享的任務清單裡各自認領工作，而且彼此可以透過mailbox（信箱）直接互通訊息，不必什麼都繞回主代理。

為了防止多個成員同時搶改同一件工作出亂子，它用file-lock（檔案鎖）來避免競爭衝突——一件工作被某個成員拿走，就鎖住，別人不會重複做。這套機制特別適合三類場景：研究與審查、用競爭假設來除錯（16.10）、以及橫跨多層的功能開發。

四個元件：team lead、teammates、task list、mailbox

拆開來看，一個 team 由四塊組成，各自的狀態存在不同地方 ✅官方：

比較新的版本（v2.1.178 起）已經不需要你自己先手動建立、命名一個 team——早期版本的 TeamCreate／TeamDelete 工具已經移除，現在只要一開口叫 Claude spawn 隊員，team 就自動成形。版本號變動快，實際指令請以你當下的官方文件為準。✅官方

畫面怎麼呈現：in-process 還是 split-pane

團隊組起來之後，隊員的畫面要怎麼看，有兩種模式：預設的 in-process——所有隊員擠在同一個終端機裡，用上下鍵選取、Enter 切換查看；以及 split-pane——每個隊員各自佔一個窗格，需要 tmux（終端機多工工具，能在一個視窗裡開多個窗格）或 iTerm2＋it2 CLI 才跑得起來。VS Code 內建終端機、Windows Terminal、Ghostty 都不支援 split-pane——在這些環境硬要求 split-pane，不會默默降級成 in-process，而是直接報缺 tmux／it2 的錯誤（只有設成 auto 才會自動 fallback）。想切換用 --teammate-mode 旗標，或寫進 ~/.claude/settings.json 的 teammateMode 設定。✅官方

16.9　Agent Teams 深水區：繼承規則、任務分工、成本，以及會咬人的坑

摸清楚基本結構後，這節把 Agent Teams 用起來會撞到的細節攤開講——模型怎麼繼承、任務怎麼分配剛剛好、要花多少錢、以及一份過來人踩過的坑清單。全部都還是 🧪 研究預覽等級，斟酌採用。

模型、推理強度、權限模式：誰繼承誰

隊員預設不會繼承隊長當下用的 /model 選擇——想固定隊員該用哪個模型，去 /config 設定 Default teammate model，或選「Default (leader's model)」讓它跟著隊長走。推理強度倒是不用你操心：v2.1.186 起，透過 split-pane（tmux／iTerm2）模式 spawn 的隊員，會自動繼承隊長的 effort 等級（官方 release notes 原句點名的是 tmux/pane 這條路徑，in-process 模式沒有特別著墨，實務上以你當下安裝版本實測為準；回顧第 15 章的 /effort）。權限模式則是在 spawn 當下就定型：所有隊員一開始都固定用隊長當時的權限模式（如果隊長層級設了 bypassPermissions 或 acceptEdits，隊員無法在 spawn 那一刻覆寫它），spawn 之後才能個別再調整某個隊員的權限模式，但沒辦法在一開始就讓每個隊員各自帶不同模式出生。版本號變動快，實際行為請以你當下的官方文件為準。✅官方

先規劃、你核准了才動手：plan approval workflow

你可以要求隊員先進 plan 模式把方案想清楚，等隊長核准這份計畫，它才能動手實作。做法是隊員規劃完會送出一份核准請求給隊長，隊長可以核准、也可以附上理由駁回；駁回後隊員留在 plan 模式修改重送，不會自己硬幹。想要隊員的動作有個把關點、不放任它一想到就動手改檔，這個工作流是最直接的做法。✅官方

成本：比單一 session 貴上不少

官方在 costs 文件裡講得很白：Agent Teams 用的 token 遠多於單一 session；隊員如果跑在 plan 模式，token 消耗大約是一般 session 的 7 倍。這不是嚇你別用，是提醒你別無腦開一整團去做小事——跟 16.3 的縮放規則是同一種紀律，只是換到 Agent Teams 這層更貴的尺度上。官方給的省錢建議很具體：隊員用 Sonnet 而非 Opus、團隊維持小規模、spawn 時給的提示保持精簡、任務做完就讓隊員主動關閉，別放著閒置燒錢。✅官方

不用重寫：既有的子代理定義可以直接當隊員角色

手上已經有寫好的子代理定義（不管放在專案還是個人層級），不用為了 Agent Teams 再寫一份。直接說「Spawn a teammate using the security-reviewer agent type」，Claude 就會沿用那份定義的 tools 與 model，定義本文也會被附加到隊員的系統提示後面。這樣一份角色定義可以同時當被委派的子代理、也當團隊裡的隊員用，不用維護兩份容易漂移不同步的定義。要留意一個例外：定義檔裡的 skills 和 mcpServers 欄位當隊員時不會生效——隊員仍然是照一般 session 的方式，從專案或使用者設定去載入技能與 MCP。✅官方

邊界：官方限制、安全性，加上實戰踩過的坑

先說安全性，這點值得特別強調，因為它跟這整個系統設計的核心精神一致：隊員之間用 SendMessage 互傳訊息時，收訊方會被明確告知「這是來自另一個 Claude session」，不是來自你本人。隊員不能替你核准權限提示，而且一個被拒絕的操作，也不能靠轉發給另一個隊員來繞過檢查——在 auto mode 下，分類器會把「另一個 agent 轉述的核准」當成不可信輸入處理，不會因為換了個信差就放行。換句話說，團隊裡誰都不能假冒你點頭。✅官方

官方另外列出幾條結構性限制：resume／rewind 救不回隊員（in-process 的隊員沒辦法透過 /resume 或 /rewind 復原，session 恢復後隊長可能還以為隊員在，試著傳訊給一個已經不存在的對象）；不支援巢狀團隊（隊員不能自己再 spawn 一個團隊，只有隊長能管理團隊）；一個 session 只能帶一個 team；隊長角色固定，不能被轉移或由隊員取代；in-process 隊員自己的子代理不能背景執行（背景工作理論上要活得比啟動它的 process 久，但 in-process 隊員本身就掛在隊長的 process 底下，撐不住）。✅官方

16.10　對抗式辯論：讓代理互相駁倒，逼出真正的根因

Agent Teams 最漂亮的用法，是拿來除一個棘手的 bug。一般的除錯是「順著一條假設查到底」，但這有個陷阱：人（和代理）都會錨定偏誤，一旦先入為主認定某個原因，後面就會不自覺地只找能佐證它的資料。對抗式辯論（competing-hypotheses，競爭假設）就是用來打破這個盲點的 🧪研究預覽。

做法是：派出大約五個成員，各自抱持一個不同的根因假設，然後明確要求它們互相對話、試著駁倒對方的理論——像科學家在辯論一樣。一個假設如果經得起其他四個的猛烈反駁還站得住，那它是真因的機率，遠高於一條沒人質疑、順順查下來的線。最後存活下來的共識，寫進一份 findings（調查結論）文件。

1. 1
   ✋動手做

   針對同一個 bug，派出約五個各持不同假設的成員

   先開好 Agent Teams（環境變數見 16.8）。給每個成員一個不同的根因方向，例如「我懷疑是快取沒清」「我懷疑是並發競爭」「我懷疑是版本不相容」……讓它們從不同角度切入同一個問題。

2. 2
   ✋動手做

   明確要求它們互相駁倒，而不是各說各話

   關鍵指令是「要彼此辯論、試圖推翻對方的理論」。如果只叫它們各查各的，就退回成普通平行調查、失去對抗的價值。要的是它們真的去攻擊彼此假設的弱點。

3. 3
   ✋動手做

   把存活的共識寫進 findings 文件

   辯論收斂後，讓團隊把「經得起反駁、大家都認同」的結論整理成一份調查結論文件。

   ✅ 預期會看到

   你拿到的不是「第一個聽起來合理的猜測」，而是一個被同儕反覆挑戰過、仍站得住的根因，以及通往它的推理過程。比一條線查到底可靠得多。

16.11　平行 code review：用好幾個獨立鏡頭看同一份 PR

對抗式辯論的近親，是把同一套思路用在程式碼審查上。一個審查者很難同時把安全、效能、測試覆蓋都看得周全——人的注意力會偏向自己最在意的那類問題，漏掉其他面向。解法是給每個面向各配一個成員，同時對同一份 PR 套上不同的鏡頭 🧪研究預覽：一個只盯安全漏洞、一個只看效能、一個只查測試覆蓋夠不夠，最後由主代理把三方意見綜合起來。

這麼做避免了「單一審查者的偏向」，每個面向都有一雙專注的眼睛。而且這些審查角色可以固化成具名的可重用子代理（例如做一個叫 security-reviewer 的子代理），以後每次審查直接叫出來用，不必每次重新交代。這正好呼應 16.6 講的第四種形狀「角色小組」——把它具體落實到 code review 這個常見場景。

把角色定義固化好之後，遇到 Agent Teams 的場景可以直接重用，不用重寫一次。回顧 16.9 提過的重用技巧，一句自然語言就夠：

# 直接重用已經寫好的 security-reviewer 子代理定義，當這次團隊裡的一個隊員
Spawn a teammate using the security-reviewer agent type to audit the auth module.

16.12　三選一：這活該找子代理、Agent Teams，還是背景代理人？

讀到這裡，你已經知道子代理和 Agent Teams 怎麼用。但市面上（甚至官方文件的不同角落）還會出現第三個長得很像的名字：背景代理人（Background Agents，官方頁面代號 agent-view）。第 10 章其實已經帶你用過它的入口——/background、claude agents、/tasks 那組指令。這節把它跟前面兩者放在一起比較，把「這三個東西到底哪裡不一樣」徹底講清楚，因為這是社群文章裡最常被搞混的地方。

背景代理人是什麼：跟子代理、Agent Teams 都不同的第三種機制

背景代理人透過一個本機 supervisor（監督）process 管理，架構上跟前兩者最大的差別有三點 ✅官方：

• 活得比終端機久：終端機視窗關掉、甚至機器休眠之後，它還能繼續跑，不像子代理跟著主 session 生死與共。
• 各自獨立的 git worktree：每個背景代理人自動拿一塊隔離的工作目錄，改檔互不干擾。
• 各自獨立消耗訂閱額度（quota）：這是最容易忽略、也最實際的一點——子代理和 Agent Teams 的隊員，用量都算在同一個 session 底下共用；背景代理人不是，它有自己獨立的額度消耗。開太多背景代理人放著跑，帳單／額度會用得比你想像中快。

第 10 章教過 /background（把目前對話收到背景）和 claude agents（開總覽畫面）這組「從對話裡收起來」的用法。如果你想從一開始就直接在冷的終端機啟動一個背景代理人，不必先進到對話裡再收起來，官方留了對應的指令組：

# 直接起一個新的背景代理人，不用先進對話
claude --bg "investigate the flaky test"

# 開總覽畫面（跟第 10 章教過的 claude agents 是同一個）
claude agents

# 接回某個背景代理人繼續盯著看
claude attach <id>

# 只想看它跑到哪、不想接進去，看 log 就好
claude logs <id>

# 停掉、或讓它帶著現有進度重新啟動
claude stop <id>
claude respawn <id>

整組背景任務功能都不想要，設環境變數 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 可以一次關掉。✅官方

三問句選型框架

名詞多、又都叫「代理」，混淆很正常——社群文章常常各講各的，讀舊文章時要注意作者講的到底是哪一種。用三個問句快速判斷該找誰做 🌐社群：

三套機制先後推出、彼此獨立，不是誰取代誰——子代理最輕、最省，Agent Teams 換取的是同儕協調的能力，背景代理人換取的是「不用你顧著」的持久性。挑最輕的那個夠用就好，不必每次都想著上最重的方案。

這裡的三選一框架，處理的是子代理／Agent Teams／背景代理人這三者之間怎麼選；如果你猶豫的其實是另一個問題——「這件事到底該包成 Skill，還是寫成子代理？」——那不在這三選一的範圍內，第 8 章 8.3 節有專門一段在講怎麼判斷（該節那組判準本身出自官方 sub-agents 文件，這裡只是指路，不重複掛徽章）。

16.13　瀏覽器 QA 派工：從截圖到結構化證據

16.12 幫你分清楚一件事該找子代理、Agent Teams,還是背景代理人。但不管找哪一種手段執行,派工出去之後常常還有一個更根本的問題:代理回報「PASS」,你怎麼知道它是真的驗證過,不是掃一眼就交差?這個問題在瀏覽器視覺 QA——截圖、對比色彩、檢查排版有沒有跑版——特別容易失守,因為「看起來對」很難量化,代理很容易退化成讀幾個 computedStyle 數字就下判斷,或是掃一眼截圖縮圖就打勾。第 22 章會從成本拆分的角度,示範一個 QA 代理群平行測站怎麼分工(跑腿的用 Sonnet、居中彙整的留給 Opus);這節要往下一層,把「怎麼確保派出去的視覺 QA 真的驗證到位」拆成三個可以直接照做的機制,再補上瀏覽器工具怎麼選的實務細節。兩節看的是同一類工作的不同切面,不重複。

先把工具選對:MCP 驅動探索 vs. CLI 跑正式回歸

瀏覽器自動化這塊,目前有兩條路可以走,先分清楚各自適合的場合,免得選錯工具白花錢。MCP 驅動——像 Google 官方維護的 Chrome DevTools MCP(提供截圖、DOM snapshot、console／network 訊息、效能追蹤、Lighthouse 稽核等工具,底層用 Puppeteer 自動等待頁面就緒)✅官方,或 Anthropic 自家的 Claude in Chrome 擴充功能——讓代理即時操作瀏覽器、邊看邊調整,適合探索與除錯這種還在摸清楚問題長什麼樣子的階段。Claude in Chrome 有個值得留意的設計:規劃模式,會先把破壞性動作(送出表單、刪除項目)攤成計畫等你核可,再動手🌐社群——跟 16.9 提過的 Agent Teams plan approval 是同一種「先想清楚、你點頭才動手」的紀律,套用在瀏覽器自動化一樣受用。

CLI 跑正式回歸則是另一條路:同一組檢查要反覆跑(例如每次部署都測一遍),改成 npx playwright test 執行寫死的 .spec.ts。這裡有個容易被忽略的成本陷阱:MCP 驅動的截圖工具會把整張圖轉成文字描述塞進 context,實測一張全頁截圖大約吃掉 23 萬 token,同一份測試改用 MCP 跑比 CLI 直接執行貴了大約 75 倍🌐社群。經驗法則很直接:MCP 拿來探索、除錯、抓一次性的 bug;會反覆跑的正式回歸測試,寫成 .spec.ts 用 CLI 執行,別放任代理每次都用 MCP 重新截一次。

結構化證據契約:有 worst-case gate 的 PASS 條件

光有工具還不夠,真正決定 QA 靠不靠得住的是怎麼定義 PASS。一個容易養成的壞習慣是:代理讀了幾個 computedStyle 數字、算出對比度或座標差在容許範圍內,就直接判 PASS——聽起來很嚴謹,其實只是在推理「應該沒問題」,沒人真的看過那張圖。

比較站得住腳的做法,是把 PASS 的條件寫成一份證據契約:要判一項視覺相關的檢查為 PASS,必須同時具備兩樣東西——① 一張真實 worst-case(最壞情況)輸入的截圖,不是暗色測試圖、不是佔位假資料,是實際會出現的最刁鑽情境(例如最亮的首頁 hero、最長的真實文案);② 一句「真的看過這張圖」的觀察描述,具體講看到了什麼、在哪個位置。純數值指標——computedStyle、對比度數字、座標差——降級成只能佐證,不能單獨構成 PASS。這個順序不能反過來:先有數字、後補一句話搪塞,跟真的沒看過圖沒兩樣。

對抗式盲驗證:第二支獨立 agent 重新驗證

證據契約解決了「有沒有交出證據」,但沒解決另一個問題:第一位驗證者自己也可能有盲點——他覺得自己看過圖、寫了觀察描述,但那份觀察本身可能就是錯的,或者他挑選截圖時無意間避開了真正的問題。要抓這種盲點,得靠第二雙獨立的眼睛。

做法是:第一支 QA 代理完成截圖驗證、判定「有視覺影響的改動、沒發現缺陷」之後,再spawn 第二支獨立代理做盲驗證。關鍵是「盲」:第二支代理只拿到一句話——哪個路徑、worst-case 長什麼樣子——完全不給第一支的判決文字或觀察結論。如果判決文字意外透過對話歷史或交接資料洩漏進第二支的 context,要當成汙染直接忽略,不能拿來當參考。

第二支代理還有三條紀律,少一條都會讓「盲驗證」名不符實。第一,不信任任何交接過來的截圖檔案——檔案可能因為後續改動過期、被裁切挑選過、甚至被替換過,牠必須自己重新導覽到頁面、自己關掉 reduced-motion、自己拍一張全新截圖,存進自己獨立的 run 目錄。第二,用跟第一支不同的檢驗方法——如果第一支讀 computedStyle 數值門檻,第二支就改成直接讀原始像素,不看相鄰列的數值差。兩次用同一種方法檢查,等於只檢查了一次,第二雙眼睛要真的看到不一樣的東西才有意義。第三,判定「沒發現缺陷」之前,先過一輪明確的檢查清單(hero 頂／底接縫、logo 區域、文字疊圖片區域、最亮的顏色過渡帶),不能掃一眼就宣稱通過——預設假設是有缺陷,代理必須主動排除它,而不是被動等缺陷自己跳出來。

還有一條容易被忽略、但很有意思的規則:如果第二支代理截到的圖其實不是真正的 worst-case——例如意外抓到暗色主題或合成的測試資料——這件事本身就要算成一個缺陷回報,而不是默默換一張重截。理由很直白:在簡單的輸入上測試通過毫無意義,連測到了什麼都測錯,比沒測更容易讓人誤判品質。

# .claude/agents/qa-blind-verify.md —— 第二支獨立驗證:不信任交接檔案,自己重拍
---
name: qa-blind-verify
description: Independent adversarial re-verification of a prior visual QA PASS. Use when a visually-impactful change has been marked as having no defects.
tools: Read, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_evaluate
---
你是第二位獨立驗證者,職責是找出第一位驗證者可能漏掉的缺陷,預設假設是「有缺陷」。

- 不信任任何交接過來的截圖檔案:自己重新導覽、關掉 reduced-motion、重新截圖,存到自己的 run 目錄。
- 不使用跟第一位相同的檢驗方法:對方讀 computedStyle 門檻,你就直接讀原始像素。
- 判「沒發現缺陷」之前,先跑過檢查清單:頂／底接縫、logo 區域、文字疊圖區域、最亮的顏色過渡帶。
- 如果你截到的圖不是真正的 worst-case(例如意外抓到暗色或合成測試圖),這本身就是缺陷,要回報。

# 第一支代理判完 PASS 後,只交一句話描述案發現場給第二支,不給判決文字
Spawn an independent qa-blind-verify agent: "重新驗證首頁 hero 區塊、最亮的顏色過渡帶那一段。不要相信任何截圖檔案,自己重新截圖。"

Reward-hacking 的結構化防禦:不是靠寫更多規則

前面兩招——證據契約、盲驗證——回答的是「怎麼確保驗證做得夠周全」。這節退一步問更根本的問題:為什麼代理會傾向少做一點、交差一點?這不是代理不夠聰明,是誘因結構的問題——如果規則允許用最省力的方式技術上過關,代理就會找到那條路。

Anthropic 官方在多代理系統的建置指南裡點出一個常見的失敗模式:過早判定通過——驗證代理常常只跑一兩個測試就宣稱通過✅官方。官方給的解法是要求具體判準、要求正反面測試都要跑、明確要求跑完整套測試,不能抽一兩個就交差。這跟 16.4 提過的專責附來源子代理(CitationAgent)是同一種設計精神的延伸——Anthropic 自家的多代理研究系統不是讓查資料的代理自己順便驗證自己,而是另外設一支獨立的角色專職做這件事✅官方。

這個精神可以歸納成一套實測有效的多代理 QA 設計,拆成三個結構性支點👤達人:

上面這套契約要落地,通常得靠某種強制格式把它釘死,不能只是口頭要求。Claude Agent SDK 的 structured outputs(結構化輸出)機制就是這種釘子:格式不符會先重試,重試仍不符就直接報硬錯誤,而不是靜默退回自由文字讓漏洞有機可乘✅官方。把證據契約的必填欄位(worst-case 截圖路徑、觀察描述、四值判定)寫進這樣的 schema,「沒交證據就不能宣稱 PASS」就從一句提醒,變成技術上做不到的事。

16.14　小結

這一章把「一個 Claude」擴成「一群 Claude」。先建立 orchestrator-worker 的骨架——主代理規劃、子代理在隔離 context 裡平行探索、回傳濃縮摘要，靠的不只是平行省時間，更是隔離換來的判斷品質，但別忘了那份回報也要精簡，不然冗長的回傳會把隔離的好處吃光。接著是三道紀律：子代理數量要跟著任務複雜度縮放（開太多本身就是偷工，複雜任務更該用分層委派而非扁平硬塞）；那個害人的權限陷阱——省略 tools 等於給全部工具，唯讀子代理一定要明寫白名單，精細一點還能用 disallowedTools 和 PreToolUse hook 動手術；以及子代理躲在哪裡的機制細節——同名時誰贏、啟動時看得到什麼、逐字稿能不能接著問。然後我們看了五種可重用的子代理形狀，外加省成本的 /fork，最後走進 2026 的新機制：Agent Teams 讓成員彼此通訊、自領工作，會繼承你的 effort 但不會自動繼承 /model、跑 plan 模式的成本大約是一般 session 的 7 倍，由此長出對抗式辯論與平行 code review 兩種玩法——但它們都還是 🧪 研究預覽，嚐鮮可以、別押身家。最後把子代理、Agent Teams、背景代理人三者放在一起分清楚：份量一個比一個重，挑最輕的夠用就好。一句話帶走：多代理的厲害不在「開得多」，而在「拆得準、權限收得緊、該駁倒的有被駁倒」。視覺與瀏覽器這類特別容易「看起來測過了」的工作,16.13 把它拆成三個機制——盲驗證換一雙眼睛、證據契約卡住沒真的看過的 PASS、用結構而非規則堆去防堵敷衍——原則跟前面幾節一以貫之:不是靠嘴巴講規矩,是靠架構逼出真的做到。下一章我們再往前一步，看 Claude 怎麼自己寫一支程式來指揮上百個分身。

16.15　動手試試

1. 1
   ✋動手做

   建一個「絕對動不了你檔案」的唯讀審查子代理

   照 16.5 的正例，寫一個 frontmatter 含 tools: Read, Grep, Glob 的審查子代理。重點是親手寫上那一行 tools——這是這章最該肌肉記憶起來的安全動作。

   ✅ 預期會看到

   叫它審查時，它只會讀、搜、列檔案並給意見，不會動手改任何東西。試著叫它「順手幫我改掉」，它會因為沒有改檔工具而做不到——這正是你要的安全邊界。

2. 2
   ✋動手做

   拿一個真實問題，練習「投入度縮放」的判斷

   挑一件你最近真的要查的事，先用 16.3 的表自問：這是簡單查詢、直接比較、還是複雜研究？據此決定要派一個、二到四個、還是更多子代理，再交給 Claude 執行。

   ✅ 預期會看到

   你會開始對「這件事值不值得開一群代理」有感覺，而不是反射性地全部展開。判斷得剛好，省下的是實實在在的 token 與時間。

3. 3
   ✋動手做

   （進階、選做）用傳統子代理組一個「三鏡頭」code review

   不必開實驗性的 Agent Teams——就用第 10 章的子代理，各給唯讀工具清單，分別請它們從安全、效能、測試覆蓋三個角度審你的同一段改動，再自己把三份意見彙整起來。體會 16.11「多個獨立鏡頭」的價值。

   ✅ 預期會看到

   三份意見往往各抓到對方漏掉的問題——你會親身感受到「分鏡頭」比「一個人全包」更周全，而且全程用的是穩定功能，沒碰任何會變動的實驗性旗標。

4. 4
   ✋動手做

   （進階、選做）用 @-mention 指名道姓，體會「保證委派」跟「自己判斷」的差別

   挑一個你已經建好的子代理，先用自然語言描述需求讓 Claude 自己判斷要不要委派；接著同一件事改用 @agent-名字 明確指名。比較兩次的差異，感受 16.2 講的「保證委派」是怎麼一回事。

   ✅ 預期會看到

   @-mention 那次一定會派給你指名的那個子代理；自然語言那次則要看它 description 寫得夠不夠白，不一定每次都準——這也是為什麼 16.5 花了篇幅講怎麼把 description 寫好。

5. 5
   ✋動手做

   幫你現有的 QA subagent 補一份證據契約檢查清單

   回頭看你已經在用的視覺 QA 子代理(或照 16.5 剛建的那個),在它的系統提示裡明講 16.13 的 PASS 條件:一張真實 worst-case 截圖＋一句真的看過的觀察描述,缺其中一項就不准判 PASS,改判 FAIL 或 UNVERIFIED。

   ✅ 預期會看到

   它開始會在回報裡老實承認「這項我沒看到、只有數值」，而不是每次都自信滿滿地打 PASS——這正是結構化證據契約在起作用。