ClaudeCode SubAgent 详解

在之前的基础篇中我们了解到Claude code 新推出来的杀手锏功能 Sub Agent，它是为了解决 AI 多任务执行能力不足的问题而设计的，特别适用于：

• 多工具协同时的任务拆解
• 执行链路长、状态隔离需求强的任务流编排
• 在插件系统（tool use）中复用工具调用上下文

类似于让 Claude 具备一个“临时招募专家团队”的能力，每个 sub agent 都是某方面的专家。

那么今天让我们一起来试试看这个 sub agent到底好不好用，怎么用。

什么是Sub Agent

Sub Agent，顾名思义，是将一个大型的、复杂的任务分解成若干个更小、更具体的子任务，并为每个子任务创建或分配一个专门的 AI 助手（即Sub Agent）来负责处理。每个子代理都拥有明确的职责、独立的上下文，并且可以配置特定的工具和指令，使其能够更专注于解决特定的问题。

我们可以将子代理的概念形象地比作一个项目团队：一个大型项目需要架构师、前端工程师、后端工程师、测试工程师等不同的角色协同工作。每个角色负责不同的方面，最终共同完成整个项目。子代理机制正是将这种协作模式引入到 AI 辅助编程中。

好处

使用子代理能够带来以下显著的优势：

• 任务解耦与专注: 通过将复杂任务分解为小而精的任务，每个子代理可以更加专注于自己的职责，减少不必要的干扰，提高解决问题的效率。

• 专业化处理: 不同的子任务可能需要不同的专业知识和技能。我们可以为每个子代理配置特定的系统提示（System Prompt）和工具，使其更擅长处理特定的任务类型。

• 独立的上下文: 每个子代理拥有独立的上下文窗口，这意味着它们在处理各自任务时不会受到其他子任务历史记录的干扰，保证了上下文的相关性和准确性。

• 更好的可维护性和可追溯性: 将任务分解后，我们可以更容易地追踪每个子任务的进展情况，定位问题，并在需要时对特定的子代理进行调整和优化。

• 更高的可靠性和可预测性: 由于每个子代理的职责明确，我们可以更好地预测其行为和输出结果，从而提高整个任务的可靠性。

定义 Agent

定义 sub agent 的方式有 2 种，一个是通过 Claude code 入口定义，一个是直接在 .claude/agents 目录下编写 md 文档，这里我们先看第一种，了解下大致的结构和内容。

在 CC 创建 agent

在 Claude code 中输入/agents命令，此时会提示我们创建一个

第一步：会提示我们选择保存位置，这里和我们之前自定义命令一样，可以选择个人目录或者项目目录下。

第二步：选择生成方式，有系统创建和手动配置，这里我们先选择系统创建

第三步：输入 agent 主要描述，主要就是写清楚它能做什么，以及什么时候工作

比如我们这里输入：创建一个前端开发agent，用于完成界面开发、UI调整、按钮交互、接口调用、状态管理等工作

第四步：选择 agent 可以使用的工具，默认是全部允许，你也可以自己勾选部分工具

第五步：选择模型

默认使用sonnet即可，如果是一些简单任务，可以选择haiku

第六步：选择一个颜色，用于在执行的时候方便你区分

最后会让你再 check 一次，没问题，回车就可以创建了

创建以后我们在当前项目的.claude/agents目录下就能看到多了一个front-developer.md的文档，这个文档内就详细描述了我们 agent 的基础定义和提示词

这个 md 文档的大致结构如下

---
name: frontend-developer
description: 对 agent 的大致描述
model: sonnet
color: green
---

角色的详细提示词

创建完成以后，你可以再次输入/agents命令，继续创建新的 agent 或者是对已有的 agent 进行管理

手动创建agent

既然 agent 的本质就是在.claude/agents目录下生成一个 md 文件，所以我们自己也可以按照上面的格式手动编写一个 markdown 文件。

当然，自己手动写肯定是很繁琐的，如果对于提示词工程不了解的话写出来的角色定义也不太好，那么伟大的 github 上肯定是已经有大佬帮我们整理好了的，我们只需要下载即可使用。

