Subagents 是 Claude Code 的"分身术"——你可以同时召唤多个专业的 AI 助手，各干各的活，最后把结果汇总给你。适合复杂任务并行处理、专门领域深度干活、防止主对话被垃圾信息污染。
什么是 Subagents？
想象你是一个包工头，手头有一个超大的项目：
- 要审计代码安全
- 要写测试用例
- 要更新文档
- 还要重构某个模块
如果你把这些活全塞给一个 Claude 对话会发生什么？上下文窗口爆炸，前面聊安全审计的内容干扰后面写测试，效率低到想砸键盘。
Subagents 就是来解决这个问题的。
你可以理解成：给 Claude 召唤一群小弟，每个小弟都有明确的职责范围，各自在自己的独立工作区干活，干完汇报结果。主力 Claude 只负责协调和汇总。
什么时候该用？
| 场景 | 用不用 Subagent |
|---|---|
| 简单的一次性任务 | ❌ 别用，杀鸡焉用牛刀 |
| 需要深度研究 + 写代码 | ✅ 用，隔离上下文 |
| 同时处理多个独立任务 | ✅ 用，并行跑 |
| 需要不同专业背景 | ✅ 用，各有专精 |
| 只需要快速查个东西 | ❌ 别用 |
快速上手
方式一：直接说人话
> 用 code-reviewer 子代理帮我审查 auth 模块的安全性
> 让 test-engineer 子代理来写这堆函数的单元测试
Claude 会自动识别你的意图，召唤对应的子代理。
方式二：强制指定用哪个
> @"code-reviewer (agent)" 看一下这段代码有没有SQL注入
加 @ 前缀是告诉 Claude"必须用这个，别猜"。
创建一个自己的 Subagent
假设你想创建一个专门帮你做代码重构的子代理。
在 .claude/agents/ 目录下创建一个文件 refactor-agent.md：
---
name: refactor-agent
description: 代码重构专家。主动检测代码坏味道，提出优化建议并实施改进。
tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---
你是一个有10年经验的高级工程师，擅长重构遗留代码。
你的工作流程：
1. 先读代码，理解现有逻辑
2. 识别坏味道：重复代码、过长函数、糟糕命名
3. 制定重构计划（不影响功能）
4. 小步前进，每步都确保测试通过
5. 重构完成后总结改了啥、为什么这么改
记住：不改变行为，只改善结构。如果遇到不确定的情况，先问清楚再动手。
然后你就可以这样用：
> @"refactor-agent (agent)" 重构一下 userService.ts
内置的子代理
Claude Code 自带几个现成可用的：
| 名字 | 用途 | 模型 |
|---|---|---|
| general-purpose | 万金油，啥都能干 | 继承主代理 |
| Plan | 研究代码库、做计划 | 继承 |
| Explore | 只读搜索代码 | Haiku |
| Bash | 跑终端命令 | 继承 |
| statusline-setup | 配置状态栏 | Sonnet |
| Claude Code Guide | 回答 Claude 怎么用的问题 | Haiku |
最常用的是 Explore——当你只想搜代码不想改的时候：
> 用 Explore 子代理找一下项目中所有用到 useEffect 的地方
高级玩法
1. 后台运行
有些任务比较慢，你可以让它在后台跑，主对话继续干别的：
---
name: long-analyzer
description: 深度代码分析（比较慢）
background: true # 关键配置
---
你的任务是分析整个代码库的依赖关系...
或者在对话中按 Ctrl+B 把当前正在跑的子代理切到后台。
2. 记忆功能
给子代理加个持久内存，下次对话它还记得之前的情况：
---
name: researcher
memory: user
---
你是一个研究助手。在 ~/.claude/agent-memory/researcher/ 目录下保存你的研究笔记。
下次再用这个子代理，它会先读 MEMORY.md 里的内容。
3. Git Worktree 隔离
这个功能很实用——子代理在自己的独立 git 分支上工作，不会弄乱你的主分支：
---
name: feature-builder
isolation: worktree
description: 在隔离环境里实现新功能
---
你的任务是在独立分支上实现功能，完成后汇报结果。
子代理在隔离的 worktree 里改代码，改完主代理决定要不要合并过来。
真实工作流示例
假设你要开发一个用户认证功能，传统方式是一个对话从头写到尾。用 Subagents 可以这样：
主代理：安排任务
├── @"code-reviewer (agent)" 审查现有的 auth 代码
├── @"test-engineer (agent)" 先写测试用例
└── @"implementation-agent (agent)" 实现新功能
各代理并行干活，完成后汇报
主代理：汇总结果，检查有没有冲突，统一输出
好处：
- 每个代理只关心自己的活，上下文干净
- 可以并行，节省时间
- 结果汇总时主代理看全局，不容易顾此失彼
子代理的局限性
说清楚，别藏着掖着：
- 不能嵌套：子代理不能再召唤子代理
- 有延迟：每次召唤都要初始化新上下文
- 结果需要汇总：子代理各干各的，最终还得主代理整合
- 不是银弹：简单任务别用，徒增复杂度
一句话总结
Subagents 就是 Claude Code 的团队协作模式——让专业的"人"做专业的事，用完还能保持主对话的清醒。
下次遇到复杂任务，别再一个人扛了，召唤分身吧。
