08 - Subagents 與平行工作

← 07-Skills與斜線指令 | 00-Index | 下一篇 → 09-Hooks自動化

四種平行方式，先分清楚

方式	是什麼	適合
Subagent	同一個 session 裡的專門助手，有自己的 context window	側邊任務會洗版主對話時
Agent view / background agent	多個獨立 session 平行跑，一個畫面監看	好幾件不相關的工作
Agent team	會互相溝通的多個 session	需要協作的複雜工作
Dynamic workflows	大規模編排 subagent	系統性的大改造

🔴 重要的成本認知：以上四種全部都算 Claude 的額度。要把產出成本移到 ChatGPT Plus，那是 Herdr + Codex 的做法，不是這一章。

Subagent

它解決什麼問題

當一個側邊任務會用大量搜尋結果、log、檔案內容淹沒你的主對話，而那些內容你之後根本不會再看——讓 subagent 在它自己的 context 裡做，只回傳結論。

好處：

保住 context：探索和實作不進主對話
限制權限：可以限定它能用哪些工具
跨專案重用：使用者層級的 subagent
專門化：針對特定領域的 system prompt
控制成本：路由到更快更便宜的模型（如 haiku）

放哪裡

位置	範圍	優先序
`--agents` CLI flag	目前 session	2（高）
`.claude/agents/`	目前專案	3
`~/.claude/agents/`	你所有專案	4
Plugin 的 `agents/`	plugin 啟用處	5（低）

專案 subagent 是從工作目錄往上走掃描，所以在子目錄啟動也會撿到 repo 根目錄的。同名時用離工作目錄最近的。

⚠️ /agents 指令現在不再開互動建立精靈了，跑它只會提示你直接叫 Claude 建，或自己編 .claude/agents/。

Frontmatter 欄位

欄位	必填	說明
`name`	✅	小寫字母加連字號。不能含 `:`（那是 plugin 命名空間用的）
`description`	✅	什麼時候該委派給這個 subagent——Claude 靠這個決定
`tools`	否	能用的工具。省略則繼承全部。要預載 skill 用 `skills` 欄位，不要在這裡列 `Skill`
`disallowedTools`	否	從清單裡移除的工具
`model`	否	`sonnet` / `opus` / `haiku` / `fable` / 完整 ID / `inherit`（預設 `inherit`）
`permissionMode`	否	`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan`
`maxTurns`	否	最多幾輪就停
`skills`	否	啟動時預載進 context 的 skill（注入完整內容，不只描述）
`mcpServers`	否	這個 subagent 可用的 MCP server
`hooks`	否	綁在這個 subagent 的生命週期 hook
`memory`	否	`user` / `project` / `local`——開啟跨 session 學習
`background`	否	`true` = 永遠當背景任務跑。不設的話 Claude 自己決定（v2.1.198 起預設在背景跑）
`effort`	否	思考力度
`isolation`	否	`worktree` = 在暫時的 git worktree 裡跑，拿到 repo 的隔離副本。沒改動的話會自動清掉
`color`	否	在任務清單和 transcript 裡的顏色
`initialPrompt`	否	當它作為主 session agent 時自動送出的第一則訊息

一個實際的例子（給你的 vault）

.claude/agents/inventory.md：

---
name: inventory
description: 盤點某個專科資料夾的所有筆記，產出時效性報告。當使用者要求「盤點」「哪幾篇該更新」「檢查時效」時使用。只讀不改。
tools: Read, Glob, Grep
model: haiku
memory: local
color: cyan
---
 
你是筆記盤點員。**你只讀，不寫任何檔案。**
 
給定一個專科資料夾，掃描所有 `*_overview.md`，產出表格：
 
| 檔案 | updated 年份 | modified 日期 | 內文引用的最新 guideline 年份 | PMID 數量 |
 
規則：
- guideline 年份從「⚡ 資料更新至：」行與 Key References 區抓
- **不要自己判斷哪個 guideline 比較新**——那是主 agent 的工作
- 不確定的欄位填「?」，不要猜
 
