Claude Code SDK #20：并行 Agent 架构全解——Sub-agents × Agent Teams × Dynamic Workflows × Agent View，四种方案选哪个？

你有一个耗时任务需要 Claude 来完成——搜索几十个代码文件、同时调查三条 bug 假设、把五百个文件逐一迁移到新格式。单个 session 跑太慢，上下文窗口也早就撑不住了。Claude Code 为此提供了四种并行 Agent 方案，但选错了不仅不省时，还会让 token 烧得更快。

这四套机制分别是：Sub-agents（一个会话里的专用子 Agent）、Agent Teams（多个 Claude 实例互相协作）、Dynamic Workflows（Claude 生成脚本来调度大规模 Agent）和 Agent View（后台 Session 的统一监控视图）。它们解决的问题不同，选型条件也有明显差异。

四种方案对比速览

方案	协调者	工作者间通信	典型规模	Token 成本
Sub-agents	Claude（在单个 session 内）	只向主 Agent 汇报	少量专用任务	较低，结果压缩返回
Agent Teams	主 Claude 分配 + 队员自协调	队员互相发消息	数个并行 session	较高，每个队员独立实例
Dynamic Workflows	脚本（Claude 生成的 JS）	不通信，结果存变量	数十至数百个 Agent	视规模而定，有 1000 个 Agent 上限
Agent View	你（手动派发并监控）	不通信	按需，随时查看	视 session 数量而定

Sub-agents：单 Session 内的专用子 Agent

Sub-agent 是 Claude Code 里最常被无感使用的机制——很多时候 Claude 已经在悄悄用它了。2

三个内置 Sub-agent

Claude Code 预装了几个内置子 Agent，它们在适当时机会被自动调用：

内置 Agent	模型	工具	触发场景
Explore	Haiku（快速低延迟）	只读工具	需要搜索或理解代码库，不做修改
Plan	继承主 session	只读工具	Plan 模式下收集上下文
General-purpose	继承主 session	全部工具	需要又探索又修改的复杂多步任务

Explore 和 Plan 会跳过你的 CLAUDE.md 和 git status，目的是让「探索」这件事本身保持廉价。其余内置 Agent 和你自定义的 Sub-agent 都会正常加载。

Frontmatter 全字段

自定义 Sub-agent 是一个带 YAML frontmatter 的 Markdown 文件，正文即 system prompt。只有 name 和 description 是必填，其余都有默认行为：

---
name: code-reviewer          # 小写字母和连字符，全局唯一

Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash  # 省略 = 继承主 session 全部工具
disallowedTools: Write, Edit   # 黑名单（与 tools 同时设置时，先减后选）
model: sonnet                  # sonnet / opus / haiku / fable / inherit
permissionMode: acceptEdits    # default / acceptEdits / auto / dontAsk / bypassPermissions / plan
maxTurns: 20                   # 最多跑几个 agentic turn
skills:                        # 预加载 Skill，全文注入上下文
  - api-conventions
mcpServers:                    # 给子 Agent 单独配 MCP 服务器
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
hooks:                         # 生命周期 Hook，仅在该 Agent 活跃时生效
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
memory: project                # user / project / local，持久化学习目录
background: false              # true = 始终后台运行
effort: high                   # 覆盖 session 的 effort 级别
isolation: worktree            # worktree = 在独立 git worktree 运行
color: cyan                    # 在任务列表里的显示颜色
initialPrompt: "..."           # --agent 启动时自动提交的首个用户消息
---

模型解析优先级（高 → 低）：CLAUDE_CODE_SUBAGENT_MODEL 环境变量 → 本次调用传入的 model 参数 → frontmatter 里的 model → 主 session 的 model。

tools vs disallowedTools 的组合逻辑

两个字段同时设置时，disallowedTools 先执行（从继承的工具池里移除），再用 tools 做白名单过滤。一个工具出现在两个字段里，最终被移除。

Agent(agent_type) 语法可以精确控制这个 Sub-agent 能派生哪些子 Agent：

tools: Agent(worker, researcher), Read, Bash

只允许派发 worker 和 researcher 类型。如果省略括号直接写 Agent，则不限类型。如果完全不写 Agent，该子 Agent 就无法再派发下一级。

Forked Sub-agent：继承完整上下文

普通 Sub-agent 总是从空白上下文出发——它拿到的只有 Claude 在委托时写的任务描述。Fork 改变了这件事：Fork 会继承父 session 的完整对话历史、system prompt、工具集和模型，因此不用再解释背景。2

用 /fork 命令手动触发：

/fork draft unit tests for the parser changes so far

