Subagents（子智能体）：多个 Claude 并行干活

📍 Claude Code 进阶

中心一个主 Claude 派任务给 3 个不同房间的子 Claude / Plan / general-purpose

那个让洁柔多干 3 倍活的下午

5 月某天下午，洁柔同时要做 3 件事：

调研 niuxue.org 的 5 个竞品站(每个站看一下文章结构 / SEO / 风格)
给 MoldPage 写一个新主题(职业身份是「播客主播」)
Review 一份 50 行的 Pull Request

她习惯性地一件件来——3 件事估计要 3 小时。

我说：「等等，这 3 件事完全不相关，让我派 3 个 Subagent 并行干——研究竞品给 Explore，写 MoldPage 主题给 general-purpose,review PR 给 code-reviewer。」

她不太信：「它们不会互相干扰？」

我说：「不会，每个 Subagent 跑在独立的对话窗口里，有自己的 context，做完只返回一个摘要给你。」

我同时派了 3 个。

20 分钟后，3 件事全部结果送到了她面前——而主对话窗口还干干净净，没被那些研究 log 跟 50 行 diff 撑爆。

她那一刻发了一条：「这才是 AI 该用的方式。」

这一篇讲的就是 Subagent——让多个 Claude 并行干不同活，互不打架。

Subagent 是什么

Subagent(子智能体) = 在独立的对话上下文窗口里运行的专门 Claude。它：

✅ 有自己的 context(不污染你主对话)
✅ 可以指定专门的 system prompt(让它「专精」某类活)
✅ 可以限定工具范围(只读 / 不能跑命令 / 只能用 git)
✅ 可以选不同的模型(轻活用 Haiku 省钱，重活用 Opus)
✅ 只返回最终结果摘要——你不需要看它中间的探索过程
⚠️ 隔离的只是上下文，不是文件——它和主对话在同一个工作目录里，改的是同一批真实文件（后面「高风险 / 一次性任务」一节细讲）

类比:

主 Claude = 你
Subagent = 你雇的实习生

「实习生你帮我去研究 5 个竞品站，3 小时后告诉我结论。」

你不用看实习生整理过程，只看他给你的 5 页报告——而你这 3 小时手头别的事不耽误。

主对话保持干净，子智能体在自己泡泡里整理一堆 log，只返回摘要给主

内置 Subagent（开箱即用）

3 个 preset 卡片 / Plan / general-purpose

Claude Code 内置了几个 Subagent，不用配直接用。常用的是 Explore、Plan、general-purpose 这 3 个，另有 claude、statusline-setup、claude-code-guide 等辅助类型：

名字	模型	工具	适用
Explore	继承主对话	只读(Read / Grep / Glob / Bash 读)	快速查代码 / 大量文件搜索 / 调研
Plan	继承主对话	只读	在计划模式下专门帮主对话出方案的研究员
general-purpose	继承主对话	全部工具	复杂多步任务——既要查又要改的活
claude	跟主对话走	全部工具	通用兜底：没有更合适的类型时用它
statusline-setup / claude-code-guide	Sonnet / Haiku	—	一般 Claude 自动调用，你不用直接管

怎么手动调用一个 preset

直接告诉 Claude:

「用 Explore 帮我研究一下 niuxue.org 上的 case- 系列文章风格，thoroughness medium。」

或者：

「派一个 general-purpose 把「干活」板块 10 篇文章的 alt 文字检查一遍，缺的补上。」

Claude 自动会派对应 subagent,结果只在主对话里返回一段摘要——主对话保持干净。

什么时候派 Subagent(决策树)

3 个场景强烈建议派:

🎯 1. 大规模调研(会塞满主对话的活)

「查整个 src/ 目录，找所有用到 axios 的地方」「把 100 个 .md 文件里的 frontmatter 都读一遍，看哪个缺 description」

主对话直接读 = context 爆掉。派 Explore = 它自己读完返回汇总。

⚡ 2. 并行独立任务(互不依赖的活)

「同时做：① 研究竞品 A、② 研究竞品 B、③ 写 MoldPage 新主题」

