用动态工作流大规模编排子智能体

动态工作流通过 Claude 编写的脚本编排大量子智能体，你可以重复运行该脚本。适用于代码库审计、大规模迁移和交叉核验调研。

动态工作流是一个 JavaScript 脚本，用于大规模编排子智能体。Claude 会为你描述的任务编写该脚本，由一个运行时在后台执行它，你的会话则保持可响应状态。

当一项任务需要的智能体数量超出单个对话能协调的范围，或者你想把编排过程固化为一份可以阅读和重新运行的脚本时，就可以使用工作流。典型场景包括全代码库范围的 bug 排查、涉及 500 个文件的迁移、需要多个来源相互交叉核验的调研问题，以及在下定决心之前，值得从多个独立角度起草的高难度计划。

何时使用工作流

子智能体、技能、智能体团队和工作流都可以运行一个多步骤任务。区别在于谁掌控这份计划：

工作流把计划移入代码中。对于子智能体、技能和智能体团队，Claude 是编排者：它逐轮决定接下来生成或分配什么，每个结果都会进入上下文窗口。而工作流脚本自身承载了循环、分支和中间结果，因此 Claude 的上下文中只留下最终答案。

把计划移入代码，还能让工作流应用一种可重复的质量保证模式，而不仅仅是运行更多智能体：它可以让独立的智能体在结果被报告之前互相进行对抗式审查，或从多个角度起草计划并互相权衡，从而获得比单轮处理更可信的结果。

运行一个打包好的工作流

要快速看到工作流的实际效果，最简单的方法是运行 /deep-research，这是 Claude Code 内置的打包工作流，用于跨多个来源调研一个问题。你会看到多个智能体在后台依次完成一系列阶段，而你的会话保持空闲，最终你会得到一份报告，而不是逐轮的记录。

/deep-research What changed in the Node.js permission model between v20 and v22?

/workflows

要为你自己的任务运行工作流，可以让 Claude 写一个，一旦某次运行达到了你想要的效果，你就可以把它保存为你自己的命令。

打包工作流

Claude Code 内置了 /deep-research 作为打包工作流：

你自己保存的工作流会以同样的方式成为命令，并与打包工作流一起出现在 / 自动补全列表中。

观察运行进度

工作流在后台运行，因此在智能体工作期间，会话保持可响应状态。随时运行 /workflows，即可列出正在运行和已完成的工作流，然后选中其中一个打开其进度视图。

/workflows

进度视图会显示每个阶段的智能体数量、Token 总量和已耗用时间。页脚会列出每个操作对应的按键：

让 Claude 写一个工作流

你可以用两种方式让 Claude 为你的任务写一个工作流：

• 在提示词中请求一个工作流，用你自己的话表达，或加入关键词 ultracode，Claude 就会为该任务写一个。
• 让 Claude 用 ultracode 自行决定：设置 /effort ultracode，Claude 会为该会话中每个实质性任务规划一个工作流。

你也可以运行一个已经存在的工作流命令：例如 /deep-research 这样的打包工作流，或你自己保存的工作流。

在提示词中请求一个工作流

要在不改变会话 effort 级别的情况下，将单个任务作为工作流运行，可在提示词中加入关键词 ultracode。用你自己的话表达也同样有效，例如“use a workflow”或“run a workflow”：Claude 会把直接的请求当作同样的一种主动选用。在 v2.1.160 之前，字面触发关键词是 workflow；自然语言请求在两个版本中都有效。

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

Claude Code 会在你的输入中高亮该关键词，Claude 会为该任务写一个工作流脚本，而不是逐轮处理它。如果你并非有意启动一个工作流，可以在 macOS 上按 Option+W，在 Windows 和 Linux 上按 Alt+W，取消这次提示的高亮，或者在光标恰好位于该高亮关键词之后时按退格键。要完全阻止该关键词触发，可在 /config 中关闭 Ultracode keyword trigger。

如果这次运行达到了你想要的效果，之后可以把它保存为一个命令。

如果你已经用其他方式搭建了一个编排器，例如一个存放子智能体提示词的文件夹，或一个能分派工作的技能，你可以让 Claude 参照它，请求一个实现同样效果的工作流。

让 Claude 用 ultracode 自行决定

Ultracode 是 Claude Code 的一项设置，它将 xhigh 推理 effort 与自动工作流编排结合在一起。开启后，Claude 会为每个实质性任务规划一个工作流，而不必等你提出请求。

/effort ultracode

要在启动会话时就已开启 ultracode，请用 claude --effort ultracode 启动。需要 Claude Code v2.1.203 或更高版本。

开启 ultracode 后，由 Claude 决定某个任务是否值得使用工作流。单次请求可能会连续触发多个工作流：一个用于理解代码，一个用于实施更改，一个用于验证。这适用于该会话中的每个任务，因此每次请求都会比更低 effort 级别消耗更多 Token、耗时更长。

Ultracode 只在当前会话中持续有效，启动新会话时会重置。回到日常工作时，用 /effort high 切回。它在支持 xhigh effort 的模型上可用；在其他模型上，/effort 菜单中不会提供该选项。