Fork 在后台运行，结果作为消息返回主 session。因为共享 prompt cache，第一次请求几乎不产生额外的 prefill 成本。

Fork 与命名 Sub-agent 的关键差异：

维度	Fork	命名 Sub-agent
上下文	继承完整对话历史	只有委托时的任务 prompt
System prompt	与主 session 相同	来自定义文件
权限提示	出现在你的终端	后台运行时自动拒绝
Prompt cache	与主 session 共享	独立缓存

嵌套 Sub-agent（v2.1.172+）

从 v2.1.172 开始，Sub-agent 可以再派发自己的 Sub-agent。场景举例：一个 reviewer Sub-agent 每找到一个问题，就派发一个 verifier Sub-agent 来验证修复。中间层的详细输出永远不会到达你的主 session，只有最顶层 Sub-agent 的摘要返回给你。

前台 Sub-agent 可以无限嵌套（但实际会自我收敛，因为每层都要等待下一层）；后台 Sub-agent 最多嵌套 5 层，超出的层数拿不到 Agent 工具，无法继续派发。

Agent Teams：多个 Claude 实例的协作网

Agent Teams 是实验性功能，默认关闭。需要在 settings.json 里手动启用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Sub-agents vs Agent Teams

两个机制的核心区别在于队员之间能否直接通信：Sub-agents 只向主 Agent 汇报结果，队员之间没有横向联系；而 Agent Teams 的每个队员都是独立的 Claude Code session，它们共享任务列表，可以互相发消息、争论假设、分工认领任务。

维度	Sub-agents	Agent Teams
上下文	各有独立窗口，结果返回主 Agent	各有独立窗口，完全独立
通信	只汇报给主 Agent	队员互相发消息
协调	主 Agent 全权管理	共享任务列表，自主认领
适合场景	只需要结果的聚焦任务	需要讨论和协作的复杂任务
Token 开销	较低	较高（每个队员是独立 Claude 实例）

启动一个 Agent Team

直接用自然语言告诉 Claude：

I'm designing a CLI tool that helps developers track TODO comments
across their codebase. Create an agent team to explore this from
different angles: one teammate on UX, one on technical architecture,
one playing devil's advocate.

Claude 会创建团队、派发队员、协调工作，最后综合结果。

几个实用操作：

Shift+Down 在队员之间切换，直接给任意一个队员发消息
--teammate-mode in-process 或 tmux 分屏两种显示模式
让队员使用你预定义的 Sub-agent 类型（复用 tools 和 model 配置，system prompt 附加在队员 prompt 后）

Hooks 质量门禁

Agent Teams 有三个专属 Hook 事件可以实现质量门禁，exit code 2 会阻止操作并把反馈发回 Agent：

Hook 事件	触发时机	exit 2 效果
`TeammateIdle`	队员即将进入空闲	发反馈，队员继续工作
`TaskCreated`	任务即将被创建	阻止任务创建
`TaskCompleted`	任务即将被标记完成	阻止完成，发反馈要求修改

Dynamic Workflows：脚本驱动的大规模 Agent 调度

当一个任务超出了几个 Sub-agent 能处理的范围——比如审查整个代码库、迁移 500 个文件、从多角度交叉验证研究结论——就该考虑 Dynamic Workflows 了。

核心区别在于「谁来持有计划」：用 Sub-agents 和 Agent Teams 时，Claude 在每一轮对话里即兴决定下一步；Dynamic Workflow 把整个编排逻辑写进一段 JavaScript 脚本，由 runtime 执行。中间结果存在脚本变量里，不占用 Claude 的上下文窗口。

四种多 Agent 方案的横向对比

维度	Sub-agents	Skills	Agent Teams	Workflows
计划由谁持有	Claude，逐轮决定	Claude，按 prompt 执行	主 Agent，逐轮决定	脚本
中间结果存在哪	Claude 上下文	Claude 上下文	共享任务列表	脚本变量
可复用的单元	Worker 定义	指令	团队定义	编排脚本本身
规模	每轮几个委托	同 Sub-agents	数个长期运行的 peer	每次运行数十至数百个
中断恢复	重新开始这一轮	重新开始这一轮	队员保持运行	在同一 session 内可恢复

触发 Workflow 的三种方式

方式一：在 prompt 里加 ultracode 关键词（或直接说"use a workflow"）：

ultracode: audit every API endpoint under src/routes/ for missing auth checks

方式二：/effort ultracode，让 Claude 对本 session 里的每个实质性任务都自动选用 Workflow。

方式三：运行内置的 /deep-research，这是 Claude Code 预置的 Workflow，专门用来多角度展开网络搜索、交叉核验来源、最终生成带引用的报告。