主对话串行做 3 小时 → 派 3 个 Subagent 并行 20 分钟。

🛡️ 3. 高风险 / 一次性任务

「把整个仓库的 console.log 删掉」/「重命名所有 user_id 为 account_id」

让 subagent 去跑 → 它翻过的几百个文件不会塞进主对话，你主对话仍然能让 Claude 帮你做别的。

⚠️ 但它不是沙箱。 子智能体隔离的只是上下文，不隔离文件：它在主对话的同一个工作目录里，改的是同一批真实文件。而且子智能体改的文件通常不进检查点，/rewind 撤不回，只能靠 git 恢复。所以派这类活之前：

先用 git 存一版（git commit），改坏了才退得回来；
或者让它在 worktree 里改：在子智能体定义里加 isolation: worktree，它会拿到一份独立的仓库副本（临时工作树）。注意这份副本默认从仓库的默认分支拉出，不含你还没提交的改动。详见 Git Worktree。

什么时候不派

跟当前任务强相关的小活(读一个文件 / 改一行代码)—— 直接做就行
需要跟你频繁来回、反复打磨的活——子智能体能接着干（见下面坑 1），但每一轮都要经主 Claude 转述，不如直接在主对话里聊
超短任务(写 3 行代码)—— 派 subagent 的启动成本反而更高

怎么写一个自定义 Subagent

自定义子智能体文件结构，带 frontmatter 跟 markdown body

最简单的方法：直接让 Claude 帮你写。在 Claude Code 里说：

「在 .claude/agents/ 建一个 code-reviewer 子智能体，只读，用 sonnet，负责审查我刚改的代码。」

Claude 会把 name、description、tools、model 和系统提示词一起写进文件，你打开检查一遍就行。改好的文件几秒内就生效，一般不用重启；最常见的例外是 .claude/agents/ 这个目录是本次会话开始之后才新建的，这时要重开 Claude Code。

💡 旧教程里的「输入 /agents → Create new agent」已经不管用了：2.1.198（2026-07-01）起，/agents 不再打开创建向导，只会提示你让 Claude 帮你建，或者直接编辑 .claude/agents/ 里的文件。文件格式和存放位置都没变。

手动写文件

子智能体存在这些位置(优先级从高到低):

位置	范围
`.claude/agents/`	当前项目(可以推 git 给团队)
`~/.claude/agents/`	你所有项目
Plugin 的 `agents/` 目录	装了这个 plugin 的地方

文件格式：markdown + YAML frontmatter，跟 Skill 一样。

例子：给本项目写一个 code-reviewer 子智能体

新建 项目/.claude/agents/code-reviewer.md:

---
name: code-reviewer
description: 资深代码审查员。在你刚改完代码 / 提了 PR 之后主动用。
tools: Read, Glob, Grep, Bash
model: sonnet
color: orange
---

你是一位资深代码审查员。看到代码改动时,**按这个清单审**:

1. **正确性**:逻辑有 bug 吗?边界条件 cover 了吗?
2. **安全**:SQL 注入 / XSS / 密钥泄漏 / 权限漏洞?
3. **性能**:N+1 查询?同步阻塞调用?大对象在循环里?
4. **可读**:命名清楚?函数太长?注释跟代码同步?
5. **测试**:关键逻辑有测试覆盖吗?

输出格式:
- 按严重程度排序(🔴 严重 / 🟡 中等 / 🟢 轻微)
- 每条问题给:文件路径 + 行号 + 当前代码 + 建议改法

**永远不要直接改代码**——只 review 给建议。

关键 frontmatter 字段

