Claude Code Sub-agent 模式的详解和实践

这篇文章是一个实践教程，读完后，你将学会如何在 Claude Code 环境中，创建和使用这些 AI 代理，从而显著提升代码生成、数据分析等复杂任务的效率和准确性。

在上一篇关于《提示工程（Prompt Engineering）入门指南》的文章中，我们探讨了如何与一个大型语言模型（LLM）高效对话。核心思想是把 AI 看作一个无所不包的"通才"，通过巧妙的指令引导它完成任务。

这种方法在许多场景下都很有用。但当任务变得复杂时，比如需要结合多种专业知识时，你会发现，让一个"通才"面面俱到，其实非常困难。它的回答常常会变得宽泛、不精确，甚至出现事实错误。

今天，我向大家介绍一种更先进、也更高效的 AI 使用模式：Sub-agent（子代理）。

这个概念来自 Anthropic 的官方文档，但请注意，它特指 Claude Code 这个开发工具中的一项功能 。它的核心思想非常符合我们的直觉：猛虎难敌群狼。

一、为什么"通才"不够用？

让我们从一个具体的场景开始。假设你正在开发一个数据分析应用，需要一个 AI 助手来帮助用户。用户的需求可能是：

"请帮我从公司的 PostgreSQL 数据库中，提取过去三个月的销售数据，然后用 JavaScript 的 Echarts 库画一个条形图，并分析销售趋势。"

如果你把这段话直接扔给一个通用的 LLM，会发生什么？

最好的情况是，它能理解你的意-图，并一次性生成 SQL 查询语句和 JavaScript 可视化代码。但更常见的情况是：

SQL 方言错误：它可能生成了适用于 MySQL 的 SQL，而不是 PostgreSQL。
库的使用过时：它使用了 Echarts 的旧版 API。
分析流于表面：趋势分析部分只是几句空话，没有深度。

根本原因在于，这个任务横跨了三个专业领域：数据库查询 (SQL)、数据可视化 (Echarts) 和业务分析。指望一个模型在所有领域都达到专家级水平，是不现实的。

Sub-agent 模式就是为了解决这个问题。

二、Sub-agent 的工作流程

在 Claude Code 环境中，Sub-agent 的本质是预先定义好的、拥有特定"人格"和"技能"的 AI 助手。

这个流程包含两个核心角色：

主 AI (Claude Code)：它就像一个总指挥。当你下达一个模糊的指令时，它会分析这个任务，并判断是否应该把它交给某个更专业的"手下"。
子代理（Sub-agent）：这些是各个领域的专家，比如"代码审查员"、"数据库专家"等。它们有自己的系统提示、独立的上下文记忆、甚至被授权使用不同的工具（比如读写文件、执行 shell 命令）。当总指挥把任务交给它时，它会"启动"并专注地完成这一项工作。

总的来说，就是 Claude Code 这个主 AI，可以智能地调用或委托任务给一个个预先配置好的、更专业的"分身"。

三、Sub-agent 实现方式

在 Claude Code 中创建和使用子代理非常直观，它依赖于配置文件，而不是复杂的代码。主要有两种方式。

方式一：使用 `/agents` 命令（推荐）

最简单的方式，是在 Claude Code 的交互界面中，输入斜杠命令：

bash 复制代码

/agents

这会弹出一个管理菜单，你可以根据引导，可视化地创建新的子代理，定义它的能力，并管理它可以使用的工具。对于新手来说，这是最不容易出错的方式。

方式二：直接创建配置文件

子代理的本质，就是一个带有 YAML 头信息的 Markdown 文件。我们可以手动创建这些文件。

它们存放在两个地方：

项目级 ：.claude/agents/ （仅在当前项目生效，优先级更高）
用户级 ：~/.claude/agents/ （在你的所有项目中都可用）

一个子代理的配置文件结构如下：

markdown 复制代码

---
name: your-sub-agent-name
description: A natural language description of what this agent does and when it should be used.
tools: tool1, tool2 # 可选，允许该代理使用的工具
---

这里是这个子代理的系统提示（System Prompt）。

你可以详细地描述它的角色、能力、行事风格和所有必须遵守的规则。
写得越详细、越清晰，它被激活时表现得就越好。

让我们以前文提到的"数据分析"任务为例，创建一个专门的 echarts-expert 子代理。

首先，在你的项目根目录下创建文件 .claude/agents/echarts-expert.md：

bash 复制代码

mkdir -p .claude/agents
touch .claude/agents/echarts-expert.md

然后，编辑这个文件，写入以下内容：

markdown 复制代码

---
name: echarts-expert
description: Echarts 可视化专家。当用户需要使用 JavaScript 和 Echarts 库创建图表时，应使用此代理。
tools: Read, Write
---

你是一位数据可视化专家，尤其精通 Apache Echarts 库。

你的任务是：

1.  接收用户提供的数据或数据结构。
2.  编写高质量、可直接运行的 Echarts JavaScript 代码。
3.  确保代码遵循 Echarts 的最新最佳实践。
4.  代码中必须包含清晰的注释，解释 `option` 配置中的关键部分。
5.  如果用户的数据不适合所选图表，要给出建议。

这样，一个"Echarts 专家"就被创造出来了。同理，你还可以创建一个 sql-expert。

如何使用子代理？

创建之后，有两种方式可以激活它：

自动委托 ：当你的指令和子代理的 description 字段高度匹配时，Claude Code 会自动调用它。比如，你直接说："帮我用 Echarts 画个图"，它很可能就会激活我们刚刚创建的专家。
显式调用：你也可以明确地"点名"，让某个专家来工作。
markdown 复制代码
```
> 让 echarts-expert 帮我把我最近的销售数据做成一个饼图。
```

四、Sub-agent 模式的优势

理解了正确的实现方式后，我们再来看它的优势，会更加清晰。这些优势是基于 Claude Code 这个工具环境的。

上下文保护 ：这是最重要的优势。每个子代理在自己独立的上下文窗口中运行。这意味着，调用一个"SQL 专家"去处理复杂的数据库查询时，不会污染你主对话窗口中关于前端代码的上下文。这让你可以进行非常长、非常复杂的项目对话，而不会因为上下文混乱导致 AI 表现下降。
专业知识：你可以为每个子代理编写非常详细、非常有针对性的系统提示。一个"代码审查员"的提示，可以包含函数命名、错误处理、安全漏洞等几十条规则。这种"专才"的成功率，远高于让一个"通才"临时抱佛脚。
可重用性 ：你定义好的用户级子代理（存放在 ~/.claude/agents/ 中），可以在你的所有项目中复用。你可以打造一套自己专属的、强大的"专家团队"，随时调用。
灵活的权限管理 (Flexible Permissions) ：你可以精细地控制每个子代理能使用的工具。比如，只有"测试工程师"这个子代理才有权限执行 Bash 命令去跑测试，而一个"文档撰写员"可能只能读取（Read）文件。这带来了更高的安全性。

五、结论

从"提示工程"到"代理工程"（Agent Engineering），我们正在从"与 AI 对话"进化到"设计和指挥 AI 系统"。

Claude Code 的 Sub-agent 功能，就是这种进化的一个极佳范例。从这个角度来看，未来的强大 AI 工具，可能不是一个无所不知的"神"，而是一个高度可配置、可扩展的平台。我们开发者可以通过编写简单的配置文件，就像组建团队一样，创建出无数"工匠"和"专家"，让它们在一个统一的环境下高效协作。

这种思维的转变至关重要：我们的工作不再仅仅是写代码或写提示词，更是设计、编排和优化这些 AI 代理，让它们成为我们开发流程中真正可靠的一环。

（完）