运行前批准计划

在 CLI 中，每次运行前的提示会显示计划中的各个阶段，以及以下选项：

• 是，运行它：开始该次运行
• 是，且以后不要再为 <path> 中的 <name> 询问：开始运行，并从现在起在该项目中跳过针对该工作流的这个提示
• 查看原始脚本：在决定之前先阅读脚本
• 否：取消

Ctrl+G 会在你的编辑器中打开该脚本。Tab 让你在运行开始前调整提示词。

你是否会看到这个提示，取决于你的权限模式：

在桌面应用中，一张批准卡片会显示工作流名称、阶段列表和 Token 用量提示，附带Once、Always 和 Deny 三个操作按钮。进度视图会出现在 Background tasks 侧边栏中。

你的权限模式只控制上面所述的启动提示。该工作流生成的子智能体始终以 acceptEdits 模式运行，并继承你的工具允许列表，无论你会话的模式是什么。文件编辑会被自动批准。

不在你允许列表中的 shell 命令、网页获取和 MCP 工具，仍可能在运行途中提示你。要在一次长时间运行中避免这种情况，可在开始前将这些智能体需要的命令加入你的允许列表。

在 claude -p 和 Agent SDK 中，没有人可以提示，因此工具调用会遵循你配置的权限规则，无需交互式确认。

保存工作流以便复用

当 Claude 为一个你会重复执行的任务写了一个工作流后，你可以把这次运行的脚本保存为一个命令。像“每个分支都要跑一次的审查”这样的流程，之后每次都会运行同样的编排过程。

运行 /workflows，选中你想保留的那次运行，按 s。在保存对话框中，Tab 可在两个保存位置之间切换：

• 项目中的 .claude/workflows/：与克隆该仓库的所有人共享
• 你主目录下的 ~/.claude/workflows/：在你的每个项目中都可用，只有你自己可见

按 Enter 保存。之后的会话中，该工作流会以 /<name> 的形式从这两个位置中的任一位置运行。

在拥有多个 .claude/ 目录的单体仓库中，你可以把工作流放在它适用的那个软件包旁边。从 v2.1.178 开始，保存到项目位置时，会写入你的工作目录与仓库根目录之间已经存在的最近的那个 .claude/workflows/ 目录，如果还不存在，则写入仓库根目录。项目工作流也会从这条路径上的每一个 .claude/workflows/ 加载，当多个目录定义了同一个名称时，Claude Code 会运行离工作目录最近的那个。

如果一个项目工作流和一个个人工作流同名，运行的是项目工作流。

向已保存的工作流传入输入

一个已保存的工作流可以通过 args 参数接收输入。该脚本会将其作为一个名为 args 的全局变量读取。可以用它在调用时提供一个调研问题、一份目标路径列表，或一个配置对象，而不必为每次运行编辑脚本。

以下提示词用一份 issue 编号列表运行一个已保存的工作流：

> Run /triage-issues on issues 1024, 1025, and 1030

Claude 会将该列表作为结构化数据传入，因此脚本可以直接对 args 调用数组和对象方法，而不必先解析它。如果省略了 args，脚本内该全局变量就是 undefined。

工作流提示词示例

当任务规模超出单个智能体上下文所能容纳的范围，或者同一个步骤需要在许多项目上重复运行时，工作流最为合适。下面的提示词展示了几种常见形态。每一条都是让 Claude 为该任务编写并运行一个工作流；你不需要自己编写脚本。

为同一个问题审查大量文件

为每个文件分派一个智能体，然后收集并核验发现。

> use a workflow to audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

持续修复直到检查通过

运行一个检查器，修复失败项，重复此过程，直到通过或不再有进展为止。

> use a workflow to run npx tsc --noEmit and keep fixing the reported errors until the type check passes or two rounds in a row make no progress

并行迁移大量文件

找出需要迁移的文件，在各自隔离的副本中转换每一个，避免编辑冲突，然后核验每个结果。

> use a workflow to migrate every component under src/components/ from styled-components to Tailwind, working on each file in its own isolated copy

审查每个变更文件并撰写一份汇总

为每个文件运行一个审查者，然后把所有发现交给一个智能体进行排序和去重。

> use a workflow to review every file changed in this PR for correctness issues, then merge the per-file findings into one ranked summary

跨多个来源调研一个主题

在多份更新日志、issue 和文档之间分派阅读者，然后综合结论。打包的 /deep-research 工作流正是这样做的；你也可以描述一个范围更窄的版本。

> use a workflow to research how our three competitors handle rate limiting: read their public docs and recent changelog entries in parallel, then compare the approaches

持续查找问题直到列表不再增长

持续分轮搜索，当新一轮不再发现新内容时停止。

> use a workflow to find flaky tests in this repo: run the suite repeatedly, record which tests fail intermittently, and stop once two rounds in a row find nothing new

已保存脚本的样子

