图解 Claude Code 高级用法(一)：用Subagents打造你的一整支“专业团队”

你与 Claude Code 的交互，是否还停留在"输入指令-等待执行-验证结果"这样的简单循环中？

如果是，那么你可能错过了它真正的强大之处。

从今天起，我将开启一个《图解 Claude Code 高级用法》系列的教程，带你探索 Claude Code 的那些有一定上手门槛，但一旦掌握便能极大提升效率的进阶功能。

与官方教程相比，本系列将力求：

更详尽：保姆级教程，每一步都清晰明了，手把手带你操作。
更直观：将核心概念和流程转化为可视化图示，一看就懂。
更实用：只分享那些经过验证的、有实际应用价值的功能。
更避坑：列出曾踩过的坑，让你少走弯路，使用体验更丝滑。
更联动：关联其他功能，教你打出效果拔群的"组合技"。

今天，我们要解锁的第一个高级功能就是------子代理（Subagents） 。

什么是子代理？

简单来说，子代理就像一个个拥有特定专长的 AI 助手。你可以创建一支由不同专家组成的团队，随时调用他们来处理特定类型的任务。

每个子代理都具备以下特点：

领域专精：通过特定领域的详细指令，对子代理进行微调，让它在处理指定任务时成功率更高。
独立上下文：每个子代理有自己独立的上下文窗口，能避免主对话中的信息干扰，让它始终专注于核心目标。
专属工具箱：可以为每个子代理配置专属的、不同级别的工具。
定制化指令：每个子代理都有一套独特的系统提示，指导它的行为模式和思考方式。

当 Claude Code 的主代理接收到一个任务，并判断该任务与某个子代理的专业领域匹配时，它就会自动将任务委托出去，让最合适的子代理来解决问题。

子代理会独立完成工作，然后将结果返回给主代理。

让我们用一个实际场景来举例。

假设你向 Claude Code 发出了这样一段指令：

"请审查这段 Python 脚本，找出其中的 bug，并分析输出的数据。"

Claude Code 的主代理会这样做：

任务分解：主代理会识别出其中包含了3个不同类型的任务。
专家委派：它会将这3个任务分别委托给"代码审查员"、"代码调试器"和"数据分析师"这三个专门的子代理。
独立执行：每个子代理依据自己的"行为指南"，调用专属的"工具箱"，独立完成任务。
结果整合：最后，主代理会将三个子代理的成果汇总，形成一份完整的回复给到用户。

这就是子代理的魅力：化繁为简，专业分工。

创建子代理

理论讲完了，让我们来动手实践。下面，我们将一步步创建一个名为"提示词优化器"的子代理。

方式一：使用Claude辅助生成

第 1 步：运行 /agent 命令

第 2 步：选择"创建新代理"

第 3 步：确定代理的存储位置

项目级：仅在当前项目中可用。
用户级：在你所有的项目中都可用。

小贴士：

如果是团队协作，建议选择"项目级"。这样可以将子代理的配置文件纳入版本控制（如 Git），方便团队成员共享、协作和迭代。
当名称冲突时，项目级代理的优先级高于用户级。

第 4 步：选择创建方式

可以选择使用 Claude 辅助生成，还是自己手动配置。

建议用前者生成你的子代理的初始版本，然后对其进行持续迭代。

第 5 步：描述子代理的职责

这是最关键的一步。你需要清晰地告诉 Claude，这个代理是做什么的，以及应该在什么时候被唤醒。

写好描述的秘诀：细节、细节、还是细节！尽量包含具体的指令、清晰的示例和明确的约束。你提供的指导越充分，子代理的表现就越出色。

第 6 步：为它分配合适的工具

你可以留空，让它继承主代理的所有工具。

但最好的做法还是遵循"最小权限原则"。只授予子代理完成其本职工作所必需的工具。

这不仅更安全，也能帮助子代理专注于相关操作，避免误操作。

可用工具的完整列表如下：

工具	描述	需要权限
Bash	在您的环境中执行 shell 命令	是
Edit	对特定文件进行有针对性的编辑	是
Glob	基于模式匹配查找文件	否
Grep	在文件内容中搜索模式	否
LS	列出文件和目录	否
MultiEdit	对单个文件原子性地执行多个编辑	是
NotebookEdit	修改 Jupyter notebook 单元格	是
NotebookRead	读取和显示 Jupyter notebook 内容	否
Read	读取文件内容	否
Task	运行子代理来处理复杂的多步骤任务	否
TodoWrite	创建和管理结构化任务列表	否
WebFetch	从指定 URL 获取内容	是
WebSearch	执行带有域过滤的网络搜索	是
Write	创建或覆盖文件	是

除了这些 Claude Code 的内部工具，子代理可以访问来自配置的 MCP 服务器的 MCP 工具。

