# 子智能体与并行：一个人带一支队伍

> 用子智能体把查资料、跑测试这类「脏活」隔离在独立上下文里，用 .claude/agents/ 定义可复用的专家，再用 git worktree、后台会话和 agent view 让多个 Claude 同时干活又互不踩脚。

- 网址：https://coding.chengyu.dev/learn/claude-code/subagents-parallel/
- 学习路径：Claude Code 精通
- 预计用时：25 分钟；核实日期：2026-10-25
- 官方来源：[Create custom subagents（Claude Code 官方文档）](https://code.claude.com/docs/en/sub-agents)，[Run agents in parallel（Claude Code 官方文档）](https://code.claude.com/docs/en/agents)，[Run parallel sessions with worktrees（Claude Code 官方文档）](https://code.claude.com/docs/en/worktrees)，[Manage multiple agents with agent view（Claude Code 官方文档）](https://code.claude.com/docs/en/agent-view)，[Orchestrate teams of Claude Code sessions（Claude Code 官方文档）](https://code.claude.com/docs/en/agent-teams)，[Common workflows（Claude Code 官方文档）](https://code.claude.com/docs/en/common-workflows)

## 学习目标

- 能判断一个任务该放在主对话里做，还是交给子智能体
- 能在 .claude/agents/ 下写出一个工具受限的自定义子智能体，并显式调用它
- 能用 claude --worktree 开出互不干扰的并行会话，并知道它默认从哪个分支切出
- 能说出后台会话、agent view、agent teams 各自适合的场景

你让 Claude 排查「订单列表接口为什么慢」。它翻了三十多个文件，跑了几轮 SQL 日志分析，终于找到原因。可接下来让它动手改时，你发现它开始忘记你一开始交代的约束——上下文已经被那些搜索结果和日志塞满了（上下文为什么会「满」，见[第 4 课](/learn/claude-code/context/)）。

另一个场景：线上有个紧急 bug 要修，手头的新功能又不想停。两件事挤在同一个目录、同一个会话里，改动很容易搅在一起。

这一课讲两种「分身」：**子智能体**解决上下文被污染的问题，**worktree 和后台会话**解决多件事同时做的问题。

## 子智能体：派个助手去干脏活

子智能体（subagent）是主对话派出去的助手。它有**自己独立的上下文窗口**、自己的系统提示词、自己的工具权限。它在自己的窗口里读文件、跑命令，干完只把一份摘要交回主对话。中间那几十次搜索和几千行日志，都不会进入你的主上下文。

代价也要心里有数：子智能体从零开始，要花时间重新了解情况；它的请求和你的主对话计入同一份用量额度；派出很多个、每个都回一大段报告，主上下文照样会被撑大。

Claude Code 自带几个内置子智能体，平时由 Claude 自动选用：

| 名称 | 能做什么 | 典型用途 |
|---|---|---|
| Explore | 只读（禁止 Write 和 Edit），按快速 / 中等 / 非常彻底三档搜索 | 在大仓库里找代码、理解结构 |
| Plan | 只读 | 计划模式下替主对话收集信息 |
| general-purpose | 全部可用工具 | 既要探索又要修改的多步骤任务 |
| 其他辅助 | `claude`（兜底通用型）、`statusline-setup`、`claude-code-guide` 等 | 由特定场景自动触发 |

## 自定义子智能体：写一个文件就是一个专家

当你发现自己总在用同样的话派同一类活，就该把它固化成文件了。子智能体就是一个带 YAML frontmatter 的 Markdown 文件：

| 位置 | 作用范围 |
|---|---|
| `.claude/agents/` | 当前项目，建议提交进仓库与团队共享 |
| `~/.claude/agents/` | 你的所有项目 |
| `--agents` 命令行参数（JSON） | 仅本次会话，适合脚本和临时测试 |

同名时，项目级优先于用户级；组织托管的定义优先级最高，插件提供的最低。

下面是一个贴近国内前端项目的例子：一个只读的「国际化检查员」，专门找 Vue 组件里没走 i18n 的硬编码中文。

```markdown
---
name: i18n-auditor
description: 检查 Vue/TS 代码中未经 i18n 处理的硬编码中文文案。在新增或修改页面组件后主动使用。
tools: Read, Grep, Glob
model: haiku
---

你是前端国际化检查员。收到任务后：
1. 用 Grep 在指定目录的 .vue 和 .ts 文件中查找中文字符；
2. 排除注释、console 日志和 locales 目录下的语言包；
3. 对每处疑似硬编码，给出「文件:行号、原文、建议的 i18n key」；
4. 只报告，不修改任何文件。最后按文件汇总数量。
```

几个要点：

- **只有 `name` 和 `description` 必填**。`description` 决定 Claude 什么时候自动派它，写清「做什么、何时用」，加上「主动使用」之类的字眼会让它更积极地被调用。
- **`tools` 是白名单**，不写就继承全部工具。审查、检查类的子智能体一定要收紧，这既是安全，也是让它专注。
- **`model`** 可选 `sonnet`、`opus`、`haiku`、`inherit` 或完整模型 ID。机械性的扫描用便宜的模型就够了。
- 其他常用字段：`disallowedTools`（黑名单）、`permissionMode`、`maxTurns`、`skills`（预加载 Skill，见[第 5 课](/learn/claude-code/skills/)）、`mcpServers`、`hooks`、`isolation`。字段名区分大小写、用驼峰写法，**拼错不会报错，只会被静默忽略**。

调用方式有三档：在提示词里点名（「用 i18n-auditor 检查一下 src/views」），由 Claude 决定是否委派；输入 `@` 从列表里选中它，或直接写 `@agent-i18n-auditor`，保证这次一定由它执行；`claude --agent i18n-auditor` 则让整个会话都以它的身份运行。

> **/agents 命令变了**
>
> 新版本里 `/agents` 只会打印一句提示，让你直接让 Claude 创建子智能体，或手动编辑 `.claude/agents/` 和 `~/.claude/agents/`。旧教程里那个带 Running / Library 标签页的交互界面，只存在于 v2.1.197 及更早版本。保存文件后几秒内就会生效，只有在会话启动时 `agents` 目录还不存在的情况下才需要重启。

**前台还是后台？** 新版本里，Claude 从主对话派出的子智能体默认在**后台**运行：你可以继续聊别的，它需要权限时会在主会话里弹出提示并注明是哪个子智能体在问，完成后结果作为通知送回来。用 `/tasks` 可以查看、进入或停止后台的工作。如果你想让一个子智能体带着主对话的全部上下文去干支线任务，可以用 `/subtask 任务描述` 开一个「分叉」（fork），它不用你重新解释背景。

## 什么时候该用子智能体

| 用主对话 | 用子智能体 |
|---|---|
| 需要你频繁来回确认、反复调整 | 产出大量你之后不会再看的中间结果（日志、搜索结果） |
| 规划、实现、测试几个阶段共享大量上下文 | 想强制限制工具或权限，比如「只读审查」 |
| 一个小而明确的改动 | 工作边界清晰、最后交回一份摘要就够 |
| 对延迟敏感 | 几个互不依赖的调查可以同时进行 |

只是想就当前对话里的内容快速问一句，用 `/btw` 就行，不必派子智能体。

**并行派出三个子智能体做调研**

```text
订单列表接口 GET /api/orders 在数据量大时很慢，先不要改代码。请用三个子智能体并行调查，每个只返回结论和关键证据（文件:行号），不要贴大段原文：

1. 一个检查 controller 和 service 层，看有没有循环里查数据库（N+1）或不必要的全量加载；
2. 一个检查数据库层：相关表的索引、ORM 生成的 SQL、分页方式；
3. 一个检查缓存和中间件：有没有本该命中却失效的缓存、耗时的拦截器。

三份报告回来后，请你综合判断最可能的根因，按「收益 / 改动风险」排序给出修复方案，等我确认后再动手。
```

## 并行开发：用 worktree 隔开文件

子智能体解决的是上下文隔离，但它们默认和你共用同一份工作目录。要让两个 Claude 同时改代码而不互相覆盖，需要 **git worktree**：同一个仓库的另一个工作目录，有自己的文件和分支，共享提交历史和远程。

Claude Code 内置了这个能力：`claude --worktree 名字`（简写 `-w`）会在仓库根目录的 `.claude/worktrees/名字/` 下建一个 worktree，切出名为 `worktree-名字` 的新分支，并在里面启动会话。

```text
# 终端 1：继续做新功能
$ claude -w coupon-feature
# 终端 2：同时修线上 bug，互不干扰
$ claude -w fix-pay-callback
# 想基于某个 PR 继续改，可以直接从 PR 切出（记得加引号）
$ claude -w "#1234"
$ git worktree list
  ~/projects/shop-admin                                   3f2a9c1 [main]
  ~/projects/shop-admin/.claude/worktrees/coupon-feature    3f2a9c1 [worktree-coupon-feature]
  ~/projects/shop-admin/.claude/worktrees/fix-pay-callback  3f2a9c1 [worktree-fix-pay-callback]
```

用之前要知道的几件事：

- **默认从远程默认分支切出，不是从你当前的分支**。这是为了让 worktree 从干净的 `main` 开始。如果你需要带上本地未推送的提交，在 settings 里把 `worktree.baseRef` 设为 `"head"`。要从某个已有分支开始，就用 `git worktree add` 手动创建，再进去运行 `claude`。
- **worktree 是全新检出**，`.env` 这类被 gitignore 的文件不会自动带过去，`node_modules` 也要重新装。在项目根目录放一个 `.worktreeinclude`（语法同 `.gitignore`），列出要复制的文件，比如 `.env.local`。
- 把 `.claude/worktrees/` 加进 `.gitignore`，免得主目录里出现一堆未跟踪文件。
- **退出时会检查**：worktree 干净就自动删除；有改动或新提交会问你保留还是删除。删除会连同分支一起删掉，没提交的东西就没了。

子智能体也能各用一个 worktree：在定义文件里加 `isolation: worktree`，或直接对 Claude 说「给你的子智能体各开一个 worktree」。适合批量重构这种多个助手同时改不同文件的活。

## 更多并行方式：后台会话、agent view 与团队

官方目前把「同时做多件事」的方式分成几类，按你参与的程度由多到少：

| 方式 | 怎么用 | 适合 |
|---|---|---|
| 子智能体 | 主对话里自动或点名派出 | 一个会话内的支线任务 |
| 后台会话 + agent view（研究预览） | `claude --bg "任务"` 从 shell 派出；`claude agents` 打开总览；会话内 `/bg` 把当前会话转入后台 | 几件互相独立的任务，派出去后只在需要你时介入 |
| agent teams（实验性，默认关闭） | 设置环境变量 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 后，由一个负责人会话拆分任务、分派给队友，队友之间可以互发消息 | 需要多个会话协同推进的大任务 |
| `/batch`（内置 Skill） | `/batch 指令`，先出计划，确认后拆成 5 到 30 个各自在 worktree 里的后台子智能体 | 跨大量文件的机械性改造 |

后台会话有个贴心的设计：在 git 仓库里，它会在改文件前自动挪进自己的 worktree；完成后会提交，有远程就推送分支，必要时开草稿 PR，但**不会推送到 main 或 master，不会强推，也不会合并**。派出后，`claude attach 短ID` 接管、`claude logs 短ID` 看输出、`claude stop 短ID` 停止。如果你的 CLAUDE.md 写了「提交由我自己来」，它会照你的规矩办。

> **并行意味着成倍消耗**
>
> 每个子智能体、每个后台会话都在独立消耗用量。同时跑十个会话，额度大约以十倍速度消耗。先从两三个并行开始，确认收益大于审查成本再加。别忘了：并行产出的每一份改动，最后都要你来审。

> 小测：你在 feature-login 分支上有几个还没推送的提交，运行 claude -w login-tests 想基于这些改动补测试，却发现 worktree 里看不到你的新代码。最可能的原因是？

> 小测：下面哪个任务最适合交给子智能体，而不是在主对话里做？

- [ ] 在一个项目的 .claude/agents/ 下写一个只读子智能体（tools 只给 Read, Grep, Glob），并用 @agent-名字 显式调用一次
- [ ] 用上面的提示词让 Claude 并行派出三个子智能体调研一个问题，观察主对话里只收到了摘要
- [ ] 在会话里输入 /tasks，看看后台有哪些子智能体在跑或刚完成
- [ ] 用 claude -w 开两个 worktree 会话同时做两件事，结束后用 git worktree list 检查并清理
- [ ] 把 .claude/worktrees/ 加进 .gitignore，需要的话写一个 .worktreeinclude