ClaudeCode Subagents 中文文档

· 2927字 · 6分钟 
mindmap
  root((Claude Code 子代理指南))
    什么是子代理
      子代理的定义
      特点
        特定用途和专业领域
        独立上下文窗口
        可配置工具
        自定义系统提示
      委派任务
    关键优势
    快速开始
    子代理配置
      文件位置
        项目子代理
        用户子代理
      文件格式
      配置字段
        name
        description
        tools
        model
      模型选择
      可用工具
    管理子代理
      使用 /agents 命令
      直接文件管理
    有效使用子代理
      自动委派
      显式调用
      示例子代理
        代码审查员
        调试器
        数据科学家
    最佳实践
      从 Claude 生成的子代理开始
      设计专注的子代理
      编写详细提示
      限制工具访问
      版本控制
    高级用法
      子代理链式调用
      动态子代理选择
    性能考量
      上下文效率
      延迟
    更多资源
      斜杠命令
      设置
      Hooks

Claude Code 中的自定义子代理（Custom subagents）是专门的 AI 助手，可以被调用来处理特定类型的任务。它们通过提供针对任务的定制化系统提示（system prompts）、工具以及独立的上下文窗口，从而实现更高效的问题解决。

什么是子代理？ 🔗

子代理是预先配置好的 AI 人格，Claude Code 可以将任务委托给它们。每个子代理：

  • 拥有特定的用途和专业领域
  • 使用独立于主对话的上下文窗口
  • 可以配置为仅使用特定的工具
  • 包含一个自定义的系统提示（system prompt），用于引导其行为

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

主要优势 🔗

快速开始 🔗

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

子代理配置 🔗

文件位置 🔗

子代理以带有 YAML frontmatter 的 Markdown 文件形式存储在以下两个可能的位置：

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

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

文件格式 🔗

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

---
name: your-sub-agent-name
description: 说明在什么情况下应调用该子代理
tools: tool1, tool2, tool3 # 可选 - 如果省略则继承所有工具
model: sonnet # 可选 - 指定模型别名或 'inherit'
---
在这里编写你的子代理的系统提示。可以包含多段内容，
并且应清晰地定义子代理的角色、能力和问题解决方法。  
包括具体的指令、最佳实践，以及子代理应遵循的任何约束条件。

配置字段 🔗

字段 必需 描述
name 是 使用小写字母和连字符的唯一标识符
description 是 对子代理用途的自然语言描述
tools 否 特定工具的逗号分隔列表。如果省略，则继承主线程中的所有工具
model 否 此子代理要使用的模型。可以是模型别名（sonnet、opus、haiku），也可以是 'inherit' 来使用主对话的模型。如果省略，则默认为配置的子代理模型

模型选择 🔗

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

  • 模型别名：使用可用的别名之一：sonnet、opus 或 haiku
  • 'inherit'：使用与主对话相同的模型（有助于保持一致性）
  • 省略：如果未指定，则使用为子代理配置的默认模型（sonnet）

可用工具 🔗

子代理可以被授予对 Claude Code 内部工具的访问权限。完整的工具列表请参阅 工具文档。

配置工具有两种方式：

  • 省略 tools 字段：默认继承主线程的所有工具，包括 MCP 工具
  • 指定单独的工具：以逗号分隔的列表形式，进行更细粒度的控制（可以手动编辑或通过 /agents 编辑）

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

管理子代理 🔗

使用 /agents 命令（推荐） 🔗

/agents 命令提供了一个完整的子代理管理界面：

通过这个交互式菜单，你可以：

  • 查看所有可用的子代理（内置的、用户级和项目级）
  • 使用引导式设置创建新的子代理
  • 编辑已有的自定义子代理，包括它们的工具访问权限
  • 删除自定义子代理
  • 当存在重复时，查看哪些子代理处于激活状态
  • 轻松管理工具权限，并查看完整的可用工具列表

直接管理文件 🔗

你也可以通过直接操作子代理文件来进行管理：

# 创建一个项目子代理
mkdir -p .claude/agents
echo '---
name: test-runner
description: 主动用于运行测试并修复失败
---
你是一名测试自动化专家。当你看到代码变更时，主动运行相关的测试。
如果测试失败，请分析失败原因并进行修复，同时保持原始测试意图。' > .claude/agents/test-runner.md

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

有效使用子代理 🔗

自动委派 🔗

Claude Code 会根据以下内容主动委派任务：

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

显式调用 🔗

通过在命令中直接提及子代理，可以请求特定的子代理：

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

示例子代理 🔗

代码审查员 🔗

---
name: code-reviewer
description: 专业的代码审查专家。主动检查代码的质量、安全性和可维护性。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
你是一名高级代码审查员，负责确保高标准的代码质量和安全性。
当被调用时：
1. 运行 git diff 查看最近的更改
2. 关注已修改的文件
3. 立即开始审查
审查检查清单：
- 代码简洁且可读
- 函数和变量命名合理
- 无重复代码
- 正确的错误处理
- 没有暴露的密钥或 API key
- 实现了输入验证
- 测试覆盖率良好
- 已考虑性能因素
提供按优先级组织的反馈：
- 严重问题（必须修复）
- 警告（应该修复）
- 建议（可改进）
包括具体的修复示例。

调试器 🔗

---
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 生成初始子代理，然后再进行迭代，使其更符合你的个人需求。这种方法能提供最佳效果——一个稳固的基础，便于你根据具体需求进行定制。
  • 设计专注的子代理：让子代理承担单一且明确的职责，而不是让一个子代理做所有事情。这能提升性能，并使子代理行为更可预测。
  • 编写详细的提示：在系统提示（system prompt）中包含具体的指令、示例和约束。你提供的指导越多，子代理的表现就越好。
  • 限制工具访问：只授予子代理所需的工具。这能提高安全性，并帮助子代理专注于相关操作。
  • 版本控制：将项目子代理纳入版本控制，以便团队可以共享、改进并协作开发。

高级用法 🔗

子代理链式调用 🔗

对于复杂的工作流，可以链式调用多个子代理：

> 先使用 code-analyzer 子代理查找性能问题，然后使用 optimizer 子代理修复它们

动态子代理选择 🔗

Claude Code 会根据上下文智能选择子代理。为了获得最佳效果，请让 description 字段具体且以行动为导向。

性能考量 🔗

  • 上下文效率：子代理有助于保存主上下文，从而支持更长的整体会话
  • 延迟：子代理每次被调用时都会从零开始，并可能因为收集所需上下文而增加延迟

更多资源：

  • 斜杠命令 - 了解更多内置命令
  • 设置 - 配置 Claude Code 的行为
  • Hooks - 使用事件处理器自动化工作流
软件开发 Claude Code AI Vibe Coding