如何使用Claude Code Sub Agents

Claude Code Sub是专门用于处理特定任务类型的AI助手。通过提供任务特定的配置、自定义系统提示、工具访问控制和独立的上下文窗口， Sub Agent 能够实现更高效的问题解决。本文将基于官方文档，详细介绍如何创建、配置和使用Claude Code Sub Agent ，帮助AI爱好者掌握这一强大功能。

引言

在使用AI辅助开发的过程中，我们经常面临上下文管理的挑战：主对话窗口被各种不同任务的信息填满，导致重点不够突出；不同类型的任务需要不同的专业知识和工具配置，但很难在单一对话中有效管理；团队协作时，缺乏标准化的工作流程和可复用的解决方案。

Claude Code Sub Agent 正是为了解决这些痛点而设计的创新功能。它允许创建专门的AI助手来处理特定领域的任务，每个 Sub Agent 都拥有独立的上下文空间、专业化的配置和精确的工具权限控制。

这种设计带来了四个核心优势：

• 上下文保护 - 每个 Sub Agent 在独立上下文中运行，防止主对话污染并保持高级目标的专注
• 专业化专长 - Sub Agent 可以通过详细的领域特定指令进行微调，在指定任务上实现更高的成功率
• 可重用性 - 一旦创建， Sub Agent 可以在不同项目中使用并与团队共享，确保工作流程的一致性
• 灵活权限 - 每个 Sub Agent 可以拥有不同的工具访问级别，允许将强大工具限制给特定的 Sub Agent 类型

什么是Claude Code Sub Agent

根据官方文档，Claude Code Sub Agent 是预配置的AI个性，Claude Code可以将任务委托给它们处理。每个 Sub Agent 具有以下核心特征：

• 特定目的和专业领域：每个 Sub Agent 都为特定类型的任务而设计，比如代码审查、调试分析或数据处理，确保专业化的处理能力
• 独立的上下文窗口： Sub Agent 使用与主对话完全分离的上下文窗口，这意味着 Sub Agent 的工作不会影响主对话的上下文，保持主对话专注于高级目标
• 可配置的工具访问：每个 Sub Agent 可以配置为只访问执行其任务所需的特定工具，这既提高了安全性，又帮助 Sub Agent 专注于相关操作
• 自定义系统提示：每个 Sub Agent 包含指导其行为的自定义系统提示，这些提示定义了 Sub Agent 的角色、能力和解决问题的方法
• 智能任务委托：当Claude Code遇到与某个 Sub Agent 专业领域匹配的任务时，可以将该任务委托给专门的 Sub Agent ， Sub Agent 独立工作并返回结果

这种架构确保了每个 Sub Agent 都能在最适合的环境中发挥专长，同时保持整体系统的清洁和高效。

快速开始：创建你的第一个 Sub Agent

官方推荐的 Sub Agent 创建流程包含四个简单步骤：

第一步：打开 Sub Agent 界面

在Claude Code中运行以下命令：

/agents

这个命令会打开 Sub Agent 管理的交互界面，显示所有可用的 Sub Agent （内置、用户级和项目级）。

查询所有的 Sub Agent

第二步：选择创建新代理

在界面中选择"Create New Agent"，然后选择创建类型：

• 项目级 Sub Agent：存储在.claude/agents/目录中，仅在当前项目中可用，优先级最高
• 用户级 Sub Agent：存储在~/.claude/agents/目录中，可在所有项目中使用，优先级较低

当 Sub Agent 名称冲突时，项目级 Sub Agent 优先于用户级 Sub Agent 。

点击创建 Sub Agent 按钮开始设置新的专用代理

第三步：定义 Sub Agent

官方强烈推荐：首先让Claude生成初始配置，然后进行定制以使其成为你自己的。这种方法能给出最佳结果 - 一个可以根据具体需求定制的坚实基础。

选择项目级别或全局配置 Sub Agent 的使用范围