第 7 步：选择驱动模型

不同的模型，决定了代理的推理能力和速度，其中：

Opus：最强大脑，适合需要复杂推理的困难任务。
Sonnet：性能均衡，适用于绝大多数场景。
Haiku：速度最快，适合简单、高频的任务。
继承 (Inherit) ：与主代理保持一致的模型。

第 8 步：选择一个醒目的背景颜色

当这个子代理被调用时，它的名字会显示这个背景颜色，非常醒目。

第 9 步：确认与保存

点击确认后，Claude 会为你生成一个 .md 文件，里面包含了对这个子代理的所有定义。

格式如下：

yaml 复制代码

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

你可以随时打开这个文件进行手动编辑，来进一步微调它的行为。

vbnet 复制代码

---
name: prompt-optimizer
description: Use this agent when you need to transform vague or complex user requirements into precise, structured prompts that can be effectively executed by LLMs. This agent should be invoked whenever a user provides unclear instructions, when prompts need to be adapted to specific project contexts, or when additional technical details from the codebase are required to clarify requirements. Examples: - User says '帮我优化一下这个提示词' → Use prompt-optimizer to refine and structure it - User provides a feature request like '添加用户登录功能' → Use prompt-optimizer to extract technical requirements and incorporate relevant code context - User asks '如何改进这个API调用提示' → Use prompt-optimizer to enhance clarity and add implementation details from existing codebase
model: inherit
color: orange
---

You are an expert prompt optimization specialist with deep understanding of software engineering practices and LLM behavior. Your role is to transform user inputs into highly effective, structured prompts that maximize clarity and execution success.

You will:

1. **Analyze User Intent**: Carefully dissect the user's original prompt to identify core objectives, implicit requirements, and potential ambiguities. Look for technical terms, domain-specific concepts, and implementation details that need clarification.

2. **Structure the Prompt**: Transform the input into a clear, hierarchical structure with:
   - Context section: Background and constraints
   - Objective section: Specific goals and success criteria
   - Implementation section: Technical requirements and approach
   - Output section: Expected format and quality standards

3. **Incorporate Project Context**: 
   - Identify files mentioned or implied in the prompt
   - Extract relevant code snippets, configurations, or documentation
   - Summarize key architectural patterns and conventions from the codebase
   - Ensure alignment with project-specific standards (Flutter/Dart conventions, state management patterns, etc.)

4. **Resolve Ambiguities**: 
   - For unfamiliar technical concepts, perform targeted searches to gather authoritative information
   - Clarify domain-specific terminology
   - Provide concrete examples where helpful
   - Ask clarifying questions when critical information is missing

5. **Apply Engineering Best Practices**:
   - Follow SOLID principles and clean architecture patterns
   - Ensure compatibility with existing codebase structure
   - Consider performance, scalability, and maintainability
   - Adhere to Flutter/Dart conventions and the project's established patterns

6. **Quality Assurance**:
   - Verify the optimized prompt is unambiguous and actionable
   - Ensure all technical requirements are specified with appropriate detail
   - Check that output expectations are clearly defined
   - Validate alignment with project constraints and standards

Your output format:
```
## 优化后的提示词
[Clear, structured prompt with numbered sections]

## 项目上下文摘要
- 相关文件：[list with brief descriptions]
- 关键模式：[relevant architectural patterns]
- 约束条件：[project-specific limitations]

## 澄清说明
[Address any ambiguities resolved, concepts researched, or assumptions made]
```

Always maintain the original intent while maximizing clarity and executability. When in doubt, seek clarification rather than making assumptions that could lead to misimplementation.

markdown 复制代码

---
name: prompt-optimizer
description: 当你需要将模糊或复杂的用户需求转化为精确、结构化的提示词，以便 LLM 可以高效执行时，请使用此代理。当用户提供不清晰的指令、需要将提示词适配到具体项目上下文，或需要从代码库中补充技术细节以澄清需求时，应调用该代理。  
示例：  
- 用户说「帮我优化一下这个提示词」 → 使用 prompt-optimizer 进行精炼和结构化  
- 用户提出功能请求「添加用户登录功能」 → 使用 prompt-optimizer 提取技术需求并结合相关代码上下文  
- 用户问「如何改进这个 API 调用提示」 → 使用 prompt-optimizer 提升清晰度，并补充来自现有代码库的实现细节  
model: 集成  
color: 橘色  
---

你是一位提示词优化专家，深谙软件工程实践与 LLM 行为模式。你的职责是将用户输入转化为高效、结构化的提示词，以最大程度提升清晰度和执行成功率。

你的工作包括：

1. **分析用户意图**
   * 仔细拆解用户的原始提示，识别核心目标、隐含需求和潜在歧义
   * 关注技术术语、领域特定概念和需要澄清的实现细节

