07 · 派助手去幹活

翔宇第一次用 SubAgents（子代理）的時候，以為重點是“一個 Claude 變三個，速度翻三倍”。真正用久以後才發現，速度只是副作用。真正重要的是：主對話終於不用再吞下那些臨時搜尋、測試日誌和無關檔案了。——翔宇

1. 從一張被弄亂的桌子開始

想象一個很普通的開發場景。

你正在和 Claude Code 討論認證模組。你們已經聊了十幾輪，桌面上擺著這些資訊：

• JWT 登入流程
• middleware/auth.ts 的判斷邏輯
• session 儲存位置
• 剛剛定下來的重構邊界
• 你已經否掉的兩個方案

這張桌子暫時很清楚。

這時你突然想起一件事：

Claude 自己去查。它搜尋 redis、ioredis、cache，開啟十幾個檔案，讀配置、讀服務層、讀測試。最後回答你：

答案是有用的。但代價是什麼？

Redis 搜尋過程中讀過的檔案、grep 結果、配置片段、分析過程，都被塞進了同一個主對話。你本來正在討論認證重構，現在桌子上多了一堆 Redis 資料。下一輪繼續聊認證時，Claude 要在兩堆資料裡判斷“哪些還相關”。

這就是主對話被汙染。

這句話比“並行”更重要。因為即使只派一個子代理，只要它把髒活留在自己的上下文裡，你的主對話就會更乾淨。

2. 子代理到底多了什麼

SubAgent 不是一個更聰明的 Claude，也不是外掛。

它是 Claude Code 臨時派出去的另一個 Agent（智慧代理）。這個代理有自己的上下文視窗、自己的系統提示、自己的工具許可權。它完成任務後，把最終結果帶回主對話。

用剛才的 Redis 例子看，流程變成這樣：

flowchart LR
    Main["主對話<br/>認證重構資料"]
    Need["臨時問題<br/>專案有沒有 Redis？"]
    Agent["SubAgent<br/>獨立上下文"]
    Mess["搜尋結果<br/>檔案片段<br/>日誌輸出"]
    Result["返回摘要<br/>3 處 Redis 用法"]
    Continue["主對話繼續<br/>認證討論不被打散"]

    Main --> Need
    Need --> Agent
    Agent --> Mess
    Mess --> Agent
    Agent --> Result
    Result --> Main
    Main --> Continue

    style Main fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Mess fill:#fef3c7,stroke:#f59e0b
    style Result fill:#f3e8ff,stroke:#a855f7,stroke-width:2px

注意這裡有兩個動作：

1. 展開：子代理在自己的上下文裡讀檔案、跑命令、分析。
2. 壓縮：子代理只把最後的摘要交回主對話。

官方文件對這個設計說得很直白：Subagents 適合處理會讓主對話塞滿搜尋結果、日誌或檔案內容的旁支任務；它們在自己的上下文裡工作，只返回摘要。完整說明見 Create custom subagents。

SubAgent 上下文怎麼"獨立"：派 SubAgent 時 Claude Code 啟動一個新的 Claude 會話——這個新會話有自己的 system prompt（包括它自己的 frontmatter 指令）+ 自己的 conversation history（預設從空開始，僅注入你給它的任務說明）。它不會自動看到主對話之前討論過什麼——這就是"獨立上下文"的工程實現。代價：你要在派任務時顯式說清背景，因為它不知道你之前跟主 Claude 聊過什麼。例外：實驗性的 forked subagent（CLAUDE_CODE_FORK_SUBAGENT=1）會繼承主對話歷史快照——見本篇 §8 details。

3. 並行只是第二層收益

很多人第一次看到 SubAgents，會先想到並行：

一个 Claude 查认证模块
一个 Claude 查数据库模块
一个 Claude 查 API 模块
三个人同时查，肯定更快

這個理解不算錯，但不夠底層。

如果並行是唯一目標，在一個主對話裡同時跑三段搜尋也可以“看起來並行”。問題是三段搜尋都會把結果倒進同一張桌子。速度變快了，桌子也更亂了。

SubAgents 的關鍵不是“同時做”，而是“分開做”。

回到 Redis 例子。如果你只問一句“專案有沒有 Redis”，真正需要的是最後的 3 條結論，不需要看它翻過的每個檔案。那就該派出去。