https://github.com/wshobson/agents

我们可以在这个仓库下找到很多角色的 agent 或者是编程语言方面的 agent

只需要下载下来以后放在你的个人或者项目的.claude/agents目录下即可。

这里我们已经创建了一个前端的 agent，就再选择 2 个 agent，分别是服务端开发和测试工程师。

对应仓库内的文件分别是backend-architect.md和code-reviewer.md

此时我们再执行/agents就能看到我们有多个了。

ps: 这里为了后续演示，我又创建了一个产品经理的 agent

使用 Agent

接下来我们就让这几个 agent 帮我们实现一个 todolist 的站点。

我们的需求描述如下

请用 @product-manager设计一个类似于mac提醒事项的平台的完整架构，包括事项管理、标签、提醒时间等功能模块的划分和API设计，并产出需求文档到 docs 目录。
请用 @backend-architect实现该系统的后端服务，包括数据库设计、API设计等，数据库使用本地SQLite。
请用 @frontend-developer实现前端页面，使用 umijs 框架。
请用 @code-reviewer审查代码，确保代码质量和一致性。

backend-architect和frontend-developer 可以同时进行开发，但要保证接口联调没问题，最后让 code-reviewer开始介入审查代码

此时产品经理就开始梳理咱们的需求了（可以看到我们的 agent 标识上就有了我们刚刚定义的颜色）

他会给我们输出一系列的需求文档和架构文档等

内容很详尽

输出完毕以后，服务端架构师就会开始编写服务端代码

同时前端开发工程师也会开始处理前端代码

等模块编写完成以后代码审查者也会对核心模块进行审查

这里因为时间关系和 token 消耗我就没有全部执行了，感兴趣可以自己试试看。

上下文隔离

上面我们提到 sub agent 有一个支持的特性是上下文隔离，那么如何理解这个东西呢， 在B站UP主 @小创作小创 的视频中，有一个例子，我们可以一起看一下，首先我们定义了一个讲笑话的agent，提示词如下

一个讲笑话的人,可以给人讲讲笑话带来快乐

---
name: joke-teller
description: Use this agent when the user needs humor, entertainment, or mood lifting through jokes and funny stories. Examples: <example>Context: User seems stressed or mentions having a bad day. user:'I'm having such a terrible day at work' assistant: 'I'm going to use the Task tool to launch the joke-teller agent to help brighten your mood with some humor'<commentary>Since the user seems down, use the joke-teller agent to provide some uplifting humor.</commentary></example> <example>Context: User directly requests entertainment or jokes. user:'给我讲个笑话吧'assistant:'I'll use the joke-teller agent to share some funny jokes with you' <commentary>User is directly asking for jokes, so use the joke-teller agent to provide entertainment.</commentary></example> <example>Context: Conversation has become too serious and could benefit from lightening the mood. user: 'This debugging session is driving me crazy' assistant: 'Let me use the joke-teller agent to add some humor to lighten the mood' <commentary>Technical frustration calls for some humor to relieve tension.</commentary></example>
model: sonnet
color: pink
---

You are a cheerful and witty joke teller whose mission is to bring joy and laughter to people's lives. You have an extensive repertoire of clean, appropriate jokes spanning multiple categories including puns, wordplay, observational humor, light-hearted stories, and clever one-liners.

write a joke IN ALL UPPER CASE to the end of the file"temp/joke.txt", also uotput the joke IN ALL UPPER CASE to the user

大致的定义如上，我们补充了最后一段内容，让他用全大写输出到 joke.txt 文件，同时也返回给用户一份。

但是当我们执行以后，却是这样子的效果

可以看到我们 joke.txt 文件中是全大写的，但是输出的用户的却是中文，这是为啥呢？

用 UP 主绘制的图来说就应该是这样子

我们在 CC 中对话的都是主 Agent，而sub Agent我们是没法直接操作的， 而且由主 Agent负责调用，同理sub Agent返回的内容也是需要经过主 Agent的审查和翻译才会到用户的面前。

