<!-- title: 多智能体四原语：任务怎么分工 -->

# 多智能体四原语：任务怎么分工

## 概述

当一个任务大到单个 Claude Code 会话装不下、或需要多人协作式的探索时，2026 版 Claude Code 给了你四把不同刻度的手术刀：**子代理（Subagent）、智能体团队（Agent Team）、动态工作流（Dynamic Workflow）、工作树（Worktree）**。本教程不是参数罗列，而是教你做一道决策题——拿到一个复杂任务后，如何在十分钟内判断"该用哪把刀、怎么组合"，并落地一个跨前后端的实战编排。适合已经熟悉单会话开发、想把 Claude Code 用到团队级吞吐的进阶开发者。

## 前置条件

- Claude Code **v2.1.178 及以上**（智能体团队自动建/拆的版本；动态工作流需 v2.1.154+）
- 一个真实的 git 仓库（工作树与子代理隔离都依赖 git）
- 已跑通过至少一个 `-p` 非交互任务（即熟悉基础自动化）
- 对 token 成本有基本概念：多智能体会显著放大消耗，盲开团队模式很容易把预算烧穿

---

## 一、先建立心智模型：谁在持有"计划"

很多人上手多智能体的第一错误，是把它当成"多开几个 Claude 一起干"。真正的差异藏在**谁持有计划**和**中间结果落在哪里**这两件事上。官方文档用一张表把四原语一次性讲透：

| 原语 | 它是什么 | 谁决定下一步跑什么 | 中间结果放哪 | 规模 | 可否复用编排本身 |
|---|---|---|---|---|---|
| 子代理 Subagent | 一个由 Claude 派生的工人 | Claude 逐回合决定 | Claude 的上下文 | 每回合几次派发 | 工人定义可复用 |
| 技能 Skill | Claude 遵循的指令 | Claude 按提示走 | Claude 的上下文 | 同子代理 | 指令可复用 |
| 智能体团队 Agent Team | 一个主管 + 若干对等会话 | 主管逐回合调度 | 共享任务清单 | 数个长时间对等体 | 团队定义可复用 |
| 动态工作流 Workflow | 运行时执行的一段脚本 | **脚本本身** | 脚本变量 | 单次数十到上百代理 | **编排本身可复用** |

这张表的核心洞察是：**子代理、技能、团队里，Claude 才是编排者**，每个结果都回流进某个上下文窗口；而**工作流把计划搬进了代码**——循环、分支、中间结果全在脚本里，Claude 的上下文最终只拿到答案。这条分界线，决定了你该选谁。

> 一句话记法：**要让 Claude 临场调度 → 团队/子代理；要把编排固化成可重跑的资产 → 工作流；要让文件改动不互相打架 → 工作树。**

## 二、第一把刀：子代理（Subagent）

子代理是粒度最小的并行单元。它跑在**自己的上下文窗口**里，有专属系统提示、受限的工具集、独立的权限，干完活只把摘要交回主会话。最适合"会污染主对话"的脏活——满屏搜索结果、巨型日志、你之后再也不想引用的文件内容。

### 内置子代理

Claude Code 自带三个主力，理解它们的分工就理解了子代理的设计哲学：

- **Explore**：模型是 Haiku，只读工具（Write/Edit 被禁）。用于文件发现、代码搜索、仓库探索。Claude 会指定粒度：`quick` 定点查找、`medium` 均衡、`very thorough` 全面铺开。
- **Plan**：模型继承主对话，只读。规划模式下，Claude 把代码调研丢给它，让探索输出留在独立窗口，主对话保持只读。
- **general-purpose**：模型继承主对话，全工具。用于既要探索又要动手、或多步依赖的复杂任务。

一个关键细节：**Explore 和 Plan 会跳过你的 CLAUDE.md 和父会话 git 状态**，这是它们又快又便宜的根源；其它子代理（含自定义）会加载这两者。

### 创建自定义子代理

定义就是一份带 YAML frontmatter 的 Markdown 文件。最快的方式是命令式：

```
/agents
```

切到 **Library** 标签 → **Create new agent** → 选 **Personal**（存到 `~/.claude/agents/`）。也可以直接手写文件，例如一个"迁移工人"子代理：

