子代理

在 Claude Code 中创建和使用专门的 AI 子代理，用于特定任务工作流程和改进的上下文管理。

Claude Code 中的自定义子代理是专门的 AI 助手，可以调用它们来处理特定类型的任务。它们通过提供具有自定义系统提示、工具和独立上下文窗口的任务特定配置，实现更高效的问题解决。

什么是子代理？

子代理是 Claude Code 可以委派任务的预配置 AI 角色。每个子代理：

• 具有特定的目的和专业领域
• 使用与主对话分离的独立上下文窗口
• 可以配置允许使用的特定工具
• 包含指导其行为的自定义系统提示

当 Claude Code 遇到与子代理专业领域匹配的任务时，它可以将该任务委派给专门的子代理，子代理独立工作并返回结果。

主要优势

上下文保持

每个子代理在独立的上下文中运行，防止主对话被污染，并保持对高级目标的专注。

专业专长

子代理可以通过针对特定领域的详细指令进行微调，从而在指定任务上获得更高的成功率。

可重用性

一旦创建，子代理可以在不同项目中使用，并与团队共享以实现一致的工作流程。

灵活权限

每个子代理可以有不同的工具访问级别，允许您将强大的工具限制在特定的子代理类型。

快速开始

要创建您的第一个子代理：

步骤 1：打开子代理界面

运行以下命令：

/agents

步骤 2：选择"创建新代理"

选择是创建项目级还是用户级子代理

步骤 3：定义子代理

• 推荐：首先使用 Claude 生成，然后自定义使其成为您的
• 详细描述您的子代理以及何时应该使用它
• 选择您想要授予访问权限的工具（或留空以继承所有工具）
• 界面显示所有可用工具，使选择变得容易
• 如果您使用 Claude 生成，也可以通过按 e 在自己的编辑器中编辑系统提示

步骤 4：保存并使用

您的子代理现在可用了！Claude 会在适当时自动使用它，或者您可以显式调用它：

> 使用代码审查子代理检查我最近的更改

子代理配置

文件位置

子代理存储为带有 YAML 前置元数据的 Markdown 文件，位于两个可能的位置：

当子代理名称冲突时，项目级子代理优先于用户级子代理。

文件格式

每个子代理在 Markdown 文件中定义，结构如下：

---
name: your-sub-agent-name
description: 描述何时应该调用此子代理
tools: tool1, tool2, tool3  # 可选 - 如果省略则继承所有工具
---

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

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

配置字段

可用工具

子代理可以授予访问 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 字段中包含"主动使用"或"必须使用"等短语。

显式调用

通过在命令中提及来请求特定子代理：

> 使用测试运行器子代理修复失败的测试
> 让代码审查子代理查看我最近的更改
> 要求调试器子代理调查此错误

子代理示例

代码审查器

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

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

调用时：
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
---

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

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

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

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

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

最佳实践

• 从 Claude 生成的代理开始：我们强烈建议使用 Claude 生成您的初始子代理，然后迭代使其成为您个人的。这种方法给您最好的结果 - 一个您可以定制以满足特定需求的坚实基础。

• 设计专注的子代理：创建具有单一、明确责任的子代理，而不是试图让一个子代理做所有事情。这提高了性能并使子代理更可预测。

• 编写详细提示：在系统提示中包含具体指令、示例和约束。您提供的指导越多，子代理的表现就越好。

• 限制工具访问：只授予子代理目的所必需的工具。这提高了安全性并帮助子代理专注于相关操作。

• 版本控制：将项目子代理检入版本控制，以便您的团队可以协作受益和改进它们。

高级用法

链接子代理

对于复杂的工作流程，您可以链接多个子代理：

> 首先使用代码分析器子代理查找性能问题，然后使用优化器子代理修复它们

动态子代理选择

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

性能考虑

• 上下文效率：代理帮助保持主上下文，实现更长的整体会话
• 延迟：子代理每次调用时都从干净的状态开始，在收集有效工作所需的上下文时可能会增加延迟。

相关文档

• 斜杠命令 - 了解其他内置命令
• 设置 - 配置 Claude Code 行为
• 钩子 - 使用事件处理器自动化工作流程