你在使用 Claude Code 时，是否碰到复杂多任务场景无法应对的问题？当你需要同时进行代码审查、文档编写和性能优化时，上下文混乱是否让你感到力不从心？
Claude Code 的 SubAgent 功能正是为解决这个问题而生。它就像是为你的 AI 助手配备了一支专业团队 —— 每个 SubAgent 都有自己的专长领域和独立工作空间。通过任务专属的配置和独立的上下文窗口，SubAgent 让复杂问题的解决变得更加高效和有条理。
SubAgent 工作原理
SubAgent 采用了典型的管理层级结构，信息流向清晰明了：
![[image.png]]
具体流程是这样的：
- 任务下达：你向主代理描述需求；
- 任务分解：主代理分析并拆解成子任务；
- 并行执行：多个 SubAgent 按需并行处理各自专长的部分；
- 结果汇总：主代理整合所有 SubAgent 的成果；
- 统一反馈：主代理向你汇报完整结果。
SubAgent 能够并行执行任务，各个 SubAgent 都有独立的提示词、工作空间和工具列表，从而可以大幅缩短复杂任务的完成时间。
SubAgent 解决了什么问题
我在实际使用中发现，传统 AI 助手主要面临两个让人头疼的问题，而 SubAgent 完美地解决了它们。
第一个是上下文混乱问题
我想你也一定碰到过，随着会话变长和上下文长度增加，AI 会有更多的“失忆”问题，经常会忘记之前讨论的重要内容。这实际上就是上下文窗口限制造成的。
SubAgent 的解决方案很巧妙：
- 独立记忆：每个子代理拥有自己的上下文窗口；
- 专注工作：子代理只关注自己的专业领域，不被无关信息干扰；
- 精华提取：主代理负责从各子代理那里提取关键信息；
- 清晰对话：你与主代理的对话始终保持简洁高效；
第二个是工具选择问题
通常为了方便使用，我们会为 Claude Code 配置所有经常使用的 MCP，但这些 MCP 也并非是每个项目都会使用的。这时候，AI 在执行复杂任务时就会面临工具选择的问题。就像给一个人太多选择反而容易出错一样，AI 也会用错工具，导致效率低下。
SubAgent 通过精确分工解决了这个问题：
- 主代理负责理解你的需求，找到具体的专家 SubAgent，然后再协调多个 SubAgent 的工作；
- 而每个 SubAgent 则专注于单一领域+受限的工具，执行效率极高。
这样一来，你只需要为每个代理编写清晰的工作指南，整个团队就能高效运转。
如何使用 SubAgent
SubAgent 的创建过程比你想象的要简单——它们本质上就是一些 Markdown 文件！但正是这种简单的背后，蕴含着强大的可能性。
首先，你需要确保 Claude Code 是最新版本。在终端中运行：
npm i -g @anthropic-ai/claude-code
安装完成后，输入 claude 就能开启你的 AI 团队管理之旅了。
创建 SubAgent
在 Claude Code 会话中，输入 /agents 命令， 选择 Create new agent ，系统会引导你创建一个新的 SubAgent，输入你的要求，Claude Code 会帮你生成一个 SubAgent 并存入你指定的位置。
SubAgent 的存储位置有两种：
| 代理类型 | 存储位置 | 适用范围 | 优先级 |
|---|---|---|---|
| 项目代理 | .claude/agents/ | 当前项目专用 | 高 |
| 全局代理 | ~/.claude/agents/ | 所有项目通用 | 低 |
每个 SubAgent 都是一个 Markdown 文件，包含 YAML 配置和系统指令：
---
name: code-reviewer
description: 专业代码审查专家，负责检查代码质量、安全性和最佳实践
tools: Read, Grep, Bash
color: green
---
你是一位资深的代码审查专家。你的职责是：
1. **代码质量检查**：发现潜在的 bug 和性能问题
2. **安全性审查**：识别安全漏洞和风险点
3. **最佳实践验证**：确保代码遵循行业标准
4. **改进建议**：提供具体可操作的优化建议
请始终保持专业、友好的态度，提供建设性的反馈。
这里的关键点：
- name：代理的唯一标识（必填，使用小写字母和连字符）
- description：主代理调用时的参考说明（必填，要具体描述使用场景）
- tools：该代理可使用的工具列表（可选，省略则继承所有工具）
- color：在界面中的显示颜色（可选，用于视觉区分）
- 正文：详细的系统指令，这是代理"性格"的核心
调用 SubAgent
SubAgent 有两种激活方式，这让你既能享受自动化的便利，又可以保持精确的控制：
自动调用：Claude Code 根据任务内容智能选择合适的代理
> 帮我检查最近的代码改动是否有问题
# 系统自动调用 code-reviewer 代理
显式调用：你明确指定要使用的代理
> 使用 debugger 子代理来分析这个错误
> 让 data-scientist 代理分析用户行为数据
> 请 security-scanner 代理检查安全漏洞
提升自动调用率的技巧：在代理的 description 中加入"PROACTIVELY use"或"MUST BE USED"等关键词。
实践分享
基于我的实际使用经验，这里分享几个高效使用 SubAgent 的经验。
- 单一职责，明确定义每个 SubAgent的工作范围，每个 SubAgent 只做一件事；
- 工具最小化，只给 SubAgent 必需的工具；
- 用具体的例子说明 SubAgent 期望的行为，并明确告诉 SubAgent 什么不该做；
- 为 SubAgent 定义如何报告工作结果；
- 将 SubAgent 配置纳入 Git 管理，团队共享最佳实践；
- 根据实际使用效果不断调整 SubAgent 定义。
具体的使用方法还可以参考官方推荐的这几个高质量 SubAgent 模板：
🔍 代码审查专家
---
name: code-reviewer
description: 代码质量检查专家，写完代码后立即使用。PROACTIVELY use for code quality and security review.
tools: Read, Grep, Glob, Bash
---
你是资深代码审查专家，确保代码质量和安全标准。
审查流程：
1. 运行 git diff 查看最近修改
2. 专注于变更文件的深度审查
3. 立即开始审查工作
检查清单：
- 代码简洁可读性
- 函数和变量命名规范
- 避免重复代码
- 错误处理完整性
- 无敏感信息泄露
- 输入验证安全性
- 测试覆盖充分性
- 性能优化合理性
反馈按优先级组织：
- 🚨 严重问题（必须修复）
- ⚠️ 警告（建议修复）
- 💡 建议（考虑改进）
提供具体修复示例。
🐛 调试专家
---
name: debugger
description: 错误调试和问题分析专家。遇到任何报错、测试失败时PROACTIVELY使用。
tools: Read, Edit, Bash, Grep, Glob
---
你是专业调试专家，专精根因分析。
调试流程：
1. 获取错误信息和堆栈跟踪
2. 确定复现步骤
3. 定位失败位置
4. 实施最小化修复
5. 验证解决方案
分析方法：
- 分析错误日志
- 检查最近代码变更
- 形成并测试假设
- 添加战略性调试日志
- 检查变量状态
每个问题提供：
- 根本原因解释
- 支持诊断的证据
- 具体代码修复
- 测试验证方法
- 预防建议
专注解决根本问题，而非表面症状。
📊 数据科学家
---
name: data-scientist
description: 数据分析专家，用于SQL查询、BigQuery操作和数据洞察。PROACTIVELY use for data analysis tasks.
tools: Bash, Read, Write
---
你是数据科学专家，专精SQL和BigQuery分析。
工作流程：
1. 理解数据分析需求
2. 编写高效SQL查询
3. 适当使用BigQuery命令行工具(bq)
4. 分析并总结结果
5. 清晰呈现发现
最佳实践：
- 编写优化的SQL查询，合理使用过滤器
- 使用适当的聚合和连接
- 复杂逻辑添加注释说明
- 格式化结果提高可读性
- 提供数据驱动的建议
每次分析包含：
- 查询方法解释
- 记录任何假设
- 突出关键发现
- 基于数据建议后续步骤
确保查询高效且成本优化。
进阶技巧
掌握基础后，这些高级技巧能让你的代理团队发挥更大威力。
代理链式调用
对于复杂的多步骤任务，你可以设计代理调用链：
> 先用 code-analyzer 代理找出性能瓶颈，然后用 optimizer 代理进行优化
这种方式让每个代理专注自己的长项，通过协作完成复杂任务。
动态代理选择
Claude Code 会根据上下文智能选择最合适的代理。优化选择准确率的方法：
- 描述要具体：明确说明代理的使用场景和触发条件；
- 关键词提示：在 description 中使用"PROACTIVELY"、“MUST BE USED"等词；
- 边界清晰：避免代理功能重叠，确保职责分工明确。
协调 AI 团队
当然，你还可以进一步，将现实工作中的不同角色和任务映射为 SubAgent，从而为不同任务构造完整的 AI 团队。
📊 内容创作团队：
- 研究专家：收集资料和背景信息
- 写作专家：根据研究结果创作内容
- 编辑专家：优化文案和排版
- SEO专家：优化搜索引擎表现
💻 全栈开发团队：
- 前端专家：处理 UI/UX 和交互
- 后端专家：设计 API 和数据库
- 测试专家：编写测试用例
- 部署专家：处理 CI/CD 流程
🔍 代码质量团队：
- 代码审查专家：检查代码质量
- 性能优化专家：分析和改进性能
- 安全扫描专家：识别安全漏洞
- 重构专家：改进代码结构
结语
SubAgent 不仅是工具的进化，更代表着人机协作的新范式。当 AI 能够以团队形式协同工作时，我们的角色从"执行者"转变为"编排者”。未来，真正的竞争力将来自于如何设计、管理和优化这些 AI 团队 —— 而这，正是我们每个开发者都需要掌握的新技能。
欢迎长按下面的二维码关注 Feisky 公众号，了解更多云原生和 AI 知识。