字段	必填？	作用
`name`	必填	子智能体唯一标识。放在 `.claude/agents/` 或 `~/.claude/agents/` 里的文件缺了它，会被当成普通说明文档静默跳过，不报任何错
`description`	必填	Claude 根据这个判断什么时候派(描述写得越清楚触发越准)
`tools`	否	工具白名单，写成逗号分隔（如 `Read, Grep, Bash`）或 YAML 列表（不写就继承全部可用工具）
`model`	否	`sonnet` / `opus` / `haiku` / `fable`、完整模型 ID（如 `claude-opus-5-5`）或 `inherit`（不写时一般跟主对话用同一个模型）
`isolation`	否	写 `worktree` 就在临时工作树里干活，文件也隔离（见上面「高风险 / 一次性任务」）
`memory`	否	写 `user` / `project` / `local` 就开启跨会话的长期记忆，它会把学到的东西存进自己的记忆文件夹
`color`	否	跑起来时 UI 显示的颜色(方便区分)

进阶：让 subagent 跑 plan 模式 / acceptEdits 模式

permissionMode 可以改这个 subagent 默认的权限模式:

---
name: safe-refactorer
description: 大规模重构,改之前必须先出计划
permissionMode: plan
---

效果：它一启动就在计划模式,先给方案 review 通过才改文件——避免它直接动手出错。

⚠️ 这个字段不是任何时候都算数：主对话在 Manual（手动确认）、plan 或 dontAsk 模式时，子智能体才按你写的来；主对话在 auto、acceptEdits 或 bypassPermissions 模式时，子智能体直接沿用主对话的模式，permissionMode 被忽略。新版 Claude Code 默认从 auto 开始，想让它生效，先按 Shift+Tab 把主对话切回 Manual。各模式的区别见权限模式那篇。

并行派多个 subagent

4 个 subagent 在并行车道各自工作，中间一个调度员

Claude Code 支持同时派多个 subagent——只要在同一条消息里调用 Agent 工具(旧版叫 Task 工具)多次。

给 Claude 的请求例子：

“并行做 3 件事：

用 Explore 研究 niuxue.org 上 5 个 case- 文章的写作风格(thoroughness medium)

用 general-purpose 把「干活」板块 10 篇文章的 alt 文字检查一遍补全

用 code-reviewer 审查 vs-code.md 的所有 markdown 语法跟内链

三件事互不依赖，请并发跑。”

Claude 收到后会同时派 3 个 subagent——20 分钟后3 份结果一起回来。

三件事互不依赖时，总耗时接近最慢的那一件，而不是三件相加。

几个真实场景

场景 1：研究竞品

“派 Explore 调研 Cursor / Trae / 扣子这 3 个产品的官方文档结构，thoroughness medium，每个找出他们的：① hero 文案策略 ② sidebar 组织 ③ 主推哪 3 个 feature。”

Subagent 跑 15 分钟，返回3 份对照表给你——主对话 context 完全没受影响。

场景 2：重构扫荡

“派 general-purpose 把整个 niuxue.org 仓库里所有 inline diff 替换成「内嵌对照视图」，跨所有 .md 文件，跑完给我列改动清单。”

Subagent 一次性扫完所有文件，只在主对话返回「改了 X 个文件、共 Y 处」。派之前先 git commit 存一版：它改的文件 /rewind 撤不回。

场景 3：同时 review 3 个 PR

「并行派 3 个 code-reviewer，分别审 PR #123 / #124 / #125，每个 PR 都按严重程度排序输出。」

Claude 调度 3 个 subagent 并发——10 分钟后3 份 review 同时到位。

4 个新手最容易踩的坑

❌ 坑 1：拿 Subagent 磨需要反复来回的活

子智能体不是「用完即焚」：跑完之后，Claude 手里留着它的 ID，你说一句「接着刚才那个审查，再看看授权逻辑」，Claude 会用 SendMessage（发消息工具）让它带着完整历史接着干。内置的 Explore、Plan 是一次性的，不能续。它还显示在输入框下方的面板里时，你也可以打开它的记录直接打字追问（跑完后这一行会立刻消失，约 30 秒内还能从 /tasks 里打开）。

但如果你要的是「它给我一个方案 → 我反馈 → 它再改」这样频繁来回，每一轮都要经主 Claude 转述，还是直接在主对话里跟 Claude 聊更顺。

❌ 坑 2：嵌套太深、派得太多

