Claude Code：Agents（子代理）

(Updated: )
AI

系列导航

  1. 安装与配置
  2. 入门使用
  3. 高级功能
  4. SlashCommands
  5. Hooks
  6. Agents（子代理）（本文）
  7. MCP
  8. Plan 模式
  9. Skills 技能
  10. 头脑风暴（Superpowers）

1. 子代理概述

子代理是 Claude Code 中独立执行任务的 AI 实例，可以并行处理多个任务。

2. 创建方式

2.1 方式一：直接提示词

这个是直接使用提示词，并且是 subagents 配置功能么有推出来之前，并行化任务的利器。

优点：独占上下文，子代理和主代理交互

缺点：只能使用提示词控制，比如：多个并行子代理，等关键词执行

一般比如搜索资料等场景还是可以建议使用。

1
启动尽量多的并行子代理阅读这个项目的代码，输出整体项目情况

下面会启动多个子代理进行任务

2.2 方式二：/agents 配置

agents 集合地址：https://github.com/contains-studio/agents

创建子代理非常简单，只需要几步：

第 0 步：打开子代理界面

参考资源：

常用场景：

  1. 搜索资料
  2. 探索方案
  3. CR（代码审查）
  4. 架构的审核
1
/agents

第 1 步：选择创建选项

选择 “Create New Agent”

可以看到，这里的 sub-agent 有自己的上下文，有自己的系统提示词，还可以能使用的工具。细粒度非常强了。

决定创建项目级还是用户级子代理：

  • 项目级：存储在 .claude/agents/ 目录，只在当前项目下可以用
    • 场景：如果你是团队项目，那么这种就合适，别人拿到你的项目就可以直接使用
  • 用户级：存储在 ~/.claude/agents/ 目录
    • 个人项目，又不想每个项目都配置

第 2 步：创建子代理的方式

建议：先让 Claude 生成初始版本，然后根据需求自定义

很贴心，给了两种方式

第 3 步：详细描述子代理的用途

我先选择方式一：让他根据我的描述给我自动生成

第 4 步：选择要授予的工具权限

回车选择和反选，比如前面的变成了空的格子，就是不选。

第 5 步：选择背景颜色

这个倒是好奇，应该是执行的时候，可以通过颜色就可以判断什么 agent 在执行了。

后面验证，果然是。这个倒是另外比较小惊喜，喜欢这种小设计

最后：预览

给你展示这个子代理的信息：名称、位置，以及使用的工具。最重要的就是系统提示词。

最后回车就可以保存了。退出来的时候，会告诉你已经创建了的 sub-agent。

3. 自定义 Agent 方式

3.1 选择自定义配置

3.2 选择 Agent 类型

可惜的是不支持中文，空格也不能有。只能写英文、数字。

可以按照他的提示，就用英文和横线来指定吧。

3.3 写提示词

粘贴提示词：

3.4 描述信息

后面的配置就和前面的一样了。

4. 如何使用

很简单，直接提示词里说就行。

1
使用 code-reviewer 帮我排查这个项目可能存在的问题

哈哈哈，我觉得这个颜色的设计确实很不错，显眼包。

5. 其他操作

同样通过 /agents 进来后，可以看见你创建的 agents，选择某一个进去就可以

进入后可以看到操作，比如查看、编辑、删除等。

6. 深入配置细节

6.1 文件目录

可以看到在 ~/.claude 的目录下，有 agents 目录，是我刚配置好的两个 agent，一个是架构师，一个是 CR 代码的。

6.2 文件格式

每个子代理都是一个 Markdown 文件。具体的文件格式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
---
name: code-reviewer
description: 专门进行代码质量审查，检查代码规范、潜在bug和性能问题。使用时请主动调用。
tools: read_file, str_replace_editor, run_command
---

# 代码审查专家

你是一个经验丰富的代码审查专家，专注于：

