Claude Code SDK 中的子代理是由主代理協調的專門化 AI。 使用子代理進行上下文管理和並行化。 本指南說明 SDK 應用程式如何與透過 markdown 檔案建立的子代理互動和使用。

​
概述

子代理僅透過基於檔案系統的方法建立，方式是將帶有 YAML 前置資料的 markdown 檔案放置在指定目錄中。然後 SDK 可以在執行期間調用這些預定義的子代理。

​
使用子代理的好處

​
上下文管理

子代理與主代理保持獨立的上下文，防止資訊過載並保持互動的專注性。這種隔離確保專門化任務不會用無關細節污染主對話上下文。 範例：research-assistant 子代理可以探索數十個檔案和文件頁面，而不會用所有中間搜尋結果使主對話變得雜亂 - 只返回相關發現。

​
並行化

多個子代理可以同時運行，大幅加速複雜的工作流程。 範例：在程式碼審查期間，您可以同時運行 style-checker、security-scanner 和 test-coverage 子代理，將審查時間從分鐘縮短到秒。

​
專門化指令和知識

每個子代理都可以有針對性的系統提示，具有特定的專業知識、最佳實踐和約束。 範例：database-migration 子代理可以具有關於 SQL 最佳實踐、回滾策略和資料完整性檢查的詳細知識，這些在主代理的指令中會是不必要的雜訊。

​
工具限制

子代理可以被限制為特定工具，降低意外操作的風險。 範例：doc-reviewer 子代理可能只能存取讀取和 Grep 工具，確保它可以分析但永遠不會意外修改您的文件檔案。

​
建立子代理

子代理定義為特定目錄中的 markdown 檔案：
  • 專案層級：.claude/agents/*.md - 僅在當前專案中可用
  • 使用者層級：~/.claude/agents/*.md - 在所有專案中可用

​
檔案格式

每個子代理都是帶有 YAML 前置資料的 markdown 檔案： 
---
name: code-reviewer
description: Expert code review specialist. Use for quality, security, and maintainability reviews.
tools: Read, Grep, Glob, Bash  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This defines the subagent's
role, capabilities, and approach to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
配置欄位

欄位必需描述
name是使用小寫字母和連字符的唯一識別符
description是何時使用此子代理的自然語言描述
tools否允許工具的逗號分隔列表。如果省略，則繼承所有工具

​
SDK 如何使用子代理

使用 Claude Code SDK 時，檔案系統中定義的子代理會自動可用。Claude Code 將：
  1. 自動檢測子代理 從 .claude/agents/ 目錄
  2. 基於任務匹配自動調用它們
  3. 使用它們的專門化提示 和工具限制
  4. 為每個子代理調用維護獨立上下文
SDK 遵循檔案系統配置 - 沒有程式化方式在執行時建立子代理。所有子代理必須在 SDK 執行之前定義為檔案。

​
範例子代理

有關子代理的全面範例，包括程式碼審查員、測試運行器、除錯器和安全稽核員，請參閱主要子代理指南。該指南包含建立有效子代理的詳細配置和最佳實踐。

​
SDK 整合模式

​
自動調用

SDK 將根據任務上下文自動調用適當的子代理。確保您的子代理的 description 欄位清楚地指示何時應該使用它： 
---
name: performance-optimizer
description: Use PROACTIVELY when code changes might impact performance. MUST BE USED for optimization tasks.
tools: Read, Edit, Bash, Grep
---

​
明確調用

使用者可以在他們的提示中請求特定的子代理： 
// When using the SDK, users can explicitly request subagents:
const result = await query({
  prompt: "Use the code-reviewer subagent to check the authentication module"
});

​
工具限制

子代理可以透過 tools 欄位限制工具存取：
  • 省略該欄位 - 子代理繼承所有可用工具（預設）
  • 指定工具 - 子代理只能使用列出的工具
唯讀分析子代理的範例： 
---
name: code-analyzer
description: Static code analysis and architecture review
tools: Read, Grep, Glob  # No write or execute permissions
---

You are a code architecture analyst. Analyze code structure,
identify patterns, and suggest improvements without making changes.

​
相關文件