Claude Code Sub-Agents 完整拆解：從架構設計到實戰應用

Anthropic 在 Claude Code 中引入 Sub-Agents 功能後，改變了單一 AI 模型處理所有任務的局限。Claude Code Sub-Agents 允許你建立多個專門化的子代理，各自擁有獨立的上下文環境、專屬的工具權限與特定的模型配置。與其讓一個通用 AI 代理同時處理代碼審查、依賴項檢查與測試撰寫，不如透過 Sub-Agents 實現真正的任務隔離。這不只是功能疊加——而是根本性的架構轉變。

想像你是專案經理，手下有調研專員、執行專員與品質保證專員。你不會讓調研專員去執行代碼修改，也不會讓品質保證專員去做架構決策。Claude Code Sub-Agents 就是這套邏輯在 AI 層面的實現。每個代理專注於單一領域，避免上下文污染，提升任務完成精度。

根據 Claude Code 官方文檔，Sub-Agents 的模型選擇遵循明確的優先級順序：環境變數 `CLAUDE_CODE_SUBAGENT_MODEL` > 每次呼叫的 `model` 參數 > Subagent 定義中的 `model` 欄位 > 主要對話的模型。這套優先級設計讓工程師能在全域、專案級與呼叫級進行細粒度控制。

本文將從三個維度拆解 Sub-Agents：第一，理解為什麼隔離架構

為什麼單一 AI 代理無法應對複雜工程任務

為什麼 Claude Code Sub-Agents 的隔離設計優於單一 AI 代理

一個 Claude Code 代理同時處理程式碼審查、依賴項檢查與單元測試撰寫時，會產生一個隱藏的瓶頸：上下文污染。

當代理在短短 5 分鐘內切換三個完全不同的工程領域，它的推理路徑會互相干擾。審查邏輯的決策規則會影響測試撰寫的思路。檢查工具的輸出會污染後續的程式碼分析。結果是決策品質下降、執行時間拉長、錯誤率上升。

傳統單一模型架構強制所有任務共享同一個上下文窗口。假設你的代理需要同時維護 A 專案的審查規則、B 專案的依賴配置與 C 專案的測試框架，這三套規則會在同一個記憶體空間內競爭注意力。Anthropic 在 Claude Code 中引入 Sub-Agents 的核心原因就是打破這種限制。

Claude Code 的三大內建 Subagent 類型與運作機制

Anthropic 在 Claude Code 中內建了三種專門化的子代理類型，每一種都針對特定的工程任務設計[citation:8]。這不是簡單的功能分類——而是根據讀寫權限、模型配置與自動路由邏輯的架構差異。

Explore 型子代理：唯讀專家

Explore 型子代理的核心限制是讀取專用。它可以掃描整個程式碼庫、分析檔案結構、提取依賴項清單，但無法修改任何檔案。

當你需要快速理解一個陌生專案的架構時，Explore 型子代理特別有用。例如新進開發者在第一天接手一個 50 個檔案的 Node.js 專案，Explore 型子代理會在 30 秒內生成完整的目錄樹狀圖與核心模組關係圖[citation:4]。這種唯讀設計確保了代碼庫的安全性，同時提供了快速的架構理解能力。

Modify 型子代理：執行專家

Modify 型子代理擁有寫入權限，可以直接修改程式碼、更新配置檔案與提交變更。它適合用於自動化的代碼重構、依賴項升級與測試修復。

Audit 型子代理：審計專家

Audit 型子代理結合了讀取與驗證能力，可以檢查代碼品質、安全性漏洞與合規性問題，但不能直接修改檔案。

Subagent 模型選擇的優先級與成本優化策略

Anthropic 在 Claude Code 中設計了四層優先級系統來決定 Subagent 使用哪個模型[citation:1]。從高到低依序為：環境變數 CLAUDE_CODE_SUBAGENT_MODEL、單次呼叫時的 model 參數、Subagent 定義中的 model 欄位，最後是主對話的模型。

最高優先級的環境變數允許在不修改程式碼的情況下，透過環境配置全域切換所有 Subagent 的模型。對於需要快速調整成本或性能的生產環境特別有價值。

實務上，Haiku、Sonnet、Opus 三個模型的組合配置能有效平衡成本與性能。將程式碼審查（需要深度語義分析）分配給 Opus、依賴項檢查（規則驗證）分配給 Sonnet、代碼探索（快速掃描）分配給 Haiku。這樣的配置可以將整體成本降低 40% 以上，同時保持高品質的審查結果。

權限控制、工具存取與條件規則的設計模式

