---
title: "08 - Subagents 與平行工作"
type: note
specialty: Programming
tags: [claude-code-cli從0開始使用教學, 08-subagents, parallel, worktree]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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，那是 [[Programming/Herdr/Herdr從0開始使用教學/08-Claude當大腦-Codex當雙手|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`：

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

---

## Worktree 隔離 ⭐

兩種用法：

**主 session 用 worktree 起步**：
```bash
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 裡跑**：
```yaml
isolation: worktree
```
它會拿到 repo 的隔離副本，**預設從你的 default branch 分出來**（不是父 session 的 `HEAD`）。沒改動就自動清掉。

> 🔴 **這對你的 vault 特別重要。** obsidian-git 每 10 分鐘會自己 commit/pull/push main。讓多個 agent 直接在同一個 checkout 上改是自找衝突。
> `isolation: worktree` 是**單一 session 內**的隔離；跨 session 的隔離用 [[Programming/Herdr/Herdr從0開始使用教學/10-實戰-Obsidian醫學筆記庫|herdr worktree]] 或 `claude -w`。

---

## Background agents 與 agent view

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

```bash
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 額度、工作可外包** | **[[Programming/Herdr/Herdr從0開始使用教學/08-Claude當大腦-Codex當雙手\|Herdr + Codex]]** |

---

## 🔗 相關筆記

- [[07-Skills與斜線指令]] — 上一步
- [[09-Hooks自動化]] — 下一步
- [[05-權限模式與安全]] — subagent 的 `permissionMode` 在 auto mode 下會被忽略
- [[Programming/Herdr/Herdr從0開始使用教學/08-Claude當大腦-Codex當雙手|Herdr 08]] — 把產出成本移到另一份訂閱
- [[Programming/Codex/Codex從0開始使用教學/07-實戰工作流範例|Codex 07 - 實戰工作流範例]] — 「平行產出 + 中央驗證」

---

*最後更新：2026-08-04*