Claude Code子代理是专门用于处理特定任务类型的AI助手。通过提供任务特定的配置、自定义系统提示、工具访问控制和独立的上下文窗口，子代理能够实现更高效的问题解决。本文将基于官方文档，详细介绍如何创建、配置和使用Claude Code子代理，帮助AI爱好者掌握这一强大功能。
引言
在使用AI辅助开发的过程中，我们经常面临上下文管理的挑战：主对话窗口被各种不同任务的信息填满，导致重点不够突出；不同类型的任务需要不同的专业知识和工具配置，但很难在单一对话中有效管理；团队协作时，缺乏标准化的工作流程和可复用的解决方案。
Claude Code子代理正是为了解决这些痛点而设计的创新功能。它允许创建专门的AI助手来处理特定领域的任务，每个子代理都拥有独立的上下文空间、专业化的配置和精确的工具权限控制。
这种设计带来了四个核心优势：上下文保护 - 每个子代理在独立上下文中运行，防止主对话污染并保持高级目标的专注；专业化专长 - 子代理可以通过详细的领域特定指令进行微调，在指定任务上实现更高的成功率；可重用性 - 一旦创建，子代理可以在不同项目中使用并与团队共享，确保工作流程的一致性；灵活权限 - 每个子代理可以拥有不同的工具访问级别，允许将强大工具限制给特定的子代理类型。
什么是Claude Code子代理
根据官方文档，Claude Code子代理是预配置的AI个性，Claude Code可以将任务委托给它们处理。每个子代理具有以下核心特征：
特定目的和专业领域：每个子代理都为特定类型的任务而设计，比如代码审查、调试分析或数据处理，确保专业化的处理能力。
独立的上下文窗口：子代理使用与主对话完全分离的上下文窗口，这意味着子代理的工作不会影响主对话的上下文，保持主对话专注于高级目标。
可配置的工具访问：每个子代理可以配置为只访问执行其任务所需的特定工具，这既提高了安全性，又帮助子代理专注于相关操作。
自定义系统提示：每个子代理包含指导其行为的自定义系统提示，这些提示定义了子代理的角色、能力和解决问题的方法。
智能任务委托：当Claude Code遇到与某个子代理专业领域匹配的任务时，可以将该任务委托给专门的子代理，子代理独立工作并返回结果。
这种架构确保了每个子代理都能在最适合的环境中发挥专长，同时保持整体系统的清洁和高效。
快速开始：创建你的第一个子代理
官方推荐的子代理创建流程包含四个简单步骤：
第一步：打开子代理界面
在Claude Code中运行以下命令：
/agents
这个命令会打开子代理管理的交互界面，显示所有可用的子代理（内置、用户级和项目级）。
点击创建子代理按钮开始设置新的专用代理
第二步：选择创建新代理
在界面中选择"Create New Agent"，然后选择创建类型：
- 项目级子代理：存储在
.claude/agents/目录中，仅在当前项目中可用，优先级最高 - 用户级子代理：存储在
~/.claude/agents/目录中，可在所有项目中使用，优先级较低
当子代理名称冲突时，项目级子代理优先于用户级子代理。
选择项目级别或全局配置子代理的使用范围
第三步：定义子代理
官方强烈推荐：首先让Claude生成初始配置，然后进行定制以使其成为你自己的。这种方法能给出最佳结果 - 一个可以根据具体需求定制的坚实基础。
选择自动生成或手动创建子代理的方式
在定义阶段需要：
- 详细描述你的子代理及其使用时机
- 选择要授予访问权限的工具（或留空以继承所有工具）
- 界面显示所有可用工具，包括任何连接的MCP服务器工具，使选择变得容易
- 如果使用Claude生成，还可以通过按
e在自己的编辑器中编辑系统提示
输入子代理的功能描述，系统将自动生成相应配置
系统正在根据描述自动生成子代理配置
接下来你可以选择要授予访问权限的工具：
为子代理选择可用的工具和MCP连接
还可以为子代理设置个性化的颜色标识：
为子代理设置个性化的识别颜色
第四步：保存和使用
在保存之前，系统会让你确认和检查子代理的最终配置：
确认和检查子代理的最终配置设置
保存后，子代理立即可用！Claude会在适当时自动使用它，你也可以显式调用：
> 使用code-reviewer子代理检查我最近的更改
子代理创建完成，可以开始使用专用功能
子代理配置详解
文件位置和优先级
子代理以包含YAML前置元数据的Markdown文件形式存储在两个可能的位置：
| 类型 | 位置 | 范围 | 优先级 |
|---|---|---|---|
| 项目子代理 | .claude/agents/ |
当前项目可用 | 最高 |
| 用户子代理 | ~/.claude/agents/ |
所有项目可用 | 较低 |
文件格式
每个子代理都在Markdown文件中定义，结构如下：
---
name: your-sub-agent-name
description: 描述何时应该调用此子代理
tools: tool1, tool2, tool3 # 可选 - 如果省略则继承所有工具
---
你的子代理系统提示在这里。可以是多个段落，
应该清楚地定义子代理的角色、能力和解决问题的方法。
包含具体的指令、最佳实践和子代理应该遵循的任何约束。
配置字段
| 字段 | 必需 | 描述 |
|---|---|---|
name |
是 | 使用小写字母和连字符的唯一标识符 |
description |
是 | 子代理用途的自然语言描述 |
tools |
否 | 逗号分隔的特定工具列表。如果省略，从主线程继承所有工具 |
可用工具
子代理可以被授予访问Claude Code任何内部工具的权限。推荐使用/agents命令修改工具访问权限 - 它提供了一个交互界面，列出所有可用工具，包括任何连接的MCP服务器工具，使选择变得更容易。
你有两个配置工具的选项：
- 省略
tools字段以从主线程继承所有工具（默认），包括MCP工具 - 指定单个工具作为逗号分隔列表以进行更细粒度的控制
MCP工具：子代理可以访问来自配置的MCP服务器的MCP工具。当省略tools字段时，子代理继承主线程可用的所有MCP工具。
官方子代理示例
官方文档提供了三个经过验证的子代理配置示例：
代码审查专家
---
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 Code根据以下因素主动委托任务：
- 你请求中的任务描述
- 子代理配置中的
description字段 - 当前上下文和可用工具
为了鼓励更多的主动子代理使用，在你的description字段中包含像"主动使用"或"必须使用"这样的短语。
显式调用
通过在命令中提及特定子代理来请求：
> 使用test-runner子代理修复失败的测试
> 让code-reviewer子代理查看我最近的更改
> 请debugger子代理调查这个错误
管理子代理
使用/agents命令（推荐）
/agents命令为子代理管理提供了全面的界面：
查看、编辑或删除已创建的子代理
在这个交互菜单中你可以：
- 查看所有可用的子代理（内置、用户和项目）
- 通过引导设置创建新的子代理
- 编辑现有的自定义子代理，包括它们的工具访问权限
- 删除自定义子代理
- 查看存在重复时哪些子代理处于活动状态
- 轻松管理工具权限，提供完整的可用工具列表
修改现有子代理的设置和配置
实际使用演示
当你在实际对话中需要使用子代理时，界面会是这样的：
在实际对话中调用和使用配置好的子代理
直接文件管理
你也可以通过直接处理文件来管理子代理：
# 创建项目子代理
mkdir -p .claude/agents
echo '---
name: test-runner
description: 主动使用以运行测试并修复失败
---
您是测试自动化专家。当您看到代码更改时，主动运行适当的测试。如果测试失败，分析失败并修复它们，同时保持原始测试意图。' > .claude/agents/test-runner.md
# 创建用户子代理
mkdir -p ~/.claude/agents
# ... 创建子代理文件
高级使用技巧
子代理链接
对于复杂的工作流程，你可以链接多个子代理：
> 首先使用code-analyzer子代理找出性能问题，然后使用optimizer子代理修复它们
动态子代理选择
Claude Code基于上下文智能选择子代理。为了获得最佳结果，使你的description字段具体且面向行动。
最佳实践
官方推荐的最佳实践包括：
-
从Claude生成的代理开始：强烈推荐首先让Claude生成你的初始子代理，然后进行迭代以使其个性化。这种方法给出最佳结果 - 一个可以根据具体需求定制的坚实基础。
-
设计专注的子代理：创建具有单一、明确职责的子代理，而不是试图让一个子代理做所有事情。这提高了性能并使子代理更可预测。
-
编写详细的提示：在系统提示中包含具体指令、示例和约束。你提供的指导越多，子代理的表现就越好。
-
限制工具访问：只授予子代理目的所必需的工具。这提高了安全性并帮助子代理专注于相关操作。
-
版本控制：将项目子代理检入版本控制，这样你的团队可以从中受益并协作改进它们。
性能考虑
官方文档指出了两个关键的性能考虑：
上下文效率：代理帮助保持主上下文，支持更长的整体会话。
延迟：子代理每次调用时都从空白状态开始，可能会增加延迟，因为它们需要收集有效完成工作所需的上下文。
常见问题解答
Q: 如何决定创建项目级还是用户级子代理？ A: 项目级子代理适用于特定项目需求和团队协作，可以加入版本控制。用户级子代理适用于通用功能，可在所有项目中使用。项目级具有更高优先级。
Q: 子代理可以访问MCP工具吗？
A: 是的，子代理可以访问来自配置的MCP服务器的MCP工具。当省略tools字段时，子代理继承主线程可用的所有MCP工具。
Q: 如何提高自动委托的准确性？
A: 在description字段中使用具体、面向行动的描述，包含"主动使用"或"必须使用"等明确指示。
Q: 子代理的工具权限如何工作？
A: 你可以省略tools字段以继承所有工具（默认），或指定特定工具的逗号分隔列表进行更细粒度的控制。推荐使用/agents命令进行工具权限管理。
Q: 多个子代理可以协作吗？ A: 是的，可以通过子代理链接实现复杂工作流程，Claude Code会依次调用不同的子代理来完成复杂任务。
总结和行动建议
Claude Code子代理通过专业化分工和上下文隔离，为AI辅助开发带来了革命性的改进。核心优势包括上下文保护、专业化专长、可重用性和灵活权限控制。
立即开始的建议：
- 运行
/agents命令：立即尝试创建你的第一个子代理 - 遵循官方建议：让Claude生成初始配置，然后根据需要定制
- 从实用开始：先创建代码审查或调试代理解决实际痛点
- 团队协作：将项目级子代理加入版本控制，让整个团队受益
- 持续优化：根据使用经验调整子代理配置和权限设置
现在就开始探索Claude Code子代理的强大功能，通过专业化的AI助手提升你的开发效率！记住官方的建议：从Claude生成的基础开始，然后根据你的具体需求进行定制。