子代理與上下文隔離

你將學到什麼

當 Claude Code 遇到複雜子任務 — 例如探索程式碼庫或研究 API — 它不一定在主對話中處理。相反，它可以產生一個子代理：一個擁有自己全新上下文視窗的子代理。

完成後，你將了解：

• 為什麼上下文隔離很重要
• 子代理如何被產生和管理
• 父子通訊模式
• 何時使用子代理 vs. 直接執行

問題是什麼

每個 token 都很重要。上下文視窗（AI 一次可以處理的文字總量）是有限的。當 Claude Code 讀取大型檔案、執行複雜搜尋或探索多個目錄時，所有這些輸出都消耗上下文。

問題：研究工作會污染工作上下文。 如果 Claude Code 讀取 50 個檔案來找到正確的那個，那 49 個不相關的檔案內容仍然在上下文視窗中，使後續工作效果降低。

如何運作

子代理模式

┌─────────────────────────────────────────┐
│           父代理                         │
│                                          │
│  訊息: [使用者提示, ...]                  │
│                                          │
│  "我需要找到 auth 實作在哪裡。            │
│   讓我產生一個探索代理。"                 │
│       │                                  │
│       │ 產生                             │
│       ▼                                  │
│  ┌──────────────────────────────┐        │
│  │      子代理                   │       │
│  │  訊息: [僅任務提示]           │       │
│  │                               │       │
│  │  • 讀取檔案 A（不相關）       │       │
│  │  • 讀取檔案 B（不相關）       │       │
│  │  • 讀取檔案 C（找到了！）     │       │
│  │                               │       │
│  │  返回: "Auth 在                │       │
│  │  src/middleware/auth.ts，     │       │
│  │  使用 JWT 和刷新 token..."    │       │
│  └──────────────┬───────────────┘        │
│                 │                         │
│                 │ 結果（僅摘要）           │
│                 ▼                         │
│  父代理收到：簡潔摘要                     │
│  （不是子代理讀取的所有檔案）              │
│                                          │
└──────────────────────────────────────────┘

關鍵洞見：只有結果流回，而非完整的探索歷史。父代理的上下文保持乾淨。

子代理一開始有什麼

不是 fork 的子代理，一開始只有：

• 自己的系統提示：來自其定義的提示加上環境資訊，而不是 Claude Code 的系統提示
• 任務訊息：Claude 交辦工作時寫給它的委派內容
• 你的 CLAUDE.md 檔案與 git status 快照：內建的 Explore 與 Plan 代理例外，兩者都會略過，以保持快速、低成本

它看不到你的對話歷史，也看不到 Claude 已經讀過的檔案，所以它需要的一切都必須寫在任務提示裡。

Fork 是例外。 Fork 會繼承完整的對話、系統提示、工具與模型，因此不必重新說明背景。它自己的工具呼叫仍然不會進入你的上下文，只有最終結果會回來。Fork 模式預設開啟（互動式終端機自 v2.1.232 起、所有介面自 v2.1.302 起），所以 Claude 可以自行啟動 fork，你也可以用 /subtask <task> 自己啟動。設定 CLAUDE_CODE_FORK_SUBAGENT=0 可關閉 fork 模式。

子代理如何被產生

在 Claude Code 中，子代理透過 Agent 工具產生：

{
  "type": "tool_use",
  "name": "Agent",
  "input": {
    "description": "Explore auth implementation",
    "prompt": "Find where authentication is implemented in this codebase. Look for middleware, route guards, and token management. Return a concise summary.",
    "subagent_type": "Explore",
    "model": "haiku"
  }
}

主要參數：

• prompt：交給子代理的任務
• subagent_type：特化的行為（Explore、Plan、general-purpose 等）
• model：簡單任務可以使用更便宜、更快的模型

Claude 從主對話產生的子代理預設在背景啟動，因此你可以在它們執行時繼續工作；/tasks 會列出它們。

上下文視窗比較

沒有子代理：

父級上下文: [使用者提示] + [50 個檔案讀取] + [實際工作]
             └── 上下文視窗幾乎耗盡 ──┘

有子代理：

父級上下文: [使用者提示] + [代理結果: 200 字] + [實際工作]
             └── 上下文視窗大部分可用 ──┘

子級上下文: [任務提示] + [50 個檔案讀取] + [摘要]
             └── 獨立上下文，完成後丟棄 ──┘

平行子代理

多個子代理可以同時執行：

[
  {
    "type": "tool_use",
    "name": "Agent",
    "input": {
      "description": "Research database schema",
      "prompt": "Find and summarize the database schema..."
    }
  },
  {
    "type": "tool_use",
    "name": "Agent",
    "input": {
      "description": "Research API routes",
      "prompt": "List all API routes and their handlers..."
    }
  }
]

兩個代理平行執行，各自在獨立的上下文中運作。

關鍵洞見

子代理不只是關於平行處理 — 它們是關於上下文管理。 AI 編程會話中最珍貴的資源是上下文視窗空間。上下文中每個不必要的 token 都會降低後續工作的品質。

把它想像成真實團隊中的委派：

• 你（父代理）專注於大局
• 團隊成員（子代理）做研究並回報
• 你只需要知道結論，而不是他們採取的每一步

這就是為什麼有經驗的使用者會把冗長、可獨立完成的工作，例如執行測試、翻查日誌、大範圍搜尋，交給子代理：主要不是為了速度，而是為了讓主對話保持乾淨、專注。不過委派並非沒有成本。每個子代理都會花費自己的 token，大量詳細結果累積起來仍會佔用你的上下文。需要反覆來回調整、各階段共用大量上下文，或只是快速的小修改時，請留在主對話中處理。

實作範例

以下是設計有效子代理提示的方法：

# 不好：模糊，回傳太多
"看一下這個程式碼庫"

# 好：具體，要求結構化輸出
"找出所有處理使用者輸入表單的 React 元件。
每個元件請回報：
1. 檔案路徑
2. 它收集哪些資料
3. 它如何驗證輸入
以條列清單回傳。略過與使用者資料無關的元件。"

提示應該要：

• 具體說明要找什麼
• 結構化說明要回傳什麼
• 有邊界，避免無止境的探索

子代理的模型選擇

為任務選擇合適的模型：

Haiku（快速，便宜）：
  → 簡單搜尋、檔案探索、列舉任務
  → "找出所有符合 *.test.ts 的檔案"

Sonnet（平衡）：
  → 程式碼分析、重構計劃、中等複雜度
  → "分析這個模組的錯誤處理模式"

Opus（強大）：
  → 複雜推理、深度分析、關鍵任務
  → "追查這個間歇性測試失敗的根本原因"

Fable（頂級）：
  → 最需要判斷力的工作：架構決策、對抗式
    驗證、最終綜合
  → "為資料庫 schema 設計遷移策略"

Agent 工具的 model 參數可接受 sonnet | opus | haiku | fable。在 Anthropic API 上，這些別名目前分別對應 Sonnet 5.5、Opus 5.5、Haiku 5.5 與 Fable 5.1；其他供應商可能對應到較早的版本。子代理定義中的 model 欄位也接受完整模型 ID 或 inherit。

前後對比

沒有子代理	有子代理
所有工作在一個上下文中	研究在子級，決策在父級
上下文很快填滿	上下文保持乾淨
順序探索	可以平行探索
一個模型處理所有	每個任務用合適的模型
完整歷史都可見	只回傳摘要

下一堂課

第 5 堂課涵蓋 Skills 與知識載入 — Claude Code 的雙層注入系統如何預先載入 skill 名稱，但延遲載入完整定義直到需要時，保持系統提示精簡。