保存并复用 Workflow

运行完一次后，如果你觉得这个编排逻辑以后还用得上，在 /workflows 里选中这次运行，按 s 保存：

保存到 .claude/workflows/：团队共享，随仓库一起入版本控制
保存到 ~/.claude/workflows/：个人全局，仅自己可用

保存后可以在任何 session 里直接用 / 命令触发，并通过 args 参数传入不同输入（比如指定不同目标路径）。

上限与约束

单次 run 最多 1000 个 Agent，最多 16 个并发（受 CPU 核心数限制）
Workflow 本身不能直接读写文件或执行 shell 命令，只能通过派发的 Agent 间接操作
运行中不能暂停等待用户输入；需要分阶段审批的任务要拆成多个独立 Workflow

Agent 总上限（单次 run）

1000

最大并发 Agent 数

内置 Sub-agent 类型

后台嵌套最大深度

Loading stats card…

Agent View：后台 Session 的统一监控视图

前三种方案都以「Claude 来协调」为前提；Agent View 则是为「你自己来协调」设计的。它提供一个全屏界面列出所有后台 session 的状态，不用再盯着每个终端窗口。

claude agents

Agent View 界面：session 按 Needs input / Working / Completed 分组，每行显示任务名称、当前活动摘要和时间 — Agent View 终端界面，1 个等待输入、1 个运行中、2 个已完成 5

每行显示一个 session 的状态图标、当前在做什么、上次更新时间。状态分六类：

状态	图标颜色	含义
Working	动态动画	Claude 正在运行工具或生成回复
Needs input	黄色	等待你回答一个问题或做权限决定
Idle	暗色	空闲，等待下一个任务
Completed	绿色	任务成功完成
Failed	红色	任务出错结束
Stopped	灰色	被手动停止

图标形状另外表示进程是否存活：✻/✽ 表示进程在运行、可以即时响应；∙ 表示进程已退出，但 attach 后会自动从断点恢复。

三个核心操作

Peek（快速预览）：按 Space 打开 Peek 面板，查看最新输出或等待的问题，直接回复无需 attach。
Attach（接管）：按 Enter 或 → 进入完整 session，按 ←（空提示符时）退出回 Agent View。
Background（发送到后台）：在任意 session 里按 ←（空提示符）就能把它发到后台，在 Agent View 里显示为一行。

后台 session 依赖一个 supervisor 进程维持运行，即使你关闭了 Terminal 窗口，session 依然在执行。机器休眠再唤醒后 supervisor 会重新连接。只有彻底关机才会停止运行中的 session。

选型决策框架

四种方案的触发条件可以归结成两个维度：工作者之间是否需要通信，以及任务规模。

工作者不需要互相通信：

任务数量少、结果需要汇总回主 session → Sub-agents
任务完全独立、你想手动派发和监控 → Agent View
任务数量多（十个以上）、需要规模化且可重复 → Dynamic Workflows

工作者需要互相讨论、挑战对方的假设 → Agent Teams（Experimental）

另外，当任务的上下文背景已经在主 session 里讲清楚了，不想从头再解释一遍 → Fork Sub-agent（继承完整上下文）。

五条可落地的实践建议

建议一：用 description 字段精确控制委托时机

Claude 依赖 Sub-agent 的 description 来判断什么时候委托。写模糊的"通用工具"不会被精准触发；加上"Use proactively after code changes"这样的触发短语，Claude 就知道在哪个节点该用它。

建议二：先用 Sub-agent 隔离高流量操作

跑测试套件、批量抓取文档、解析大量日志——这类操作会产生海量输出。委托给 Sub-agent 后，详细内容在子 Agent 的上下文里消化，你的主 session 只收到摘要，省下大量 context token。

建议三：用 isolation: worktree 隔离可能冲突的文件操作

多个 Sub-agent 并行运行时，如果它们可能编辑相同的文件，加上 isolation: worktree，每个 Sub-agent 会在独立的 git worktree 里操作，不会互相覆盖。

建议四：Agent Teams 的队员越独立、收益越大

Agent Teams 的 token 消耗和协调开销都远高于 Sub-agents。只有当任务天然可以并行展开、且工作者之间需要真正互相讨论时才划算。如果任务实际上是串行的（每步都依赖上一步结果），团队模式不会让它更快。

建议五：用 /deep-research 验证 Workflow 的真实效果

在自己写 Workflow 之前，先跑一遍 /deep-research，感受 Workflow 的运行方式、进度视图和结果质量。确认适合你的场景后，再让 Claude 为具体任务生成专用 Workflow，并保存备用。