Logo
Published on

Claude Code Sub-agents 使用最佳實踐：20 小時測試後的經驗分享

前言

我發現有蠻多人對於 Claude Code 的 sub-agent 有一些錯誤的理解，剛好看到這部影片，它把相關的運作原理說明的還蠻清楚的，有在用 Claude Code 的，可以看一下，我覺得不一定要跟作者用一樣的方式來實作，不過，至少要了解 sub-agent 的運作原理，才能夠正確地使用它

影片一開頭就表示，Claude Code 的 sub-agent 功能經常被誤解和誤用，導致許多開發者體驗到性能下降和效率降低，作者將深入探討 sub-agent 的正確使用方式，分享經過 20 多小時測試後得出的最佳實踐

Sub-agent 功能的設計初衷

解決上下文視窗限制

Claude Code 引入 sub-agent 的主要目的是優化大型語言模型的上下文視窗（context window）限制與高代幣（token）消耗問題。在 sub-agent 功能推出之前，主 agent 必須自行處理所有任務，包括

  • 閱讀檔案
  • 列出檔案
  • 編輯檔案
  • 搜尋程式碼庫

這些操作會將整個檔案內容納入對話歷史，極度消耗代幣，並很快觸發「壓縮對話」（compact conversation）指令，導致模型失去上下文，性能急劇下降

上下文工程與優化

Sub-agent 的核心目的在於上下文工程（context engineering）與上下文優化（context optimization）。透過任務工具（task tool），主 agent 可以將任務指派給另一個 sub-agent，而 sub-agent

  • 擁有與主 agent 相同的工具集
  • 可以執行掃描程式碼庫、理解相關檔案等任務
  • 工作過程中產生的所有中間步驟都不會計入主 agent 的對話歷史
  • 只會向主 agent 提供簡要研究報告或總結

原本會消耗大量代幣的檔案讀取與搜尋操作，就能以數百個代幣的總結形式呈現，極大優化了上下文管理

常見的誤用與問題

直接實作的陷阱

許多用戶（包括影片作者初期）在使用 sub-agent 時常遇到負面體驗：反應緩慢、消耗更多代幣，且感覺並未帶來更好的結果。這通常源於對 sub-agent 用途的誤解

最大的誤用是嘗試讓 sub-agent 直接進行實際的實作（implementation）。例如，設想的「前端開發 agent」和「後端開發 agent」各自專精於特定實作，主 agent 僅負責協調和任務委派。但這種模式會引發以下問題

上下文受限問題

每個 sub-agent 的任務都是一個「獨立會話」

  • 前端開發 agent 無法得知上次會話的內容
  • 無法了解後端開發 agent 的進度
  • 當需要修復錯誤時，sub-agent 缺乏必要的全面上下文

主 agent 資訊不足

主 agent 僅能看到

  • 任務被指派給 sub-agent
  • Sub-agent 完成任務的回報

但無法得知

  • Sub-agent 執行了哪些具體操作
  • 建立了哪些檔案
  • 填寫了哪些內容

這使得主 agent 在除錯時，因缺乏詳細資訊而難以有效解決問題

最佳實踐：研究員與規劃者角色

核心理念

Claude Code 團隊的關鍵工程師 Alan Wolf 證實：Sub-agent 的最佳作用是尋找資訊，並將少量總結回傳給主對話線程

基於此洞察，應該將每個 sub-agent 視為研究員（researcher）或規劃者（planner）

實踐方式

1. 建立專業 sub-agent

為不同的服務建立專門的 sub-agent

  • Vercel
  • AI SDK
  • Supabase
  • Tailwind
  • Shadcn
  • Stripe

這些 sub-agent 載入了其領域的最新文件、最佳實踐和設計原則

2. 規劃而非實作

專業 sub-agent 的任務是分析現有程式碼庫，並基於其專業知識提出實作計畫，而非直接執行實作

3. 檔案系統作為上下文管理系統

借鑑 Manus 團隊的上下文工程經驗

  • 不將工具的執行結果直接儲存在對話歷史中
  • 儲存到本機檔案（例如 .md 檔案）
  • 在 cloud 資料夾下，建立一個 task 資料夾
  • 用於存放每個功能的上下文資訊