选择自动生成或手动创建 Sub Agent 的方式

在定义阶段需要：

• 详细描述你的 Sub Agent 及其使用时机
• 选择要授予访问权限的工具（或留空以继承所有工具）
• 界面显示所有可用工具，包括任何连接的MCP服务器工具，使选择变得容易
• 如果使用Claude生成，还可以通过按e在自己的编辑器中编辑系统提示

输入 Sub Agent 的功能描述，系统将自动生成相应配置

Sub Agent 自动生成配置

接下来你可以选择要授予访问权限的工具：

选择 Sub Agent 工具

还可以为 Sub Agent 设置个性化的颜色标识：

为 Sub Agent 设置个性化的识别颜色

第四步：保存和使用

在保存之前，系统会让你确认和检查 Sub Agent 的最终配置：

确认和检查 Sub Agent 的最终配置设置

保存后， Sub Agent 立即可用！Claude会在适当时自动使用它，你也可以显式调用：

> 使用code-reviewer Sub Agent 检查我最近的更改

Sub Agent 创建完成，可以开始使用专用功能

Sub Agent 配置详解

文件位置和优先级

Sub Agent 以包含YAML前置元数据的Markdown文件形式存储在两个可能的位置：

类型	位置	范围	优先级
项目 Sub Agent	.claude/agents/	当前项目可用	最高
用户 Sub Agent	~/.claude/agents/	所有项目可用	较低

文件格式

每个 Sub Agent 都在Markdown文件中定义，结构如下：

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

你的 Sub Agent 系统提示在这里。可以是多个段落，
应该清楚地定义 Sub Agent 的角色、能力和解决问题的方法。

包含具体的指令、最佳实践和 Sub Agent 应该遵循的任何约束。

配置字段

字段	必需	描述
name	是	使用小写字母和连字符的唯一标识符
description	是	Sub Agent 用途的自然语言描述
tools	否	逗号分隔的特定工具列表。如果省略，从主线程继承所有工具

可用工具

Sub Agent 可以被授予访问Claude Code任何内部工具的权限。推荐使用/agents命令修改工具访问权限 - 它提供了一个交互界面，列出所有可用工具，包括任何连接的MCP服务器工具，使选择变得更容易。

你有两个配置工具的选项：

• 省略tools字段以从主线程继承所有工具（默认），包括MCP工具
• 指定单个工具作为逗号分隔列表以进行更细粒度的控制

MCP工具： Sub Agent 可以访问来自配置的MCP服务器的MCP工具。当省略tools字段时， Sub Agent 继承主线程可用的所有MCP工具。

官方 Sub Agent 示例

官方文档提供了三个经过验证的 Sub Agent 配置示例：

代码审查专家

---
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查询
- 使用适当的聚合和连接
- 包含解释复杂逻辑的注释
- 格式化结果以提高可读性
- 提供数据驱动的建议

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

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

有效使用 Sub Agent

自动委托

Claude Code根据以下因素主动委托任务：

• 你请求中的任务描述
• Sub Agent 配置中的description字段
• 当前上下文和可用工具

为了鼓励更多的主动 Sub Agent 使用，在你的description字段中包含像"主动使用"或"必须使用"这样的短语。

显式调用

通过在命令中提及特定 Sub Agent 来请求：

> 使用test-runner Sub Agent 修复失败的测试
> 让code-reviewer Sub Agent 查看我最近的更改  
> 请debugger Sub Agent 调查这个错误

管理 Sub Agent

使用/agents命令（推荐）

/agents命令为 Sub Agent 管理提供了全面的界面：

查询所有的 Sub Agent

查看、编辑或删除已创建的 Sub Agent

在这个交互菜单中你可以：

• 查看所有可用的 Sub Agent （内置、用户和项目）
• 通过引导设置创建新的 Sub Agent
• 编辑现有的自定义 Sub Agent ，包括它们的工具访问权限
• 删除自定义 Sub Agent
• 查看存在重复时哪些 Sub Agent 处于活动状态
• 轻松管理工具权限，提供完整的可用工具列表

