Subagents：让 Claude Code 同时分身干几件事
以前我让 Claude Code 同时做三件事，它一件一件串行干完花了八分钟。后来我才知道 Subagents 可以让它并行派活，各自独立跑，最后汇总结果。这篇聊聊什么时候该用、怎么触发、以及一个让我掉进坑里的权限问题。
我最早发现 Claude Code 会"分身"，是在一次重构里。
当时我在改一个用户模块，需要同时做三件事：
1. 把 UserService 里的逻辑拆到三个子 Service
2. 把前端组件里的用户信息展示改成新的 API 格式
3. 写一组新测试覆盖拆完的 Service
我一句一句跟 Claude 说。它先干第一件，改完我再让它干第二件，再改完说第三件。
全程花了八分钟。
我当时没觉得有什么问题。直到后来我在文档里看到 subagent 这个词，才意识到——原来我可以同时派活。
Subagents 是什么
Claude Code 内部有一个"子代理"机制。你可以把它理解成给 Claude 配了几个不同专长的小弟，每个小弟只干一件事，而且互相不干扰。
最常用的两种子代理类型：
- Explore：负责在代码库里面乱翻。比如"帮我找一下所有用到 JWT 的地方"。它只读不写，适合做代码考古。
- Plan：负责设计方案。比如"帮我规划一下这个模块怎么拆"。它不直接改代码，而是输出一个 plan 文件。
你不需要显式地"创建"一个子代理。只需要在 prompt 里说清楚你要什么，Claude 会自动判断要不要派个子代理去干。
什么时候该用 Subagents
第一，任务之间没有依赖，可以并行。
比如我刚才说的三件事——拆分 Service、改前端 API、写测试。这三件事互不影响，完全可以同时推进。
第二，任务类型不同，需要不同的"专长"。
让同一个 Claude 实例既去翻代码库找所有用到的配置项，又去规划新的架构，上下文会乱。子代理各自带着自己的上下文跑，互不污染。
第三，大任务里包含很多小搜索。
比如"帮我全面审计一下这个项目的安全漏洞"。这种场景非常适合派一个 Explore agent 去全库扫描。
具体怎么用
触发方式一：直接说"同时做几件事"
这是最自然的方式。你不需要记什么命令，直接描述需求就行：
同时帮我做三件事：
1. 重构 UserService，拆成 UserCrudService 和 UserQueryService
2. 把前端 ProfilePage 的用户信息展示改成调用新的 /api/v2/user 接口
3. 写单元测试覆盖新的 UserCrudService
Claude 会自动识别出这是三个独立任务，分别派子代理去处理。
每个子代理会独立运行，完成后把结果汇总给你。
触发方式二：明确指定使用特定子代理类型
如果你知道要用什么类型，可以直接指定：
用 Explore agent 帮我找项目中所有直接调用数据库的地方，不要通过 Repository 层。
或者：
用 Plan agent 帮我规划一下 OAuth2 登录模块的架构，输出到 docs/oauth2-plan.md。
指定类型的好处是——Claude 会严格限制这个子代理的行为。Explore agent 不会改代码，Plan agent 不会执行实现。
触发方式三：斜杠命令
有些内置的斜杠命令会直接触发子代理：
/shortcuts
这个命令会列出你项目里所有可用的快捷方式。很多团队会定义自己的子代理快捷方式。
一个真实场景
上周我在做一个权限系统的重构。需求是：把旧的 RBAC 改成 ABAC。
我要同时确认几件事：
1. 现有代码里所有 @PreAuthorize 注解的位置
2. 数据库里 roles 和 permissions 的当前结构
3. ABAC 策略引擎的选型对比
以前我的做法是——开三个终端标签页，每个标签页里开一个 Claude Code 实例，分别干不同的事。
现在我只开一个 Claude Code，说：
帮我同时做三件事：
1. 用 Explore agent 全库搜索所有 @PreAuthorize 和权限判断逻辑，汇总到 docs/auth-audit.md
2. 用 Explore agent 查数据库里 roles、permissions、user_roles 三张表的结构和数据量
3. 基于 Casbin 和 OpenFGA 做 ABAC 策略引擎选型对比，输出到 docs/abac-engine-comparison.md
十五分钟后，三份文档都写好了。
我只需要再看一遍，合并成一份完整的技术方案。
Tricks
Trick 1：给子代理足够的信息边界
子代理不是全知全能的。你给它的 prompt 越清晰，它跑偏的概率越低。
不好的 prompt：
帮我重构这个项目
好的 prompt：
用 Plan agent 重构 UserService：
- 目标：拆成 UserCrudService 和 UserQueryService
- 约束：不能改前端代码，不能改 API 路由
- 输出：docs/user-service-refactor-plan.md
子代理没有你项目里的所有上下文。你需要把约束条件、输出位置、格式要求都写清楚。
Trick 2：用 Plan agent 输出方案，让主 agent 执行
这是一个我常用的工作流：
用 Plan agent 规划这次重构的方案，不要改代码。
Plan agent 输出一个 plan 文件之后，我再跟 Claude 说：
按照 docs/xxx-plan.md 的方案执行重构
这样我先生成方案、评审、确认没问题再执行。风险小很多。
Trick 3：子代理的结果会自动合并，但你需要会"读"
子代理完成后，Claude 会把所有结果汇总到主对话里。
但有时候子代理的输出很长，关键信息埋在中间。我会直接问 Claude：
把三个子代理的结果各总结成三句话，按优先级排序
它会重新整理一遍，给你一个浓缩版。
注意事项 / 踩坑
坑一：子代理不能访问你当前对话的完整上下文
这是最容易踩的坑。
你以为你在对话里说了很多背景信息，子代理应该都知道。但实际上——子代理只带着你给它的那部分 prompt 跑。
我遇到过这种情况：我在主对话里跟 Claude 讨论了半天项目的权限设计，然后说"用 Explore agent 找一下所有用到权限的地方"。结果子代理找出来的结果完全不相关——因为它没拿到刚才讨论的上下文。
解决办法：在派子代理之前，把关键背景写进 prompt 里。
用 Explore agent 找所有用到 JWT 的地方。背景：我们正在从 session 认证迁移到 JWT，项目是 Spring Boot 3.x，安全框架是 Spring Security 6。
坑二：Explore agent 可能会"过度探索"
Explore agent 的模式是"找到相关的地方就继续深入"。有时候它会钻到一个完全无关的文件里，花了很多 token 还没找到你要的东西。
我见过一个 case：我让它找"所有用到 Redis 的地方"，它翻了一百多个文件，包括测试、配置、甚至 dependency 声明。
你需要给它一个明确的范围：
用 Explore agent 在 src/main/java 目录下找所有直接调用 RedisTemplate 的地方，排除测试文件。
坑三：子代理的并行消耗会叠加
子代理虽然看起来是"同时跑"的，但 token 消耗是叠加的。三个子代理各跑五分钟，你的 session token 消耗可能比一个串行任务还高。
另外，如果你的 session 上下文已经比较大了，派多个子代理可能会导致 Claude 在汇总结果时丢失一些细节。
我的经验是：一个 session 里同时跑的独立子代理不要超过三个。 超过的话，考虑分成两个 session 来做。
坑四：子代理的错误不会自动中断整个任务
这是设计上的取舍。Claude 会等所有子代理都跑完，然后把结果汇总。如果一个子代理失败了，其他子代理的结果还是会正常返回。
你需要自己检查每个子代理的输出，确认有没有遗漏或错误。
我遇到过子代理在翻文件时遇到一个编码问题，静默跳过了某个目录。如果我没逐份检查，就会漏掉那个目录里的相关代码。
一个反直觉的事实
我之前以为子代理是"为了省时间"而设计的。用了一段时间之后我发现——子代理真正的作用是隔离上下文。
以前我让同一个 Claude 实例先干 A 再干 B，A 的上下文会污染 B 的判断。比如 Claude 先翻了一堆配置文件，转头去写新代码的时候，会不自觉地把配置里的旧思路带进去。
子代理各自带着干净的上下文跑，互不干扰。
串行干三件事，不只是慢，而且容易"串味"。
下篇聊聊 Verification Loop，那个让 Claude Code 写完代码会自己回头检查的机制。
评论
发表评论