```markdown
---
name: migrator
description: 把指定目录下的 CommonJS 文件改写为 ESM，逐文件处理，返回改动清单。
model: haiku
tools: Read, Edit, Grep, Glob
isolation: worktree
---

你是一个专注的迁移工人。规则：
1. 只处理调用方指定的目录，绝不越界。
2. 每个文件：require → import、module.exports → export。
3. 改完即停，不要跑测试、不要碰 package.json。
4. 返回 JSON：{"files": [...], "notes": "..."}。
```

这里有两个高频踩坑点要特别说明：

**踩坑一：`description` 是触发器。** Claude 完全靠这段文字决定何时把任务派给子代理。描述含糊，它就永远不会被调用。务必写"它擅长什么 + 何时该用"。

**踩坑二：`isolation: worktree` 让每个子代理拿到临时工作树。** 这样多个并行子代理同时改文件不会互相覆盖，结束后无改动的工作树会自动清理。没有这一行，并行子代理就是在同一个工作区里抢方向盘。

### 常见问题

- **自定义子代理从不被触发** → 八成是 description 写成了"我是 X 工程师"这种自我介绍，而不是"当需要做 Y 时调用我"。改成任务导向。
- **想彻底禁用子代理** → 在 `permissions.deny` 里 deny 掉 `Agent` 工具；只禁某个内置类型，就把类型名加进 `deny`。
- **SDK / 非交互模式想只用自定义** → 设 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`，内置类型全部消失，只剩你提供的。

## 三、第二把刀：智能体团队（Agent Team）

当任务需要**多个会话互相通信**时，子代理就不够用了——子代理只能"干完汇报"，不能"互相对话"。团队模式解决的就是这个。

### 启用

团队模式仍是**实验特性、默认关闭**。在 `settings.json` 或环境变量里加：

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

不设这个变量，启动时不会建任何团队、不写团队目录、Claude 也不会提议或派生队友。**v2.1.178 起**，派生队友不再需要前置 setup 步骤，会话退出时自动清理；旧版本的 `TeamCreate`/`TeamDelete` 工具已删除，`Agent` 工具上的 `team_name` 入参虽被接受但被忽略。

### 架构与用法

一个会话当**主管（lead）**，负责协调、派活、综合结果；其余是**队友（teammate）**，各自独立上下文，可以直接互相通信，你也可以绕过主管直接和某个队友对话。队友间共享一个任务清单。

它最发光的场景，官方点名的四类：

- **研究与评审**：多个队友同时调查问题的不同侧面，再互相质疑结论。
- **新模块/新功能**：每个队友认领一块，互不踩脚。
- **竞争假设调试**：并行验证不同理论，更快收敛。
- **跨层协作**：前端、后端、测试各由一个队友负责。

而它**不该用**的场景同样要记住：串行任务、同文件编辑、依赖密集的工作——这些用单会话或子代理更划算。团队模式会引入协调开销，且**显著吃 token**。

### 质量门与管控

团队可以挂 hooks 当质量闸门：比如所有队友提交前必须过一遍 lint/test。你还可以指定队友用哪个模型（研究用便宜快的、关键改动用强模型）、要求队友先出计划再动手、直接给某个队友派活或让它认领任务、随时关停队友。使用时盯紧 `/workflows` 风格的进度面板，及时纠偏。

### 常见问题

- **队友不出现** → 确认实验开关已生效，且版本 ≥ v2.1.178。
- **权限提示刷屏** → 给团队预配好 `permissions.allow`，否则每个队友的工具调用都会打断。
- **主管在活没干完前就收尾** → 明确要求"等待所有队友完成后再综合"，并设好完成判定。
- **遗留 tmux 会话** → 这是已知的清理边界问题，退出后手动检查是否有孤儿会话。

## 四、第三把刀：动态工作流（Dynamic Workflow）

当任务**大到单次对话协调不过来**，或者你希望把编排本身**固化成可读、可重跑的脚本**时，就该上工作流了。它需要 **v2.1.154+**，所有付费计划、Anthropic API、Bedrock、Vertex AI、Microsoft Foundry 都支持；Pro 用户在 `/config` 的 **Dynamic workflows** 行开启。

### 它到底是什么

一段 **JavaScript 脚本**，由运行时在后台执行，编排大量子代理；你的会话保持响应。典型场景：全仓库 bug 扫描、500 文件迁移、需要多源交叉核验的研究、值得从多个独立角度起草再择优的硬核方案。

它和前三者的本质区别再强调一次：**计划在代码里**。子代理/技能/团队是 Claude 临场当编排者，结果都进上下文；工作流脚本自己持有循环、分支、中间结果，Claude 的上下文只拿到最终答案。正因为计划成了代码，工作流还能套用**可重复的质量模式**——比如让独立代理互相对抗式评审对方的发现，或从多个角度起草方案再相互权衡，得到比单次更可信的结果。

### 上手：先跑内置的

最快的体感来自内置工作流 `/deep-research`，它跨多个角度扇出搜索、抓取并交叉核验来源、综合成带引用的报告：

```
/deep-research Node.js v20 到 v22 的权限模型到底改了什么？
```

Claude Code 会问是否允许该工作流，选 Yes。随后后台开跑，前台依然空闲。用 `/workflows` 查看进度，方向键选中某次运行回车，进入分阶段视图：每个阶段的代理数、token 总量、耗时一目了然，钻进任一阶段能看到每个代理发现了什么。任务面板里也有一行进度摘要，下方向键聚焦、回车展开。结束后报告落回会话，未通过交叉核验的论断已被过滤。

### 让 Claude 写你的工作流

四种触发方式，由轻到重：

1. **在提示里直接要**："给这个迁移任务写一个工作流。"
2. **让 Claude 自己判断（ultracode 模式）**：开启后，Claude 会自主决定何时该上工作流。
3. **先批计划再跑**：在权限模式下要求先出计划，你点头它才执行。
4. **存下来复用**：某次运行达预期后，把它存成你自己的命令；下次带输入直接重跑。

### 常见问题

- **运行卡住 / 中断** → 工作流可在**同一会话内断点续跑**（resume），这是它相对团队模式的一大优势。
- **成本失控** → 工作流可能单次起几十上百代理。先用小规模跑通脚本骨架，确认扇出逻辑再放大。
- **想关掉** → 直接在 `/config` 关闭，或不在提示里触发。

## 五、第四把刀：工作树（Worktree）——所有并行的"地基"

前三把刀解决的是"工作怎么协调"，工作树解决的是"文件改动怎么不冲突"。它是并行的隔离层，可以叠加在子代理、团队之上。**注意：工作树需要 git 仓库。**

### 命令式开隔离会话

```
claude --worktree feature-auth      # 简写 -w
claude --worktree bugfix-123        # 另一个终端再开一个
claude --worktree                   # 不起名则自动生成，如 bright-running-fox
claude -p --worktree                # 非交互模式，跳过信任检查
```

默认在仓库根的 `.claude/worktrees/<value>/` 建工作树，分支名 `worktree-<value>`。**务必把 `.claude/worktrees/` 加进 `.gitignore`**，否则会冒出一堆未跟踪文件。首次在某目录交互式用 `--worktree` 前，需先在该目录跑一次 `claude` 接受工作区信任弹窗；`-p` 非交互会跳过这个检查。

### 选基线分支

工作树默认从 `origin/HEAD`（远程默认分支）拉，保证干净起点。无远程或拉取失败时回退到本地 HEAD。想永远从本地 HEAD 拉（带上你未推送的提交和功能分支状态），在 settings 里设：

```json
{ "worktree": { "baseRef": "head" } }
```

只接受 `"fresh"` 或 `"head"`，不接受任意 git ref。从某个 PR 拉：

```
claude --worktree "#1234"           # 也会接受完整 GitHub PR URL
```

### 带上 gitignored 文件

工作树是全新检出，主仓库里 `.env` 这类未跟踪文件不会出现。在项目根加一个 `.worktreeinclude`（`.gitignore` 语法），它只复制"既匹配模式、又确实被 gitignore"的文件——绝不会复制已跟踪文件：

```
.env
.env.local
config/secrets.json
```

这条对 `--worktree`、子代理工作树、桌面端并行会话都生效。

### 给子代理套工作树

除了子代理 frontmatter 里的 `isolation: worktree`，也可以在对话里直接说"给你的代理用工作树"。每个子代理拿到临时工作树，无改动时自动清理。

### 清理规则

退出工作树会话时：无任何改动/未跟踪文件/新提交 → 自动删除；有改动 → Claude 提示你保留还是删除。保留的话目录和分支都在，下次还能回来。

## 六、决策框架：四把刀怎么选

把上面的零散点收拢成一张可照着走的决策图。拿到任务后，依次问自己：

```mermaid
flowchart TD
    A[复杂任务] --> B{需要多个会话互相对话吗？}
    B -->|是，要互相质疑/协作| C[Agent Team 智能体团队]
    B -->|否| D{任务是重复的、规模大、要可重跑吗？}
    D -->|是，几十上百单元| E[Dynamic Workflow 动态工作流]
    D -->|否，少量派发| F{要不要隔离文件改动？}
    F -->|要，并行改文件| G[Subagent + worktree]
    F -->|不要，只读探索| H[内置 Explore/Plan 子代理]
    C --> I[叠加 worktree 防冲突]
    E --> I
    G --> I