反過來，如果你正在和 Claude 一起設計認證重構方案，每一步都需要你不斷糾正、追問、改邊界，這種任務放在主對話更合適。因為過程本身就是上下文。

4. 什麼時候該派助手

判斷標準可以很簡單：這個子任務的中間過程，你後面還要不要用？

應該派出去

適合派 SubAgent 的任務通常有三個特徵：

• 輸出過程很長：測試日誌、grep 結果、依賴樹、構建錯誤。
• 任務邊界清楚：查 Redis 用法、審查某個檔案、跑測試並歸納失敗項。
• 主對話只需要結論：有幾處、失敗在哪、建議怎麼改。

Redis 查詢就是典型例子：

任务：查项目有没有 Redis
过程：搜关键字、读配置、读调用链
主对话需要：是否使用、在哪些地方、风险是什么

過程很多，結論很短。適合派出去。

不該派出去

不適合派 SubAgent 的任務也很明顯：

• 任務很小：改一個變數名、解釋一行報錯。
• 需要連續追問：你還沒想清楚目標，邊聊邊改。
• 過程必須留在主線：架構決策、需求澄清、和使用者一起取捨。
• 子任務之間要互相溝通：前端、後端、測試需要持續對齊。

最後一類就是下一篇 Agent Teams（代理團隊）的主題。SubAgents 只向主對話彙報，它們之間不會像團隊成員那樣互相發訊息、共享任務列表。

flowchart TB
    Start["有一個旁支任務"]
    Small{"一步就能完成？"}
    Interactive{"需要頻繁來回確認？"}
    Noisy{"過程會產生很多檔案/日誌/搜尋結果？"}
    Summary{"主對話只需要摘要？"}
    Team{"子任務之間需要互相溝通？"}
    Main["留在主對話"]
    Sub["派 SubAgent"]
    Teams["考慮 Agent Teams"]

    Start --> Small
    Small -->|是| Main
    Small -->|否| Interactive
    Interactive -->|是| Main
    Interactive -->|否| Team
    Team -->|是| Teams
    Team -->|否| Noisy
    Noisy -->|否| Main
    Noisy -->|是| Summary
    Summary -->|是| Sub
    Summary -->|否| Main

    style Sub fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Main fill:#dbeafe,stroke:#3b82f6
    style Teams fill:#f3e8ff,stroke:#a855f7,stroke-width:2px
    style Small fill:#fef3c7,stroke:#f59e0b
    style Team fill:#fef3c7,stroke:#f59e0b

5. 內建三種工位

Claude Code 自帶幾類內建 SubAgents。官方文件列出的核心內建型別是 Explore、Plan 和 general-purpose。它們不是“智商等級”，而是不同工位。

官方說明裡，Explore 是 fast、read-only，適合 codebase exploration；Plan 用在 plan mode 裡做研究；general-purpose 用於需要探索和行動的複雜多步任務。見 Built-in subagents。

為什麼是這三類不是別的：三類對應三種"派任務"模式——

• Explore（Haiku 只讀）：成本最低、速度最快，適合純查詢（"專案裡有幾處用了 Redis"）。用 Sonnet/Opus 跑這種純搜尋是殺雞用牛刀。
• Plan（繼承模型 + 只讀）：你要它"先調研再給方案"——讀程式碼不動手，避免它在調研中途擅自改檔案。
• general-purpose（繼承模型 + 全工具）：你要它"調研完順手把簡單的修一下"——能寫、能跑命令。

三類覆蓋"快查 / 調研 / 調研+執行"三個常見場景。Anthropic 沒單獨做"只跑命令"或"只寫檔案"的 SubAgent——因為這些場景用主對話或 Hook 更合適，單開 SubAgent 反而把簡單任務搞複雜。

這三個名字不用硬背。按中文直覺記就行：

• Explore：偵察員，只看不動手。
• Plan：參謀，先調研再給計劃。
• general-purpose：執行員，能讀、能寫、能跑命令。

6. 怎麼點名派誰

SubAgent 可以自動觸發，也可以你手動點名。Claude 會根據你的請求、當前上下文和子代理的 description 判斷是否委派。比如你說：

查一下项目里 Redis 相关代码都在哪里，只返回文件和用途。

這類請求邊界清楚、偏搜尋、只要摘要，Claude 就可能自動派 Explore。

