Claude Code 中的自定義子代理是專門的 AI 助手,可以被調用來處理特定類型的任務。它們通過提供具有自定義系統提示、工具和獨立上下文窗口的特定任務配置,實現更高效的問題解決。

什麼是子代理?

子代理是 Claude Code 可以委派任務的預配置 AI 個性。每個子代理:

  • 具有特定的目的和專業領域
  • 使用與主對話分離的自己的上下文窗口
  • 可以配置允許使用的特定工具
  • 包含指導其行為的自定義系統提示

當 Claude Code 遇到與子代理專業知識匹配的任務時,它可以將該任務委派給專門的子代理,該子代理獨立工作並返回結果。

主要優勢

上下文保護

每個子代理在自己的上下文中操作,防止主對話的污染並保持其專注於高級目標。

專業知識

子代理可以針對特定領域進行詳細指令的微調,在指定任務上獲得更高的成功率。

可重用性

一旦創建,子代理可以在不同項目中使用,並與您的團隊共享以實現一致的工作流程。

靈活權限

每個子代理可以有不同的工具訪問級別,允許您將強大的工具限制為特定的子代理類型。

快速開始

創建您的第一個子代理:

1

打開子代理界面

運行以下命令:

/agents
2

選擇「創建新代理」

選擇是創建項目級還是用戶級子代理

3

定義子代理

  • 推薦:首先使用 Claude 生成,然後自定義使其成為您的
  • 詳細描述您的子代理以及何時應該使用它
  • 選擇您想要授予訪問權限的工具(或留空以繼承所有工具)
  • 界面顯示所有可用工具,使選擇變得容易
  • 如果您正在使用 Claude 生成,您也可以通過按 e 在自己的編輯器中編輯系統提示
4

保存並使用

您的子代理現在可用了!Claude 會在適當時自動使用它,或者您可以明確調用它:

> 使用 code-reviewer 子代理檢查我最近的更改

子代理配置

文件位置

子代理作為帶有 YAML 前置內容的 Markdown 文件存儲在兩個可能的位置:

類型位置範圍優先級
項目子代理.claude/agents/在當前項目中可用最高
用戶子代理~/.claude/agents/在所有項目中可用較低

當子代理名稱衝突時,項目級子代理優先於用戶級子代理。

文件格式

每個子代理在 Markdown 文件中定義,具有以下結構:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define 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特定工具的逗號分隔列表。如果省略,從主線程繼承所有工具

可用工具

子代理可以被授予訪問 Claude Code 的任何內部工具。請參閱工具文檔以獲取可用工具的完整列表。

推薦: 使用 /agents 命令修改工具訪問權限 - 它提供了一個交互式界面,列出所有可用工具,包括任何連接的 MCP 服務器工具,使您更容易選擇所需的工具。

您有兩個配置工具的選項:

  • 省略 tools 字段以從主線程繼承所有工具(默認),包括 MCP 工具
  • 指定個別工具作為逗號分隔列表以進行更精細的控制(可以手動編輯或通過 /agents 編輯)

MCP 工具:子代理可以訪問來自配置的 MCP 服務器的 MCP 工具。當省略 tools 字段時,子代理繼承主線程可用的所有 MCP 工具。

管理子代理

使用 /agents 命令(推薦)

/agents 命令為子代理管理提供了全面的界面:

/agents

這會打開一個交互式菜單,您可以:

  • 查看所有可用的子代理(內置、用戶和項目)
  • 使用引導設置創建新的子代理
  • 編輯現有的自定義子代理,包括其工具訪問權限
  • 刪除自定義子代理
  • 查看當存在重複時哪些子代理處於活動狀態
  • 輕鬆管理工具權限,提供可用工具的完整列表

直接文件管理

您也可以通過直接處理子代理文件來管理它們:

# 創建項目子代理
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# 創建用戶子代理
mkdir -p ~/.claude/agents
# ... 創建子代理文件

有效使用子代理

自動委派

Claude Code 基於以下因素主動委派任務:

  • 您請求中的任務描述
  • 子代理配置中的 description 字段
  • 當前上下文和可用工具

為了鼓勵更主動的子代理使用,在您的 description 字段中包含諸如「主動使用」或「必須使用」等短語。

明確調用

通過在命令中提及特定子代理來請求它:

> 使用 test-runner 子代理修復失敗的測試
> 讓 code-reviewer 子代理查看我最近的更改
> 請 debugger 子代理調查這個錯誤

示例子代理

代碼審查員

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

調試器

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

數據科學家

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

最佳實踐

  • 從 Claude 生成的代理開始:我們強烈建議使用 Claude 生成您的初始子代理,然後對其進行迭代以使其個人化。這種方法為您提供最佳結果 - 一個您可以根據特定需求自定義的堅實基礎。

  • 設計專注的子代理:創建具有單一、明確責任的子代理,而不是試圖讓一個子代理做所有事情。這提高了性能並使子代理更可預測。

  • 編寫詳細的提示:在您的系統提示中包含具體指令、示例和約束。您提供的指導越多,子代理的表現就越好。

  • 限制工具訪問:只授予子代理目的所必需的工具。這提高了安全性並幫助子代理專注於相關操作。

  • 版本控制:將項目子代理檢入版本控制,以便您的團隊可以從中受益並協作改進它們。

高級用法

鏈接子代理

對於複雜的工作流程,您可以鏈接多個子代理:

> 首先使用 code-analyzer 子代理找到性能問題,然後使用 optimizer 子代理修復它們

動態子代理選擇

Claude Code 基於上下文智能選擇子代理。使您的 description 字段具體且面向行動,以獲得最佳結果。

性能考慮

  • 上下文效率:代理幫助保護主上下文,實現更長的整體會話
  • 延遲:子代理每次被調用時都從乾淨的狀態開始,可能會增加延遲,因為它們需要收集有效完成工作所需的上下文。

相關文檔

  • 斜線命令 - 了解其他內置命令
  • 設置 - 配置 Claude Code 行為
  • 鉤子 - 使用事件處理程序自動化工作流程