只回傳表格和一句話總結。不要貼出筆記內容。

為什麼這樣設計：

model: haiku → 純掃描不需要貴的模型
tools: Read, Glob, Grep → 物理上不可能改到你的筆記
「不要自己判斷哪個 guideline 比較新」→ 對應 CLAUDE.md §0「絕不捏造」，判斷留給有 PubMed MCP 的主 agent

什麼載入 / 什麼不載入

主對話的 auto memory 不會載入 subagent（例外是 fork，它繼承父對話與 system prompt）
subagent 自己的 auto memory（memory 欄位）是獨立的目錄：
- user → ~/.claude/agent-memory/<name>/
- project → .claude/agent-memory/<name>/
- local → .claude/agent-memory-local/<name>/

auto mode 下的 subagent

classifier 在三個點檢查 subagent：

啟動前檢查委派的任務描述（危險的任務在生成時就擋掉）
執行中每個動作都過 classifier，跟主 session 同規則，subagent frontmatter 裡的 permissionMode 會被忽略
結束時審查完整動作歷史；有疑慮會在結果前面加安全警告

Worktree 隔離 ⭐

兩種用法：

主 session 用 worktree 起步：

claude -w feature-auth              # 在 <repo>/.claude/worktrees/feature-auth
claude -w                           # 自動產生名字
claude -w '#123'                    # 從 origin 抓 PR #123 開 worktree
claude -w feature-auth --tmux       # 順便開 tmux session

讓 subagent 在隔離 worktree 裡跑：

isolation: worktree

它會拿到 repo 的隔離副本，預設從你的 default branch 分出來（不是父 session 的 HEAD）。沒改動就自動清掉。

🔴 這對你的 vault 特別重要。 obsidian-git 每 10 分鐘會自己 commit/pull/push main。讓多個 agent 直接在同一個 checkout 上改是自找衝突。 isolation: worktree 是單一 session 內的隔離；跨 session 的隔離用 herdr worktree 或 claude -w。

Background agents 與 agent view

跑多個獨立 session、一個畫面看：

claude agents                    # 開 agent view
claude agents --json             # 列出進行中的 session（給腳本用）
claude agents --json --all       # 含已完成的背景 session
claude --bg "調查那個 flaky test"  # 直接開一個背景 session
claude attach <id>               # 在這個終端接上某個背景 session
claude logs <id>                 # 印出某個背景 session 的近期輸出
claude stop <id>                 # 停掉
claude respawn <id>              # 重啟（對話保留）；--all 重啟全部
claude rm <id>                   # 從清單移除（transcript 還在，可用 --resume）

claude agents 可以用 --cwd <path> 只看某個目錄底下開的 session，也可以用 --permission-mode / --model / --effort / --agent 設定派送出去的 session 的預設值。

在 session 裡：/background [prompt] 把目前 session 轉成背景 agent，/fork [prompt] 把目前對話複製成一個新的背景 session。

💡 /fork 很好用：正在做一件事，想同時試另一個方向，又不想丟掉目前的 context。

背景 subagent 的控制鍵：Ctrl+X Ctrl+K 停掉這個 session 所有背景 subagent（3 秒內按兩次確認）。

該用哪個？決策表

情況	用什麼
搜尋 / 探索會洗版主對話	subagent（`tools` 限制成唯讀）
同一個 repo、彼此獨立的多個修改	subagent + `isolation: worktree`
好幾個不相關的專案要同時推進	background agents + agent view
需要 agent 之間溝通	agent team
大規模、系統性的改造	`/batch` 或 dynamic workflows
想省 Claude 額度、工作可外包	Herdr + Codex

🔗 相關筆記

07-Skills與斜線指令 — 上一步
09-Hooks自動化 — 下一步
05-權限模式與安全 — subagent 的 permissionMode 在 auto mode 下會被忽略
Herdr 08 — 把產出成本移到另一份訂閱
Codex 07 - 實戰工作流範例 — 「平行產出 + 中央驗證」

最後更新：2026-08-04

Andrew的筆記園地

探索

目錄