当你保存一个工作流后，.claude/workflows/ 中的文件会包含一个 meta 块，随后是一段编排子智能体的脚本正文。你通常不需要编辑它，但下面展示了一个小型脚本的样子，方便你辨认 Claude 生成的内容：

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

脚本正文是使用顶层 await 的普通 JavaScript。agent() 生成一个子智能体，pipeline() 会为列表中的每一项各运行一个。如果你想手动编辑某个脚本，可以让 Claude 带你完成这次更改，或者查阅 Agent SDK 参考中的 Workflow 工具条目，了解完整的选项集。

工作流如何运行

工作流运行时会在一个与你的对话隔离的环境中执行该脚本。中间结果保留在脚本变量中，而不会进入 Claude 的上下文。

每次运行都会把脚本写入你会话目录（位于 ~/.claude/projects/ 下）中的一个文件。运行开始时 Claude 会收到该路径，因此你可以向它索要。你可以打开该文件阅读 Claude 编写的编排逻辑，将其与之前某次运行的脚本进行差异对比，或编辑它后让 Claude 从编辑后的版本重新启动。

运行时会随着运行的进展记录每个智能体的结果，这正是一次运行能够在同一会话内恢复的原因。

行为与限制

运行时会施加以下约束：

管理运行

一次运行启动后，你可以从 /workflows 视图中管理它，或在输入框下方的任务面板中展开其进度行来管理。

暂停后恢复

如果你停止了一次运行，可以恢复它：已经完成的智能体会返回其缓存的结果，剩余的智能体则实时运行。可以在 /workflows 中选中一次已暂停的运行并按 p 来恢复它，或者让 Claude 用同一份脚本重新启动该工作流。

恢复功能只在同一个 Claude Code 会话内有效。如果你在某个工作流运行期间退出 Claude Code，下一次会话会重新全新启动该工作流。

成本

一个工作流会生成许多智能体，因此单次运行消耗的 Token 可能明显多于在对话中处理同一任务。运行会像任何其他会话一样计入你方案的用量和速率限制。

要在投入一项大任务之前预估花费，可以先在一小部分范围上运行该工作流：只处理一个目录，而不是整个仓库；或提出一个范围较窄的问题，而不是宽泛的问题。/workflows 视图会随着运行的推进显示每个智能体的 Token 用量，你可以随时在那里停止该次运行，而不会丢失已完成的工作。运行时的智能体上限限制了单次运行能生成多少智能体，从而限制了一个失控脚本的成本。要让每次运行默认更小，可以在 /config 中设置一个规模指南。

Claude Code 还会标记出异常庞大的运行。当一个工作流调度超过 25 个智能体，或其预计 Token 总量超过 150 万时，输入框下方任务面板中的进度行会显示一条 Large workflow 警告。该警告会指引你前往 /workflows，你可以在那里停止该次运行。需要 Claude Code v2.1.203 或更高版本。

该警告只是提示性的：它不会暂停或限制该次运行。看到它时，有两项设置会发生变化：

• 如果你设置了规模指南，该指南的智能体数量会取代默认的 25 个智能体阈值。
• 开启了ultracode 的会话不会显示该警告，因为开启 ultracode 本身就意味着你已经主动选择接受大规模运行。

工作流中的每个智能体都会使用你会话的模型，除非脚本将某个阶段路由给了另一个模型。要控制模型成本：

• 如果你平常在日常工作中会切换到更小的模型，请在大规模运行前检查 /model
• 在描述任务时，让 Claude 为不需要最强模型的阶段使用较小的模型

设置规模指南

/config 中的 Dynamic workflow size 设置会让 Claude 编写的工作流默认保持在较小规模。Claude Code 会把该设置作为建议发送给 Claude，因此如果提示词要求不同的规模，仍会覆盖它。需要 Claude Code v2.1.202 或更高版本。

每个值设定了 Claude 在编写脚本时所追求的智能体数量目标。

更改会在下一次提示时生效。无论该设置如何，运行时的智能体上限始终适用。

关闭工作流

工作流在 CLI、桌面应用、IDE 扩展、使用 claude -p 的非交互模式以及 Agent SDK 中均可用。同样的关闭设置适用于每个界面。

要为你自己关闭工作流：

• 在 /config 中关闭 Dynamic workflows。会在多次会话间持续生效。
• 在 ~/.claude/settings.json 中设置 "disableWorkflows": true。会在多次会话间持续生效。
• 设置 CLAUDE_CODE_DISABLE_WORKFLOWS=1。在启动时读取，因此无论你在哪里设置它都会生效。

要为你整个组织关闭工作流，在统一管理设置中设置 "disableWorkflows": true，或在 Claude Code 管理设置页面中使用相应开关。

工作流被禁用后，打包的工作流命令将不可用，ultracode 关键词不再触发运行，ultracode 也会从 /effort 菜单中移除。

相关资源

• 并行运行智能体：比较子智能体、智能体视图、智能体团队和工作流
• 创建自定义子智能体：工作流编排的工作者基本单元
• 管理成本：多智能体运行如何计入用量限制