如果你自定義了一個 security-reviewer，description 要寫清觸發場景：

description: Reviews authentication, authorization, token handling, and input validation for security issues. Use proactively after auth-related code changes.

當你說“審查一下認證相關改動有沒有安全問題”，Claude 就更容易匹配上。

手動指定有三種層級：

官方還支援在選擇器裡輸入：

@"code-reviewer (agent)" 看一下这次认证相关的改动

如果要讓專案預設用某個 agent，可以在 .claude/settings.json 寫：

{
  "agent": "code-reviewer"
}

7. 自定義一個子代理

內建型別夠用時，不需要急著自定義。

但如果你反覆派同一種角色，比如“認證安全審查員”，每次都要說同一套檢查規則，那就可以寫成自定義 SubAgent。

專案級檔案放在：

最小版本可以這樣寫：

---
name: auth-reviewer
description: Reviews authentication and authorization code for security issues. Use when code changes touch login, sessions, JWT, permissions, or user identity.
tools: Read, Grep, Glob
model: sonnet
---

You are an authentication security reviewer.

Review only the authentication and authorization surface:

1. Token creation, validation, expiration, and storage.
2. Session lifecycle and logout behavior.
3. Permission checks and role boundaries.
4. Input validation for login, registration, and password reset.

Return:

- High-risk findings first.
- File paths and exact symbols.
- Why the issue matters.
- A minimal fix suggestion.
- "No high-risk auth issues found" if nothing serious is found.

這個檔案分兩層：

• frontmatter（檔案頭後設資料）：告訴 Claude 什麼時候用、能用什麼工具、用什麼模型。
• 正文：告訴這個子代理按什麼角色、流程和輸出格式工作。

它和 Skill 很像，但目標不同。

第 6 篇講過，Skill 是“遇到某類任務時怎麼做”的說明書。SubAgent 更像“找一個按這套說明做事的人”。

8. 許可權、資源和記憶

SubAgent 真正變好用，靠的不是“寫一個很響亮的角色名”，而是把邊界寫清楚：它放在哪裡、能用什麼工具、要不要帶額外資源。

放在哪裡

新手最常用兩個位置：專案級 .claude/agents/，適合隨儲存庫共享；個人級 ~/.claude/agents/，適合自己跨專案複用。更高階的來源還包括管理設定、--agents 當前會話和 plugin。多個位置出現同名 agent 時，高優先順序會覆蓋低優先順序。

限制它能做什麼

可以用 tools 做 allowlist（允許列表）：

tools: Read, Grep, Glob

這表示它只能讀和搜，不能寫檔案。

也可以用 disallowedTools 做 denylist（拒絕列表）：

disallowedTools: Write, Edit

這表示它繼承主會話大部分工具，但明確不能寫和改。

如果你給“程式碼審查員”全部寫許可權，它可能在審查時順手修改檔案。那不是審查員，是執行員。不是不能這樣做，而是你要有意識。

常見角色的許可權邊界可以這樣記：

• 程式碼搜尋員：Read, Grep, Glob。只需要找資訊。
• 安全審查員：Read, Grep, Glob, Bash。可能需要跑只讀檢查。
• 測試執行員：Read, Grep, Glob, Bash。需要跑測試，但不一定改程式碼。
• 修復執行員：讀寫 + Bash。需要真正落地改動。

Claude Code 還支援 permissionMode、subagent 級 hooks、MCP（Model Context Protocol，模型上下文協議）伺服器作用域、預載入 Skills、持久 memory（記憶）等配置。官方完整欄位見 Supported frontmatter fields。

給它帶資源

SubAgent 不只是“另一段 prompt”。它可以帶自己的資源。

你可以在 subagent frontmatter 裡寫：

skills:
  - api-conventions
  - error-handling-patterns

官方說明裡強調：這些 Skill 的完整內容會在子代理啟動時注入上下文，不只是放在旁邊等它呼叫。子代理不會自動繼承父會話裡的 Skills，想要就要顯式列出來。

如果某個 agent 才需要資料庫只讀工具或瀏覽器測試工具，可以把 MCP server 配在這個 subagent 裡，讓工具只在它啟動時可用。這樣主對話不用背工具描述，許可權也更窄。

SubAgent 還能配置 memory：

