Claude Code 子代理完整指南

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

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

什么是子代理？

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

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

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

把子代理想象成您团队中的专家，每个人都有自己的专长。当遇到特定问题时，您会找对应的专家来解决，而不是让所有人一起处理。

主要优势

上下文保护

每个子代理在自己的上下文中操作，防止主对话的污染并保持其专注于高级目标。这意味着：

主对话不会被专业细节打断
子代理可以专注于特定任务而不受干扰
整体对话更加清晰和有条理

专业知识

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

代码审查子代理专注于代码质量
调试子代理专注于问题排查
数据分析子代理专注于数据处理

可重用性

一旦创建，子代理可以在不同项目中使用：

项目级子代理：团队共享，保持一致性
用户级子代理：个人使用，跨项目复用
避免重复配置，提高效率

灵活权限

每个子代理可以有不同的工具访问级别：

敏感工具只授权给特定子代理
根据任务需要配置相应权限
提高安全性和专注度

快速开始

第一步：打开子代理界面

运行以下命令：

/agents

第二步：选择创建新代理

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

项目级：只在当前项目中可用，适合团队协作
用户级：在所有项目中可用，适合个人使用

第三步：定义子代理

推荐做法：首先使用 Claude 生成，然后自定义使其成为您的

详细描述您的子代理以及何时应该使用它：

功能描述：说明子代理的专长和用途
使用场景：描述什么情况下应该调用这个子代理
工具选择：选择您想要授予访问权限的工具（或留空以继承所有工具）
系统提示：定义子代理的行为准则和工作方式

界面会显示所有可用工具，使选择变得容易。如果您正在使用 Claude 生成，您也可以通过按 `e` 在您自己的编辑器中编辑系统提示。

第四步：保存并使用

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

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

子代理配置

文件位置

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

类型	位置	范围	优先级
项目子代理	`.claude/agents/`	在当前项目中可用	最高
用户子代理	`~/.claude/agents/`	在所有项目中可用	较低

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

插件代理

插件可以提供与 Claude Code 无缝集成的自定义子代理。插件代理的工作方式与用户定义的代理完全相同，并出现在 /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"
  }
}'

适用场景：

快速测试子代理配置
不需要保存的会话特定子代理
需要自定义子代理的自动化脚本
在文档或脚本中共享子代理定义

文件格式

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

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

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

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

配置字段说明

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

模型选择

model 字段允许您控制子代理使用哪个 AI 模型：

模型别名：使用可用别名之一
'inherit'：使用与主对话相同的模型（对一致性有用）
省略：使用为子代理配置的默认模型

使用 `'inherit'` 在您希望子代理适应主对话的模型选择时特别有用，确保整个会话中的一致能力和响应风格。

工具配置

子代理可以被授予访问 Claude Code 的任何内部工具。

推荐使用 `/agents` 命令修改工具访问权限 - 它提供了一个交互式界面，列出所有可用工具，包括任何连接的 MCP 服务器工具，使选择您需要的工具变得更容易。

配置选项：

省略 tools 字段：从主线程继承所有工具（默认）
指定单个工具：作为逗号分隔列表进行精细控制

管理子代理

使用 /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 字段具体且面向行动，以获得最佳结果。

性能考虑

上下文效率

代理有助于保护主上下文，实现更长的整体会话。这意味着您可以进行更长时间的对话而不会因为上下文限制而需要重新开始。

延迟考虑

子代理每次被调用时都从干净的状态开始，可能会增加延迟，因为它们需要收集有效完成工作所需的上下文。这是为了保证质量而做的权衡。

相关文章