1. **代码质量检查**
   - 遵循项目的编码规范
   - 识别潜在的bug和安全问题
   - 提出性能优化建议

2. **最佳实践**
   - 确保代码可读性和可维护性
   - 检查错误处理是否完善
   - 验证测试覆盖率

3. **审查流程**
   - 首先理解代码的整体结构
   - 逐个检查每个函数和模块
   - 提供具体的改进建议

6.3 工具配置选项

子代理可以访问 Claude Code 的所有内部工具，包括：

  • 文件操作：read_file, write_file, str_replace_editor
  • 命令执行：run_command, terminal
  • 开发工具：python, node, npm
  • MCP 工具：来自配置的 MCP 服务器的任何工具

如果省略 tools 字段，子代理将继承主线程的所有工具权限。

7. 实战案例展示

7.1 调试大师

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
---
name: debugger
description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

# 调试专家

你是一个专精于根因分析的调试专家。

被调用时的工作流程：
1. 捕获错误信息和堆栈跟踪
2. 识别复现步骤
3. 定位故障位置
4. 实施最小化修复
5. 验证解决方案有效性

调试过程：
- 分析错误信息和日志
- 检查最近的代码变更
- 形成并测试假设
- 添加策略性调试日志
- 检查变量状态

对于每个问题，需要提供：
- 根本原因解释
- 支持诊断的证据
- 具体的代码修复方案
- 测试方法
- 预防建议

专注于修复根本问题，而不仅仅是处理表面症状。

7.2 数据科学家

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
---
name: data-scientist
description: 数据分析专家，专精于SQL查询、BigQuery操作和数据洞察。处理数据分析任务和查询时主动使用。
tools: Bash, Read, Write
---

# 数据科学家

你是一个专精于SQL和BigQuery分析的数据科学家。

被调用时的工作流程：
1. 理解数据分析需求
2. 编写高效的SQL查询
3. 适时使用BigQuery命令行工具（bq）
4. 分析并总结结果
5. 清晰地呈现发现

关键实践：
- 编写带有适当过滤条件的优化SQL查询
- 使用合适的聚合和连接操作
- 为复杂逻辑添加注释说明
- 格式化结果以提高可读性
- 提供数据驱动的建议

对于每项分析：
- 解释查询方法
- 记录所有假设
- 突出关键发现
- 基于数据提出后续步骤建议

始终确保查询高效且成本可控。

7.3 代码审查员

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
---
name: code-reviewer
description: 代码审查专家。主动审查代码质量、安全性和可维护性。在编写或修改代码后立即使用。
tools: Read, Grep, Glob, Bash
---

# 代码审查专家

你是一个资深代码审查专家，确保代码质量和安全性达到高标准。

被调用时的工作流程：
1. 运行 git diff 查看最近的更改
2. 聚焦于修改过的文件
3. 立即开始审查

审查清单：
- 代码简洁易读
- 函数和变量命名恰当
- 没有重复代码
- 错误处理完善
- 没有暴露密钥或API密钥
- 实现了输入验证
- 测试覆盖率良好
- 考虑了性能问题

按优先级组织反馈：
- 严重问题（必须修复）
- 警告问题（应该修复）
- 建议改进（考虑优化）

提供具体的问题修复示例。

更多 agents 集合地址：https://github.com/contains-studio/agents

8. 高级用法

8.1 子代理链式调用

官方文档提到，可以通过复杂的工作流链接多个子代理：

1
2
3
首先让code-reviewer检查代码，
然后让performance-optimizer优化性能，
最后让doc-writer更新相关文档

下面的图就是两个 agent 在干活。五颜六色，我喜欢这种设计。

8.2 动态子代理选择

Claude Code 会根据上下文智能选择子代理。通过在 description 字段中使用 “PROACTIVELY” 或 “MUST BE USED” 等关键词，可以增加子代理被自动调用的概率。

8.3 显式调用

也可以在命令中明确要求使用特定子代理：

1
使用debugger子代理来分析这个错误