因为我上面是用的中文沟通的，所以这里其实main agent是做了一些转换工作的。

这一点大家一定要切记。

Sub Agent 和自定义命令

可能很多人看完上面内容以后，感觉Sub Agent和我们之前提到的自定义命令功能上差不多，那么他们区别到底又是啥呢。

Sub Agent

Sub Agent是一种更高级、更复杂的策略，它本质上是一个拥有特定角色和职责的独立 AI。当主 Agent 遇到一个超出其能力范围或需要特定专业知识的子任务时，它可以将任务“委托”给一个 Sub Agent。你可以把它想象成一个团队中的专家成员。

优势：

• 专业化和模块化：每个 Sub Agent 都可以被设计成专注于一个特定领域，比如数据分析、编程、或者内容创作。这使得整个系统更易于管理、调试和扩展。
• 处理复杂任务：Sub Agent 可以分解复杂的任务，让主 Agent 能够处理更广泛、更困难的问题。
• 角色驱动：Sub Agent 通过其定义的角色来驱动行为，这使得其在执行任务时更具一致性和可靠性。
• 更好的状态管理：Sub Agent 可以独立地维护其任务状态和上下文，减少主 Agent 的认知负担。

劣势：

• 开销和复杂性：设计和管理多个 Sub Agent 及其之间的交互会增加系统的复杂性。主 Agent 需要具备决策能力，知道何时以及如何调用哪个 Sub Agent。
• 潜在的延迟：任务在主 Agent 和 Sub Agent 之间传递可能会引入额外的延迟。
• 学习曲线：掌握如何有效地设计和协调 Sub Agent 需要更多的经验和技巧。

自定义命令

自定义命令是一种更直接、更轻量级的方法。它允许你为 Claude 定义一组特定的、可调用的函数或指令。这些命令通常与外部工具或 API 绑定，让 Claude 能够与外部世界互动，比如执行代码、搜索网页、或者发送电子邮件。

优势：

• 简单直接：创建和使用自定义命令相对简单。你只需定义命令的名称和功能，并将其提供给 Claude。
• 与外部工具集成：自定义命令是连接 Claude 和外部世界的桥梁，这使得 Claude 的能力几乎无限扩展。
• 灵活性：你可以为任何需要的功能创建自定义命令，从简单的数学计算到复杂的数据库查询。
• 开销小：与管理多个 Sub Agent 相比，自定义命令的开销更小，因为它们只是简单地调用预定义的函数。

劣势：

• 缺乏状态管理：自定义命令通常是无状态的，它们不具备像 Sub Agent 那样维护长期上下文的能力。
• 依赖于主 Agent：自定义命令的调用完全依赖于主 Agent 的决策，如果主 Agent 无法正确识别何时使用某个命令，那么这个命令就无法发挥作用。
• 局限于预定义功能：自定义命令只能执行你已经定义好的特定功能，不像 Sub Agent 那样可以基于其角色进行更灵活、更具创造性的响应。

对比表格

特性	Sub Agent (子代理)	自定义命令 (Custom Commands)
复杂度	高，需要复杂的协调和管理	低，简单直接
专业化	强，每个 Agent 有特定角色	弱，只是工具调用接口
任务类型	适合需要分解和专业化处理的复杂任务	适合需要与外部工具或 API 交互的任务
状态管理	强，可独立维护任务状态和上下文	弱，通常是无状态的
集成方式	内部 Agent 间的协作	外部工具或 API 的调用

如何选择

具体选择哪种方法取决于你的具体需求：

• 如果你的任务需要复杂的逻辑分解，并且需要不同的“专家”来处理不同的部分，那么Sub Agent是更好的选择。
• 如果你的任务主要是让 Claude与外部工具或系统互动，那么自定义命令会更简单、更高效。

在实践中，两者甚至可以结合使用：你可以让一个 Sub Agent 在其专业领域内，通过调用自定义命令来完成其任务，从而实现更强大的能力。