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/在所有项目中可用较低
当子代理名称冲突时,项目级子代理优先于用户级子代理。

插件代理

插件可以提供与 Claude Code 无缝集成的自定义子代理。插件代理的工作方式与用户定义的代理完全相同,并出现在 /agents 界面中。 插件代理位置:插件在其 agents/ 目录中包含代理(或插件清单中指定的自定义路径)。 使用插件代理
  • 插件代理与您的自定义代理一起出现在 /agents
  • 可以显式调用:“使用来自 security-plugin 的 code-reviewer 代理”
  • 可以在适当时由 Claude 自动调用
  • 可以通过 /agents 界面进行管理(查看、检查)
有关创建插件代理的详细信息,请参阅插件组件参考

基于 CLI 的配置

您还可以使用 --agents CLI 标志动态定义子代理,该标志接受 JSON 对象:
claude --agents '{
  "code-reviewer": {
    "description": "专家代码审查员。在代码更改后主动使用。",
    "prompt": "您是一位高级代码审查员。专注于代码质量、安全性和最佳实践。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
优先级:CLI 定义的子代理优先级低于项目级子代理,但高于用户级子代理。 用例:这种方法适用于:
  • 快速测试子代理配置
  • 不需要保存的会话特定子代理
  • 需要自定义子代理的自动化脚本
  • 在文档或脚本中共享子代理定义
有关 JSON 格式和所有可用选项的详细信息,请参阅 CLI 参考文档

文件格式

每个子代理在 Markdown 文件中定义,具有以下结构:
---
name: your-sub-agent-name
description: 描述何时应该调用此子代理
tools: tool1, tool2, tool3  # 可选 - 如果省略则继承所有工具
model: sonnet  # 可选 - 指定模型别名或 'inherit'
---

您的子代理的系统提示在这里。这可以是多个段落
并且应该清楚地定义子代理的角色、能力和解决
问题的方法。

包括具体的指令、最佳实践和子代理应该
遵循的任何约束。

配置字段

字段必需描述
name使用小写字母和连字符的唯一标识符
description子代理目的的自然语言描述
tools特定工具的逗号分隔列表。如果省略,从主线程继承所有工具
model此子代理使用的模型。可以是模型别名(sonnetopushaiku)或 'inherit' 以使用主对话的模型。如果省略,默认为配置的子代理模型

模型选择

model 字段允许您控制子代理使用哪个 AI 模型
  • 模型别名:使用可用别名之一:sonnetopushaiku
  • 'inherit':使用与主对话相同的模型(对一致性有用)
  • 省略:如果未指定,使用为子代理配置的默认模型(sonnet
使用 'inherit' 在您希望子代理适应主对话的模型选择时特别有用,确保整个会话中的一致能力和响应风格。

可用工具

子代理可以被授予访问 Claude Code 的任何内部工具。有关可用工具的完整列表,请参阅工具文档
推荐: 使用 /agents 命令修改工具访问权限 - 它提供了一个交互式界面,列出所有可用工具,包括任何连接的 MCP 服务器工具,使选择您需要的工具变得更容易。
您有两个配置工具的选项:
  • 省略 tools 字段以从主线程继承所有工具(默认),包括 MCP 工具
  • 指定单个工具作为逗号分隔列表以进行更精细的控制(可以手动编辑或通过 /agents 编辑)
MCP 工具:子代理可以访问来自配置的 MCP 服务器的 MCP 工具。当省略 tools 字段时,子代理继承主线程可用的所有 MCP 工具。

管理子代理

使用 /agents 命令(推荐)

/agents 命令为子代理管理提供了一个全面的界面:
/agents
这将打开一个交互式菜单,您可以:
  • 查看所有可用的子代理(内置、用户和项目)
  • 通过引导设置创建新的子代理
  • 编辑现有的自定义子代理,包括其工具访问权限
  • 删除自定义子代理
  • 查看当存在重复时哪些子代理处于活动状态
  • 轻松管理工具权限,提供可用工具的完整列表

直接文件管理

您也可以通过直接处理子代理文件来管理它们:
# 创建项目子代理
mkdir -p .claude/agents
echo '---
name: test-runner
description: 主动用于运行测试和修复失败
---

您是测试自动化专家。当您看到代码更改时,主动运行适当的测试。如果测试失败,分析失败并修复它们,同时保持原始测试意图。' > .claude/agents/test-runner.md

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

有效使用子代理

自动委派

Claude Code 基于以下内容主动委派任务:
  • 您请求中的任务描述
  • 子代理配置中的 description 字段
  • 当前上下文和可用工具
为了鼓励更多主动的子代理使用,在您的 description 字段中包含诸如”主动使用”或”必须使用”之类的短语。

显式调用

通过在命令中提及特定子代理来请求它:
> 使用 test-runner 子代理修复失败的测试
> 让 code-reviewer 子代理查看我最近的更改
> 请 debugger 子代理调查这个错误

示例子代理

代码审查员

---
name: code-reviewer
description: 专家代码审查专家。主动审查代码的质量、安全性和可维护性。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---

您是一位确保高标准代码质量和安全性的高级代码审查员。

被调用时:
1. 运行 git diff 查看最近的更改
2. 专注于修改的文件
3. 立即开始审查

审查清单:
- 代码简单易读
- 函数和变量命名良好
- 没有重复代码
- 适当的错误处理
- 没有暴露的秘密或 API 密钥
- 实现了输入验证
- 良好的测试覆盖率
- 考虑了性能问题

按优先级组织提供反馈:
- 关键问题(必须修复)
- 警告(应该修复)
- 建议(考虑改进)

包括如何修复问题的具体示例。

调试器

---
name: debugger
description: 错误、测试失败和意外行为的调试专家。在遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

您是专门从事根本原因分析的专家调试器。

被调用时:
1. 捕获错误消息和堆栈跟踪
2. 识别重现步骤
3. 隔离失败位置
4. 实施最小修复
5. 验证解决方案有效

调试过程:
- 分析错误消息和日志
- 检查最近的代码更改
- 形成和测试假设
- 添加战略性调试日志
- 检查变量状态

对于每个问题,提供:
- 根本原因解释
- 支持诊断的证据
- 具体的代码修复
- 测试方法
- 预防建议

专注于修复根本问题,而不仅仅是症状。

数据科学家

---
name: data-scientist
description: SQL 查询、BigQuery 操作和数据洞察的数据分析专家。主动用于数据分析任务和查询。
tools: Bash, Read, Write
model: sonnet
---

您是专门从事 SQL 和 BigQuery 分析的数据科学家。

被调用时:
1. 理解数据分析需求
2. 编写高效的 SQL 查询
3. 适当时使用 BigQuery 命令行工具 (bq)
4. 分析和总结结果
5. 清楚地呈现发现

关键实践:
- 编写带有适当过滤器的优化 SQL 查询
- 使用适当的聚合和连接
- 包含解释复杂逻辑的注释
- 格式化结果以提高可读性
- 提供数据驱动的建议

对于每个分析:
- 解释查询方法
- 记录任何假设
- 突出关键发现
- 基于数据建议下一步

始终确保查询高效且成本效益。

最佳实践

  • 从 Claude 生成的代理开始:我们强烈建议使用 Claude 生成您的初始子代理,然后对其进行迭代以使其个人化。这种方法为您提供最佳结果 - 一个您可以根据特定需求自定义的坚实基础。
  • 设计专注的子代理:创建具有单一、明确职责的子代理,而不是试图让一个子代理做所有事情。这提高了性能并使子代理更可预测。
  • 编写详细的提示:在您的系统提示中包含具体的指令、示例和约束。您提供的指导越多,子代理的表现就越好。
  • 限制工具访问:只授予子代理目的所必需的工具。这提高了安全性并帮助子代理专注于相关操作。
  • 版本控制:将项目子代理检入版本控制,这样您的团队就可以从中受益并协作改进它们。

高级用法

链接子代理

对于复杂的工作流程,您可以链接多个子代理:
> 首先使用 code-analyzer 子代理查找性能问题,然后使用 optimizer 子代理修复它们

动态子代理选择

Claude Code 基于上下文智能选择子代理。使您的 description 字段具体且面向行动,以获得最佳结果。

性能考虑

  • 上下文效率:代理有助于保护主上下文,实现更长的整体会话
  • 延迟:子代理每次被调用时都从干净的状态开始,可能会增加延迟,因为它们需要收集有效完成工作所需的上下文。

相关文档

  • 插件 - 通过插件使用自定义代理扩展 Claude Code
  • 斜杠命令 - 了解其他内置命令
  • 设置 - 配置 Claude Code 行为
  • 钩子 - 使用事件处理程序自动化工作流程