```

三条经验法则：

1. **默认从子代理起步。** 大多数"任务有点大"的情况，一两个带 worktree 的子代理就够了，开销最低。
2. **要"对话"才上团队。** 团队的价值在队友互相沟通与质疑，纯并行的活用工作流或子代理更省。
3. **要"可重跑的资产"才上工作流。** 一次性任务别写脚本；要反复执行的迁移/审计/研究，工作流的脚本化才划算。

## 七、实战案例：把 ticket-api 从 JS 迁到 TS 并补测试

这是一个真实的中型仓库：Express 写的工单 API，约 40 个路由文件、20 个数据访问层、测试覆盖不足。单会话跑会撑爆上下文。我们用三把刀分层处理。

### 第 1 步：先让内置子代理摸清家底

进会话第一句，把"探索"丢给只读的 Explore，主上下文只收摘要：

```
> 用 very thorough 粒度探索 src/ 下所有路由与数据访问层，给我一份按"改造成本"排序的文件清单和依赖图，不要把文件全文贴回来。
```

Explore（Haiku、只读）跑完，你拿到的是结构化清单而非 40 个文件的原文——这就是子代理"保上下文"的价值。

### 第 2 步：定义迁移工人子代理（带 worktree）

`~/.claude/agents/ts-migrator.md`：

```markdown
---
name: ts-migrator
description: 把单个 .js 文件改写为 .ts（加类型注解、换 import 风格），用于批量 TS 迁移。调用方给出文件路径。
model: sonnet
tools: Read, Edit, Glob, Grep
isolation: worktree
---