memory: project

官方給出三個作用域：user 跨所有專案，project 專案內共享，local 專案本地私有。比如 auth-reviewer 可以逐漸記住這個專案的認證路徑、常見安全問題、歷史決策。以後再審查時，它不必每次從零開始。

9. 編排模式和團隊邊界

真正用起來後，SubAgents 常見有三種編排模式。

模式一：隔離噪音

這是最常用的。

让一个子代理跑完测试套件，只回报失败用例的文件路径和错误信息。

測試可能輸出幾千行日誌。主對話不需要每一行，只需要失敗項、錯誤資訊、建議下一步。

模式二：並行研究

當幾個方向互不依賴，可以同時派出去。

分别派子代理并行调研 authentication、database、API 三个模块，最后汇总成一份架构摘要。

這比序列快，也避免三個模組的搜尋過程混在主上下文裡。

模式三：串聯交接

一個子代理先做審查，另一個再修復。

先用 code-reviewer 子代理找出认证相关的高风险改动，再让一个 general-purpose 子代理只修复已确认的问题。

這裡要注意：串聯會產生資訊損耗。第一個子代理給第二個的是摘要，不是完整過程。所以摘要必須寫清檔案、符號、風險和建議。

新手最常見的兩類誤用：

1. 把 SubAgent 當並行加速器：所有任務都派——結果 5 個子代理同時跑同一個儲存庫，互相不知道對方在做什麼，可能重複讀同一批檔案、給出衝突的建議、合起來反而更亂。SubAgent 的核心是上下文隔離不是並行加速——能在主對話討論的就不該派出去。
2. 派出去後忘了"輸出契約"：讓 general-purpose 子代理"看看 auth 模組"——它返回一篇 800 字散文式分析，主對話還得花一輪把散文壓成可執行的 todo。修復方式：派任務時顯式說"返回格式：① 檔案路徑 ② 風險描述 ③ 建議改法，每條 ≤30 字"。把"輸出格式"當 §4 件套的"驗收"來對待。

和 Agent Teams 的邊界

SubAgents 不是 Agent Teams。

SubAgents 是主從結構：

主对话 -> 子代理 A -> 回摘要
主对话 -> 子代理 B -> 回摘要
主对话负责汇总

子代理之間不互相聊天，也不共享任務列表。它們各做各的，然後向主對話彙報。

Agent Teams 是協作結構。官方文件說，Agent Teams 有 shared tasks、inter-agent messaging 和 centralized management。也就是說：團隊成員能互相發訊息，有共享任務列表，有 lead 負責協調。見 Run agent teams。

邊界可以這樣判斷：

• 查三個互不依賴的模組：用 SubAgents 合適，Agent Teams 太重。
• 跑測試並只看失敗摘要：用 SubAgents 合適，Agent Teams 太重。
• 前端、後端、測試要互相對齊：SubAgents 不夠，Agent Teams 更合適。
• 多個假設要互相反駁：SubAgents 勉強，Agent Teams 更合適。
• 成本敏感：SubAgents 通常更低，Agent Teams 通常更高。

回到 Redis 例子：只是查 Redis 用法，不需要團隊。SubAgent 就夠。

但如果你要讓一個 agent 改後端 Redis session，另一個 agent 改前端登入態，第三個 agent 寫整合測試，而且它們需要互相確認欄位、狀態和進度，那就開始接近 Agent Teams。

10. 本章自檢

試著用自己的話回答這 3 個問題：

1. 有人說"SubAgents 的核心價值是並行加速"。這個說法漏掉了哪個更底層的價值？對應 §1-§3。
2. 為什麼 Redis 查詢這種任務適合派 SubAgent？請用"過程"和"結論"的區別解釋。對應 §4。
3. 動手題 ⭐：列出你最近一次 Claude Code 會話裡"中途讓 Claude 查一下 X" 的 3 個時刻（比如查依賴、查介面、查測試覆蓋）。每個判斷：當時該派 Explore 還是留在主對話？派出去能省多少主對話上下文？這一題做完你會發現日常有 1/3 的"中途查一下"應該派 SubAgent，但你之前都沒派。對應 §5。

官方資料

• Create custom subagents

接下來去哪

如果只記一句：SubAgent 不是為了顯得多人協作，而是為了讓主對話少吞不必要的過程。