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

概述

当一个任务大到单个 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 一起干"。真正的差异藏在谁持有计划和中间结果落在哪里这两件事上。官方文档用一张表把四原语一次性讲透：

这张表的核心洞察是：子代理、技能、团队里，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/）。也可以直接手写文件，例如一个"迁移工人"子代理：

---
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 或环境变量里加：

{
  "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 里设：

{ "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 提示你保留还是删除。保留的话目录和分支都在，下次还能回来。

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

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

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：

---
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 步：合并与验收

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

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 — 动态工作流的官方权威说明，含四原语对比表与 v2.1.154 版本要求
2. Orchestrate teams of Claude Code sessions — Claude Code Docs — 智能体团队架构、实验开关与 v2.1.178 行为变更
3. Create custom subagents — Claude Code Docs — 子代理 frontmatter 定义、内置 Explore/Plan/general-purpose 与模型路由
4. Isolate sessions with worktrees — Claude Code Docs — --worktree、.worktreeinclude、worktree.baseRef 与子代理工作树隔离
5. Claude Code Subagents: Parallel Multi-Agent Workflows — turion.ai — 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 等场景全覆盖。