规则：
1. 只处理调用方指定的单个文件，绝不连带改动其它文件。
2. 为函数参数与返回值加类型；无法确定的类型用 unknown 并标注 TODO。
3. 保留原有逻辑与命名，不做重构优化。
4. 返回 JSON：{"file": "...", "todos": ["..."]}。
```

注意 `isolation: worktree`：每个 ts-migrator 在自己的工作树里改，多个并行不冲突。

### 第 3 步：迁移主体——交给动态工作流做批量扇出

40 个文件逐个派子代理既慢又难管，这正是工作流的舞台。提示 Claude 写一个：

```
> 写一个动态工作流：用 pipeline 模式，把这 40 个 .js 文件喂给 ts-migrator 子代理（每个带 worktree），改完后再让一个只读的 reviewer 子代理逐个对抗式检查"是否破坏原有逻辑"。先出计划等我批。
```

Claude 产出脚本，你审过计划再放行。后台 `/workflows` 里能看到分阶段进度：迁移阶段 40 个代理、审查阶段再 40 个，未通过审查的会被标出来。脚本里循环和分支自己持有，你的主上下文只拿到最终的"通过/待修"汇总——这就是"计划在代码里"的体感。

> **成本护栏**：先在 5 个文件上跑通脚本骨架，确认扇出与对抗审查的逻辑无误，再放开到 40 个。工作流单次可能起几十上百代理，骨架验证能避免一次性烧掉一周预算。

### 第 4 步：跨层补测试——上智能体团队

迁移改了类型，测试要重写，还要加新覆盖。这部分有三个互相依赖的面（类型定义、路由实现、测试），且需要互相校对，适合团队模式。开启 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` 后：