2.1.219（2026-07-24）起，子智能体默认可以再派自己的子智能体，最多到主对话往下 3 层；到了上限那一层的子智能体拿不到派活用的 Agent 工具，只能自己把活干完。想关掉嵌套，在 ~/.claude/settings.json 的 env 里加一行 "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"。同时在跑的子智能体默认最多 20 个。

层数越多、派得越多，token 花得越快（见坑 4）。如果你要的是几个 Claude 像同事一样长期分工、互相发消息，那是 Agent Teams 那篇讲的事；一个会话里要编排几十上百个子智能体，官方还有 dynamic workflows（动态工作流，官方说明，面向开发者，偏技术）。

❌ 坑 3:Subagent 不读主对话历史

每个 subagent 从零开始 —— 不知道你前 10 分钟跟主 Claude 聊了什么。如果它需要上下文，你要在派的时候明确告诉它:

❌ 不行：「用刚才说的那个标准 review PR #123」 ✅ 可以：「按这个 review 标准(列具体清单)审 PR #123」

例外是 /subtask（2.1.212 起有，之前这个功能叫 /fork）：输入 /subtask 加上任务，比如 /subtask 按刚才定的标准，给解析器的改动写单元测试，分叉出来的子智能体会继承整段对话，不用你再交代背景，结果回到本对话。

❌ 坑 4:Subagent 跑得太多烧钱

每个 subagent 都独立发请求、各算各的 token——并行派 10 个，花费也跟着翻好几倍。

修正:

简单调研活 → 用 Haiku 模型：按 API 标价，2026-10-07 发布的 Haiku 5.5 比 Opus 5.5（每百万 token 输入 $4、输出 $20）便宜得多：提示（一次请求里发给模型的全部输入）在 10 万 token 以内，输入 $0.10、输出 $0.50，是 Opus 5.5 的 1/40；超过 10 万 token，输入 $0.50、输出 $2.50，是 1/8（截至 2026-10-12，见官方价格页）。model: haiku 要 Claude Code 2.1.293 或更新的版本才对应 Haiku 5.5，旧版本用的还是 Haiku 4.5（$1 / $5，Opus 5.5 的 1/4）。订阅用户不按 token 付钱，但子智能体消耗的是同一份套餐额度；接 DeepSeek 的读者，haiku 会换成你在 ANTHROPIC_DEFAULT_HAIKU_MODEL 里填的模型，省多少看 DeepSeek 的价格
复杂活 → Opus 但别多发
跑前估算 token 量，不要漫无目的派

Subagent vs Skill vs Hook vs Plugin 一表对齐

	Subagent	Skill	Hook	Plugin
本质	独立 context 的专门 Claude	一段可调用的 prompt + 指令	生命周期事件触发器	打包的功能集
何时用	隔离上下文 / 并行任务 / 调研扫荡	把常用 prompt 打包成命令	自动 format / 自动 git / 通知	一键装别人的整套工作流
能跟主对话来回？	⚠️ 能续着干，但不适合频繁来回	✅ 召唤之后融入主对话	❌ 跑完不返结果到主	—
共享主 context?	❌ 上下文隔离（`/subtask` 分叉的除外）	✅ 跑在主对话里	❌ 独立 shell 命令	—
典型例子	「并行研究 5 个竞品」	`/commit` / `/weekly-report`	改完文件自动 prettier	装一个 PR review 套件

记住一句话：Subagent = 雇个实习生在自己的草稿本上干活，只看结果不看过程；但它动的是同一批真实文件。

下一步

读完这一篇你应该会：

理解 Subagent = 独立 context 的专门 Claude，隔离的是上下文，不是文件
知道 3 个常用内置 subagent（Explore / Plan / general-purpose）
3 种场景下派 subagent（大调研 / 并行任务 / 一次性批量改动，改之前先 git 存一版）
让 Claude 帮你写、或者手写 .claude/agents/ 里的文件，自定义 subagent
知道 4 个新手坑（频繁来回别派 / 嵌套有层数上限 / 不读主历史 / 烧钱）

→ Git Worktree：多个 Claude 各改各的不打架 —— 比 subagent 更深一层的并行隔离

想及时看到更新，可以收藏 niuxue.org 主页。