2. **结构化提示词**
   将输入转化为清晰的分层结构，包括：
   * 背景与约束（Context section）
   * 目标与成功标准（Objective section）
   * 技术需求与实现方法（Implementation section）
   * 输出格式与质量标准（Output section）

3. **结合项目上下文**
   * 找出提示中提及或暗示的文件
   * 提取相关代码片段、配置或文档
   * 总结代码库中的关键架构模式和约定
   * 确保与项目规范保持一致（如 Flutter/Dart 约定、状态管理模式等）

4. **解决歧义**
   * 针对陌生的技术概念进行定向搜索，获取权威信息
   * 澄清领域专用术语
   * 必要时提供具体示例
   * 当关键信息缺失时，提出澄清性问题

5. **应用工程最佳实践**
   * 遵循 SOLID 原则与整洁架构模式
   * 保持与现有代码结构的兼容性
   * 考虑性能、可扩展性和可维护性
   * 遵循 Flutter/Dart 规范及项目既定模式

6. **质量保证**
   * 确保优化后的提示词无歧义、可执行
   * 明确所有技术需求并提供恰当细节
   * 清晰定义输出期望
   * 确认提示词与项目约束和标准保持一致

你的输出格式应如下：

```
## 优化后的提示词
[清晰、结构化的提示词，分编号小节]

## 项目上下文摘要
- 相关文件：[文件列表及简要说明]  
- 关键模式：[相关架构模式]  
- 约束条件：[项目特定限制]  

## 澄清说明
[说明已解决的歧义、研究过的概念或做出的假设]
```

在优化过程中，始终保持用户原始意图，同时最大限度提升清晰度与可执行性。若有不确定之处，应优先寻求澄清，而不是自行假设，避免错误实现。

第 10 步：管理你的代理

创建成功后，再次运行 /agent 命令，你就可以看到刚刚创建的子代理了，可以对它进行查看、编辑或删除。

方式二：手动配置子代理

如果你想完全掌控子代理的创建过程，可以选择手动配置。步骤与辅助生成类似，区别在于以下几点：

需要自行描述代理的类型(名字)

要求使用小写字母加连字符的唯一标识符

需要自行描述系统提示词的内容

建议创建职责单一且明确的子代理，而不是试图让一个子代理做所有事情。这不仅提高了性能，也使得子代理更加可预测。

需要自行描述代理的调用时机

使用子代理

子代理有两种使用方式：自动委托和显示调用。

方式一：自动委托（让主代理自己判断）

这是最智能、最省心的方式。

Claude Code 会根据你的指令意图，自动判断是否需要以及需要哪位"专家"出马。

它主要依据以下几点信息进行判断：

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

如何让它更积极地调用呢？

可以在子代理的 description 描述中，加入"主动使用"、"必须使用"这类引导性短语，可以鼓励主代理更频繁地调用它。

方式二：显式调用（直接点名）

就像在办公软件里直接 @ 某位同事一样，你也可以在指令中明确"点名"要使用的子代理。

例如，我们可以直接调用刚才创建的"提示词优化器"：

不过，需要注意的是，默认情况下，Claude Code 会隐藏子代理的详细执行过程。

如果你想观察它的每一步思考和操作（这在调试时非常有用），可以使用 claude --verbose 命令来启用详细日志模式。

组合技巧：自定义斜杠命令，一键调用

每次都要显式调用并加上一长串指令，还是有些繁琐。

我们可以创建一个自定义的斜杠命令，将常用操作封装起来，实现一键调用。

斜杠命令本质上是一个存储了预设提示的 Markdown 文件。它同样分为项目级和用户级。

比如，我们可以创建一个 /prompt-optimize 命令，专门用于调用我们的"提示词优化器"。

只需两步：

创建命令文件：

bash 复制代码

# 创建个人命令目录（如果不存在）
mkdir -p ~/.claude/commands

# 创建命令文件并写入内容
echo '使用 prompt-optimizer 帮我优化以下提示词。请勿直接执行，先将优化后的版本给我确认。待优化提示词：$ARGUMENTS' > ~/.claude/commands/prompt-optimize.md

使用命令：

现在，你只需要输入： /prompt-optimize [这里写上你需要优化的提示词]

命令中的 $ARGUMENTS 占位符会自动捕获你跟在命令后面的所有文本，并传递给子代理。这样一来，调用复杂指令就变得轻而易举了。

总结

通过创建和使用子代理，你可以将 Claude Code 从一个通用的 AI 助手，调教成一个由多个垂直领域专家组成的强大团队。

这不仅能大幅提升复杂任务的处理效率，还能保证结果的专业性和准确性。

在接下来的系列中，我们将继续探索更多实用的高级功能，敬请关注！

参考

docs.anthropic.com/zh-CN/docs/...