```
> 组一个三人团队：types-mate 负责统一类型定义与共享 schema，impl-mate 负责按新类型修路由实现，test-mate 负责补单测。三者要互相校对：types-mate 改了 schema 要通知 impl-mate，impl-mate 改了签名要通知 test-mate。最后主管综合一份覆盖报告。
```

团队的价值在这步兑现——队友间能直接通信、共享任务清单、互相质疑。注意给团队预配好 `permissions.allow`，否则每个队友的工具调用都会打断你；并要求"等所有队友完成后再综合"。

### 第 5 步：合并与验收

子代理和团队的改动都在各自工作树/分支上。逐个验收：

```mermaid
flowchart LR
    subgraph 探索["第1步 探索(只读子代理)"]
        E1[Explore 摸家底]
    end
    subgraph 迁移["第2-3步 批量迁移(工作流)"]
        W1[ts-migrator×40 worktree] --> R1[reviewer 对抗审查]
    end
    subgraph 补测["第4步 跨层补测(团队)"]
        T1[types-mate] <--> T2[impl-mate]
        T2 <--> T3[test-mate]
        T1 <--> T3
    end
    探索 --> 迁移 --> 补测 --> M[主管综合 + 逐分支验收合并]
```

关键纪律：**研究/探索永远先于动手**；**每个并行单元都不越界**（靠 `isolation: worktree` + 受限 tools 强制）；**对抗式审查兜底**（工作流里的 reviewer、团队里的互校）。

## 八、踩过的坑与避坑清单

- **开团队却只用来跑串行任务** → 协调开销远超收益。串行、同文件、依赖密集，留给单会话。
- **子代理 description 写成简历** → 永远不被触发。写成"何时该调用我"。
- **工作流不设成本护栏直接全量** → 一次跑飞烧光预算。先骨架后放量，盯 `/workflows` 的 token 列。
- **忘了 `.gitignore` 里加 `.claude/worktrees/`** → 主仓库被未跟踪文件淹没。
- **工作树里缺 `.env`** → 加 `.worktreeinclude`，别手动拷。
- **想禁子代理却不知道开关** → deny `Agent` 工具，或 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`。

## 延伸阅读

- Claude Code 官方文档「Agents and parallel work」总览页，是四原语导航的入口。
- `/deep-research` 内置工作流的源码思路：研究类任务的扇出 + 交叉核验范式，可直接迁移到自己的工作流。
- 官方「Run agents in parallel」对比页，把 subagents / agent teams / background sessions / worktrees 的边界讲得最清楚。
- 社区对 orchestrator/worker 模式与 context-isolation 的实测分析（见参考来源），补足了 token 实测数据。

## 训练营适用性评估

- **适用类型**：进阶工程师训练营、AI 研发效能营、团队级 AI 工程化课程。**不适合**零基础营——需要先掌握单会话开发与 `-p` 自动化。
- **教学时长**：建议 **3–4 学时**。1 学时讲四原语决策模型 + 内置子代理；1 学时做子代理 + worktree 动手；1 学时跑 `/deep-research` 并让学员写一个自己的小工作流；剩余时间做团队模式实战案例。
- **考核建议**：给学员一个中型真实仓库，要求其提交一份"四原语选型说明 + 至少一种多智能体编排的落地记录"，重点评决策是否合理、成本是否受控。

## 参考来源

1. [Orchestrate subagents at scale with dynamic workflows — Claude Code Docs](https://code.claude.com/docs/en/workflows) — 动态工作流的官方权威说明，含四原语对比表与 v2.1.154 版本要求
2. [Orchestrate teams of Claude Code sessions — Claude Code Docs](https://code.claude.com/docs/en/agent-teams) — 智能体团队架构、实验开关与 v2.1.178 行为变更
3. [Create custom subagents — Claude Code Docs](https://code.claude.com/docs/en/subagents) — 子代理 frontmatter 定义、内置 Explore/Plan/general-purpose 与模型路由
4. [Isolate sessions with worktrees — Claude Code Docs](https://code.claude.com/docs/en/worktrees) — `--worktree`、`.worktreeinclude`、`worktree.baseRef` 与子代理工作树隔离
5. [Claude Code Subagents: Parallel Multi-Agent Workflows — turion.ai](https://turion.ai/blog/claude-code-multi-agents-subagents-guide/) — Task 工具与并行子代理的社区实测与编排模式分析

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)