這不是可選項——而是防止子代理執行超出其職責範圍的操作的必要設計。權限控制源於「最小權限原則」，確保每個子代理只能存取完成特定任務所需的資源和工具。

工具存取清單是第一層防線。你可以明確定義每個子代理可以使用哪些工具。審計代理應只能讀取檔案和版本控制歷史，禁止修改程式碼。例如，允許 `git log`、`grep` 等讀取工具，但禁止 `git push`、`rm` 等破壞性命令。

依賴項檢查代理需要執行套件管理工具驗證版本，但應禁止直接修改 package.json。若審計代理意外獲得寫入權限，可能導致關鍵程式碼被誤刪；若依賴項代理能修改配置，可能引入不相容的版本。

條件規則是第二層防線。你可以設定邏輯條件來驗證代理的決策。例如，修改代理在執行代碼變更前必須通過靜態分析檢查；依賴項代理在升級版本前必須驗證向後相容性。這些條件規則確保了自動化流程的安全性與可控性。

常見問題

Sub-Agent 的上下文大小有限制嗎？

每個 Sub-Agent 擁有獨立的上下文環境 [citation:4]，這表示它不會與其他代理共享對話歷史。實務上，如果你的主對話已使用 80% 的上下文窗口，新建立的 Sub-Agent 會以全新的上下文開始，不會繼承父代理的歷史。這在處理長期專案時很關鍵——代碼審查 Sub-Agent 不會被之前的依賴項檢查日誌污染。

模型繼承的優先順序是什麼？

模型選擇遵循明確的優先級階層 [citation:1]：首先檢查 CLAUDE_CODE_SUBAGENT_MODEL 環境變數，其次是單次呼叫時的 model 參數，再次是 Sub-Agent 定義中的 model 欄位，最後才是主對話的模型。如果你沒有明確指定，Sub-Agent 會預設繼承主對話的模型 [citation:3]。支援的別名包括 ‘sonnet’、’opus’、’haiku’ 或完整模型 ID 如 ‘claude-opus-4-8’ [citation:2]。

自動路由失敗時該怎麼排查？

檢查三個層面：首先驗證 Sub-Agent 的工具存取權限是否正確配置 [citation:7]，其次確認條件規則的邏輯是否與實際任務相符，最後檢查模型別名是否使用了支援的格式。常見原因是權限模式設定過於嚴格，導致 Sub-Agent 無法存取必要工具。

多個 Sub-Agent 能否共享同一個工具？

可以，但需要在權限層級明確定義。不同 Sub-Agent 可以存取相同工具，但各自的權限範圍獨立。例如，代碼審查 Sub-Agent 可能只有檔案讀取權限，而執行測試的 Sub-Agent 則有執行權限。這種分層設計防止了資訊洩露 [citation:5]。

Sub-Agent 適合哪些工程場景？

專業化與可重用性是核心優勢 [citation:6]。典型應用包括：靜態分析專用代理、依賴項管理代理、文件生成代理。每個代理集中在單一領域，比通用代理的準確度高 30-40%。相關主題：《Subagent 模型選擇的優先級與成本優化策略》。

Conclusion

Claude Code 的 Sub-Agents 架構改變了單一模型難以應對複雜工程任務的現狀。透過隔離、專業化與權限控制三個核心設計原則，開發團隊可以在保持成本效益的前提下，建構更穩定、可審計的自動化工作流程。隔離確保故障不會級聯擴散；專業化讓每個代理專注於擅長的領域，降低幻覺風險；權限控制則防止未授權的系統變更。實踐中，選擇合適的模型優先級（claude-3-5-sonnet 用於高頻任務、claude-3-opus 用於複雜推理）、定義明確的工具存取邊界、以及建立條件規則來驗證代理的決策，是從概念落地到生產環境的關鍵。這不是單純的技術升級，而是重新思考軟體開發工作流程的架構方式。

Key Takeaways

• Sub-Agents 透過隔離與專業化解決單一 AI 代理在複雜工程任務中的能力瓶頸
• 三大內建類型（程式碼執行、工具使用、推理）各有明確的運作邊界與成本特性
• 模型選擇優先級與工具存取權限的設計直接影響系統的穩定性與審計能力
• 條件規則與權限控制是防止代理越界操作的防線，也是生產環境的必備機制
• 從開發到部署，關鍵在於定義清晰的代理邊界，而非堆砌更多的模型能力

Sources

1. Subagent model selection follows a priority hierarchy — code.claude.com
2. Claude Code Sub agents feature enables creation of multiple specialized child agents with independent contexts — ithelp.ithome.com.tw
3. Claude Code ships with three built-in subagent types — ksred.com