保持 Claude Code 上下文純淨：子代理 (Subagents) 的實戰指南 (Keep your Claude Code context clean)

原始來源與檔名：20260512_2026-04-28T092649+0800-Keep your Claude Code context clean with Subagents.md

來源：[[@dani_avila7]] / X (Twitter) — 2026-04-27 原始檔名：2026-04-28T092649+0800-Keep your Claude Code context clean with Subagents.md

NAPKIN | 餐巾紙

餐巾紙公式

Messy Context = Main Agent + (ls + grep + find + cd) * 50 -> Context Bloat & Summary Loss. Clean Context = Main Agent -> Calls Subagent -> Subagent runs isolated tools -> Returns 3-line Summary to Main Context. Context Forking = CLAUDE_CODE_FORK_SUBAGENT=1 (Child inherits parent’s context cache, but tools remain isolated).

當你在 Claude Code 中進行長時間編程時，無數次的 grep 和 ls 查詢會迅速塞滿上下文視窗（Context Window），導致重要資訊在系統自動壓縮時遺失。解法是使用「Subagents (子代理)」。讓子代理在獨立的視窗中去執行那些髒活累活（檢索、掃描），然後只把最終的結論回傳給主代理。這樣既保持了主對話的乾淨，又能透過 Fork 機制共享提示詞緩存 (Prompt Cache) 節省成本。

一句話

這是一篇極具實操性的 Claude Code 優化指南。作者指出，單一上下文視窗會被大量的終端機指令工具輸出所污染。透過在 .claude/agents/ 目錄下建立 Markdown 格式的子代理定義，你可以將「探索 (Explore)」或「規劃 (Plan)」等複雜任務外包。子代理在隔離環境中運行工具，只回傳精煉摘要。更進階的玩法是開啟 CLAUDE_CODE_FORK_SUBAGENT=1，讓子代理繼承主代理的上下文記憶，實現高效且乾淨的平行任務處理。

餐巾紙草圖

[ Context Management with Subagents ]

Without Subagent (Bloated):
User -> Main Agent -> [ls] -> [grep] -> [find] -> [grep again] -> 80K tokens of noise -> Answer.

With Subagent (Clean):
User -> Main Agent -> [Spawns Subagent "Explorer"]
                          |-> [ls]
                          |-> [grep] -> 80K tokens processed in isolation
                          |-> [find]
                   <- Returns 3-line Summary
Main Agent Context: Clean, contains only the User request and the 3-line Summary.

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

• 痛點: 長時間的 Claude Code 會話會被工具輸出（grep, ls 等）塞滿。當觸發 Context Compaction（上下文壓縮）時，這些噪音會導致關鍵細節丟失。
• 解法 (Subagents): 一個具有獨立系統提示詞、工具權限和上下文視窗的專用助手。主代理呼叫它，它在隔離環境幹活，只回傳結果摘要。
• 如何建立:
  • 在 .claude/agents/ (專案級) 或 ~/.claude/agents/ (全域) 中建立帶有 YAML frontmatter 的 Markdown 檔案（定義 name, description, tools）。
• 內建子代理:
  • Explore: 不污染主上下文的前提下搜尋代碼庫。
  • Plan: 閱讀檔案、理解架構並產出實作步驟。
• 進階技巧 (Forking):
  • 預設下子代理是「空白上下文」。如果主代理已經累積了對專案的深度理解，可以設定環境變數 CLAUDE_CODE_FORK_SUBAGENT=1 或使用 /fork 指令。
  • Fork 後，子代理繼承父代理當下的完整記憶，且共用 Prompt Cache（輸入成本降 10 倍），但其後續的工具呼叫依然隔離不污染父代理。
• 監控工具: 作者提供了一個實用 Hook context-timeline，可即時視覺化監控主代理與子代理的上下文運作狀態。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

1. 上下文壓縮的代價: LLM 雖然有巨大的 Context Window，但「大海撈針」效應明顯。當 80K tokens 全是 grep 的日誌時，LLM 提煉出來的摘要會非常扁平，丟失精確性。物理隔離是唯一解。
2. Map-Reduce 模式的 Agent 實踐: 主代理負責高層邏輯（Map），子代理負責具體的高密度 I/O 任務（Reduce）。這符合傳統軟體工程中的職責分離原則 (Separation of Concerns)。
3. 經濟學與效能考量: Fork 機制不僅解決了「子代理重頭學起」的痛點，更巧妙利用了 Anthropic 的 Prompt Caching 機制。繼承上下文意味著重複的前綴可以直接命中快取，大幅降低 API 成本與延遲。

關鍵證據

• 作者提供的對比案例：不用子代理時，對話框裡塞滿了 50 個工具呼叫；使用 Plan 子代理後，主對話框只剩下 3 行摘要答案。視覺化監控工具 (context-timeline) 也直觀證實了記憶體隔離的運作。

邊界條件

• Fork 機制會將父代理的完整上下文複製給子代理，如果父代理本身就已經包含了大量不相關的雜訊，那麼 Fork 出來的子代理依然要承受這些雜訊的計算成本。因此，平時保持父代理的乾淨依然是首要任務。

ROUND 3: SOUL | 靈魂提取

“還能怎么用”

• 知識連結: 完美實作了《Context Management in Agent Harnesses》中提到的「Subagent Isolation (子代理隔離)」模式，也是《Anatomy of Agent SKILLS》中解決 Context Bloat（上下文膨脹）的具體工程手段。
• 深層洞見: “Thirty minutes in, you have 80k tokens of noise you’ll never read.” 這是所有 AI 開發者最深刻的痛。不要讓 AI 代理在你的主臥室裡做木工，把它們送到車庫（Subagent）去，完工後把成品拿進來就好。
• 行動呼籲:
  1. 立刻在你的 Terminal 中匯出環境變數：export CLAUDE_CODE_FORK_SUBAGENT=1。
  2. 建立一個專門用於「Code Review」的 Subagent 放在 .claude/agents/ 中，賦予它 Read 和 Grep 權限。
  3. 下次要重構代碼前，先請主代理呼叫 Explore，你會發現世界變得異常清爽。