修改现有 Sub Agent 的设置和配置

在这个界面中，你可以编辑 Sub Agent 的名称、描述、系统提示和工具权限。

实际使用演示

当你在实际对话中需要使用 Sub Agent 时，界面会是这样的：

在实际对话中调用和使用配置好的 Sub Agent

直接文件管理

你也可以通过直接处理文件来管理 Sub Agent ：

# 创建项目 Sub Agent 
mkdir -p .claude/agents
echo '---
name: test-runner
description: 主动使用以运行测试并修复失败
---

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

# 创建用户 Sub Agent  
mkdir -p ~/.claude/agents
# ... 创建 Sub Agent 文件

高级使用技巧

Sub Agent 链接

对于复杂的工作流程，你可以链接多个 Sub Agent ：

> 首先使用code-analyzer Sub Agent 找出性能问题，然后使用optimizer Sub Agent 修复它们

动态 Sub Agent 选择

Claude Code基于上下文智能选择 Sub Agent 。为了获得最佳结果，使你的description字段具体且面向行动。

最佳实践

官方推荐的最佳实践包括：

1. 从Claude生成的代理开始：强烈推荐首先让Claude生成你的初始 Sub Agent ，然后进行迭代以使其个性化。这种方法给出最佳结果 - 一个可以根据具体需求定制的坚实基础。

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

3. 编写详细的提示：在系统提示中包含具体指令、示例和约束。你提供的指导越多， Sub Agent 的表现就越好。

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

5. 版本控制：将项目 Sub Agent 检入版本控制，这样你的团队可以从中受益并协作改进它们。

性能考虑

官方文档指出了两个关键的性能考虑：

上下文效率：代理帮助保持主上下文，支持更长的整体会话。

延迟： Sub Agent 每次调用时都从空白状态开始，可能会增加延迟，因为它们需要收集有效完成工作所需的上下文。

常见问题解答

Q: 如何决定创建项目级还是用户级 Sub Agent ？ A: 项目级 Sub Agent 适用于特定项目需求和团队协作，可以加入版本控制。用户级 Sub Agent 适用于通用功能，可在所有项目中使用。项目级具有更高优先级。

Q: Sub Agent 可以访问MCP工具吗？ A: 是的， Sub Agent 可以访问来自配置的MCP服务器的MCP工具。当省略tools字段时， Sub Agent 继承主线程可用的所有MCP工具。

Q: 如何提高自动委托的准确性？ A: 在description字段中使用具体、面向行动的描述，包含"主动使用"或"必须使用"等明确指示。

Q: Sub Agent 的工具权限如何工作？ A: 你可以省略tools字段以继承所有工具（默认），或指定特定工具的逗号分隔列表进行更细粒度的控制。推荐使用/agents命令进行工具权限管理。

Q: 多个 Sub Agent 可以协作吗？ A: 是的，可以通过 Sub Agent 链接实现复杂工作流程，Claude Code会依次调用不同的 Sub Agent 来完成复杂任务。

总结和行动建议

Claude Code Sub Agent 通过专业化分工和上下文隔离，为AI辅助开发带来了革命性的改进。核心优势包括上下文保护、专业化专长、可重用性和灵活权限控制。

立即开始的建议：

• 运行/agents命令：立即尝试创建你的第一个 Sub Agent
• 遵循官方建议：让Claude生成初始配置，然后根据需要定制
• 从实用开始：先创建代码审查或调试代理解决实际痛点
• 团队协作：将项目级 Sub Agent 加入版本控制，让整个团队受益
• 持续优化：根据使用经验调整 Sub Agent 配置和权限设置

现在就开始探索Claude Code Sub Agent 的强大功能，通过专业化的AI助手提升你的开发效率！记住官方的建议：从Claude生成的基础开始，然后根据你的具体需求进行定制。