工作流程

主 agent 工作流程

  1. 建立包含專案資訊的上下文檔案（如 context_session_X.md）
  2. 委派任務給相關的專業 sub-agent
  3. 讀取 sub-agent 建立的計畫檔案
  4. 基於計畫執行實際實作

Sub-agent 工作流程

  1. 開始工作前，先讀取上下文檔案，了解整體專案計畫和當前進度
  2. 執行研究和規劃工作
  3. 將詳細的研究報告或實作計畫儲存為獨立的 Markdown 檔案
  4. 更新上下文檔案

透過這種方式，主 agent 始終掌握著全面的專案上下文，而 sub-agent 則專注於高效地進行資訊檢索與計畫制定

建立 Sub-agent 的實用技巧

系統提示詞設定

  • 將大量重要的文件內容直接包含在系統提示詞中
  • 確保 sub-agent 遵循最新的最佳實踐
  • 提供專用的工具（MCP 工具）以檢索重要上下文

明確目標設定

為每個 sub-agent 設定清晰的目標

  • 「設計、提出詳細的實作計畫，並且絕不執行實際的實作」
  • 指令 sub-agent 完成後，將設計檔案儲存到指定路徑

輸出格式規範

明確規範 sub-agent 最終輸出訊息的格式

  • 例如：「我已經建立了一個計畫檔，請在繼續之前先閱讀它」
  • 這些訊息會回傳給主 agent，指示其參考相關檔案

行為規則制定

  • 指令 sub-agent 在開始工作前，必須先讀取上下文檔案
  • 指令 sub-agent 完成工作後，必須更新上下文檔案
  • 重申 sub-agent 不應執行實際實作
  • 避免 sub-agent 呼叫自身（Cloud MCP Client），以避免混淆

實例：打造 ChatGPT 複製品

前端 UI 構建流程

  1. 主 agent 建立專案上下文檔案 context_session_1.md
  2. 任務委派給 Shadcn UI 專家 agent
  3. Shadcn agent 先讀取上下文檔案，然後利用專用的 MCP 工具檢索組件資訊和範例程式碼
  4. Shadcn agent 完成後，建立包含 UI 設計、整體佈局和組件使用計畫的詳細文件，並更新上下文檔案
  5. 主 agent 讀取此計畫，並基於此執行實際的 UI 實作

Vercel AI SDK 整合流程

  1. 主 agent 委派任務給 Vercel AI SDK 實作規劃器 agent
  2. Vercel agent 先讀取上下文檔案，然後檢視整個程式碼庫以確定最佳整合方式
  3. Vercel agent 完成後，建立 Vercel AI SDK 的實作計畫文件，並更新上下文檔案
  4. 主 agent 讀取此計畫，並執行相應的整合實作

關鍵成功因素

在整個過程中，所有實際的程式碼執行和錯誤修復都由主 agent負責，因為它擁有最完整的上下文資訊，能夠最有效地解決問題。Sub-agent 的角色僅限於提供詳細的規劃和研究報告

總結

透過將 sub-agent 定位為專業的研究員和規劃者，並採用檔案系統作為共享上下文的核心機制，可以大幅提高 Claude Code 的開發效率和成果品質。關鍵要點包括

  1. 正確理解 sub-agent 的設計目的：上下文工程與優化，而非直接實作
  2. 避免常見誤用：不要讓 sub-agent 執行實際的程式碼實作
  3. 建立專業化的研究型 sub-agent：專注於特定領域的知識和最佳實踐
  4. 使用檔案系統管理上下文：透過 Markdown 檔案共享資訊和計畫
  5. 保持主 agent 的實作責任：確保主 agent 擁有完整上下文進行實作和除錯

這種方法不僅能提升開發效率，還能確保程式碼品質和專案的整體一致性。對於正在使用或考慮使用 Claude Code sub-agent 功能的開發者來說，這些最佳實踐將是寶貴的參考

支持創作

如果這篇文章對您有幫助，歡迎透過 贊助連結 支持我持續創作優質內容。您的支持是我前進的動力！

圖片來源：AI 產生