Claude Code Subagent 手把手包教会

1、Subagent 是什么

在 Claude Code 中我们可以为某一类任务定制一个小助手，每个小助手都有自己的专长，比如有的擅长代码审查，有的擅长需求分析。这里的小助手就是 Subagent。

使用 Subagent 有下面的优势：

1）上下文保持

每个 Subagent 都有自己独立的上下文，互不干扰，这样我们的主对话也不会被各种细节搞乱，可以一直专注在大目标上。

2）专业化技能

每个 Subagent 都可以通过系统提示词让它在某一个领域变得非常专业，比如专门做代码审查、SQL 分析等。这样遇到相关任务时，成功率更高。

3）可重用性

每个 Subagent 一旦创建好，可以在不同项目里面反复使用。还能提交到 Git / 分享给团队。

4）权限控制

可以给不同的 Subagent 分配不同的工具箱，比如有的能用操作 MCP 的工具，有的就不能给他使用操作 MCP 的工具。 这样既安全又能让每个子代理专注于自己的本职工作。

2、Subagent 怎么用

1、在 Claude Code 中输入 /agents 命令

2、选 Create New Agent

1）生效范围

这一步需要选择是在项目级别创建还是用户级别创建

1️⃣ 项目级 （存放在目录 .claude/agents/）

子代理只在当前项目中可用，优先级最高。如果你希望这个子代理只服务于某个具体项目，可以选这个

2️⃣ 用户级 （存放在目录~/.claude/agents/）

子代理存放在你的用户目录，在你所有项目中都能用，但优先级低于项目级别。适合你想在多个项目中复用同一个子代理时使用。

一张表搞清楚区别：

类型	存放路径	可用范围	优先级
项目级 subagent	.claude/agents/	仅限当前项目	高
用户级 Subagents	~/.claude/agents/	所有项目	低

这两种方式可以根据实际情况按需选择。我选择在当前项目下创建 subagent。

2）创建方式

这一步选择创建方式，可以让 claude 帮你自动生成，也可以你手工自己配置。

1️⃣ 让 claude 自动生成

2️⃣ 手动配置

这里我们可以看到 Generate with Claude 后面有一个 recommended，说明官方更推荐这种方式去创建。

事实上，在官方文档的最佳实践中，也确实更推荐这种方式。

先让 Claude 自动帮你生成子代理的初始配置，然后你可以再根据自己的需求进行个性化调整。

3）描述你创建的这个 Agent 具体要干啥

一般是按照下面几个方面来写：

1️⃣ 角色定位：一句话说明子代理是谁、擅长什么。

比如说你是一个软件测试工程师，非常擅长发现代码中的隐藏问题。

2️⃣ 触发场景：补充说明什么时候用它"

比如说当我做完一次 commit 之后，立马帮我测试一下整体的功能是否可用，是否有潜在 BUG？

3️⃣ 工作方式与标准：用两三句话交代评审时遵循的最佳实践、风格指南或限制。

4️⃣ 示例可选：若任务复杂，可在正文里放几个输入输出示例，帮助 Claude 更准确理解。

如果不会写怎么办？

一种方法是可以直接问 ChatGPT，另一种方法是按照我上面提到的几个方面，把你知道的能写出来的给它写上去。因为我们上一步选择的是 Generate with Claude (recommended) claude 会根据你写的几个关键词自动生成完整的描述。

4）选择这个 agent 可以用哪些工具

只授予子代理完成其目的所必需的工具，这样更安全，也能让子代理更专注。

5）选择一个背景颜色

这一步是让你给新建的 agent 选一个背景颜色，方便区分和美观。

6）确认并保存

这是创建 Subagent 最后一步，你可以检查一下所有的配置是否符合你的要求。

• Name ：你给 agent 起的名字，这里 claude 帮我生成的名字是 senior-code-reviewer
• Location：这个 agent 的配置文件会被保存在哪里。
• Tools：这个 agent 能用哪些工具
• Description：告诉 claude 这个 agent 什么时候用、做什么
• System Prompt：agent 的角色设定和行为规范（比如，你是一名有15年经验的软件测试专家）

如果确定没问题，直接按回车就可以保存，想要调整修改的话，可以按键盘的 e 进行修改。

上面保存之后，会来到这个页面：

这是一个总览和管理所有子代理（agent）的界面。你可以在这里：

1️⃣ 查看当前有哪些 agent（包括你自己创建的和系统自带的）

2️⃣ 选择某个 agent 进行编辑、删除等操作

3️⃣ 新建一个新的 agent

这里我选中刚刚新建的 agent ，就可以对它进行查看、编辑、删除

进入到这个总览和管理所有子代理（agent）的界面，代表已经完成了子代理的创建和总览。

此时你可以按 Esc 键退出，回到普通的 Claude 终端命令行，然后可以像平时一样写代码、提问或调用刚刚我们创建的子代理了。

以后可以随时运行 /agents命令重新打开该面板，查看、编辑或删除现有子代理，或者新建更多子代理。

补充：

创建完之后，你就可以在当前项目的目录下看到这个 agent，它本质上就是一个 MD 文件，用来指导 claude code 的行为，你可以随时在右侧修改这份 MD 文件的内容。

7）使用

可以直接在 Claude 终端输入命令，显示指定用哪个 subagent 来完成任务。一般来说使用 subagent 一般有下面几种方法：

1️⃣ 自动触发

• 当你在 Claude 终端或对话中描述一个任务时，如果这个任务和某个 subagent 的描述（description）匹配，Claude 会自动调用最合适的 subagent 来处理。
• 例如：你提交了代码，Claude 可能会自动用 senior-code-reviewer来帮你做代码审查。

2️⃣ 显示指定某个 subagent

• 你可以在和 claude 对话中直接点名某个subagent 执行任务。只要你在指令中提到了 subagent 的名字，claude 就会用它来完成任务。
• 例如，请用 senior-code-reviewer 帮我检查刚提交的代码

3️⃣ 链式调用

• 如果任务复杂，可以让多个 subagent 按顺序处理
• 例如，可以先用 code-analyzer subagent 找出性能问题，再用 optimizer subagent 优化这些性能问题

3、怎么找现成的 subagent

去 github 搜索 subagent ，有非常多别人总结好的 subagent ，找点赞高的

我们以上面截图中这个为例，点进去，想用哪个直接把对应的 md 文件下载下来放到我们项目的 .claude/agents/ 文件夹下即可。