使用动态工作流大规模编排子代理

动态工作流从 Claude 编写的脚本中编排许多子代理，您可以重新运行。用于代码库审计、大型迁移和交叉检查研究。

动态工作流是一个 JavaScript 脚本，可大规模编排许多子代理。Claude 为您描述的任务编写脚本，运行时在后台执行它，同时您的会话保持响应。

当任务需要比一个对话能协调的更多代理时，或当您想将编排编纂为可以读取和重新运行的脚本时，请使用工作流。示例包括代码库范围的错误扫描、500 文件迁移、需要相互交叉检查来源的研究问题，以及在提交一个之前值得从多个独立角度起草的困难计划。

何时使用工作流

子代理、skills、agent teams 和工作流都可以运行多步骤任务。区别在于谁掌握计划：

工作流将计划移入代码。使用子代理、skills 和 agent teams，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 作为内置工作流：

/deep-research 仅在您调用它时运行。

您自己保存的工作流以相同方式成为命令，并在 / 自动完成中与捆绑的工作流一起出现。

观看运行

工作流在后台运行，所以会话在代理工作时保持响应。随时运行 /workflows 列出运行中和已完成的工作流，然后选择一个打开其进度视图。

进度视图显示每个阶段及其代理计数、令牌总数和经过的时间。页脚列出每个操作的键：

代理详情列出代理的提示、其最近的工具调用和其结果。每个调用显示其状态，例如仍在运行或失败。当代理保持自己的任务列表时，详情显示它，以及每个任务的状态。

按 Enter 展开详情。提示和结果然后完整显示，每个列出的调用显示其输入和其结果的开始。

让 Claude 编写工作流

您可以通过两种方式让 Claude 为您的任务编写工作流：

• 在您的提示中请求工作流，使用关键字 ultracode，Claude 为任务编写一个。
• 让 Claude 使用 ultracode 决定：设置 /effort ultracode，Claude 为会话中的每个实质性任务规划工作流。

您也可以运行已存在的工作流命令：一个捆绑工作流如 /deep-research，或一个您已保存的。

在您的提示中请求工作流

要在不改变会话的努力级别的情况下将单个任务作为工作流运行，在您的提示中包含关键字 ultracode。用您自己的话提问，例如"使用工作流"或"运行工作流"，也可以工作：Claude 将直接请求视为相同的选择加入。

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

Claude Code 在您的输入中突出显示该关键字，Claude 为任务编写工作流脚本，而不是逐轮处理它。该关键字仅选择 Claude 如何组织工作：代理的工具调用接收与会话中任何其他工具调用相同的权限检查和沙箱化。

如果运行完成了您想要的操作，您可以之后将其保存为命令。如果您已经用另一种方式构建了编排器，例如子代理提示的文件夹或一个分散工作的技能，您可以指向 Claude 并要求一个执行相同操作的工作流。

忽略或关闭关键字

如果您不打算启动工作流，在 macOS 上按 Option+W 或在 Windows 和 Linux 上按 Alt+W 来忽略此提示的突出显示，或在突出显示的关键字后面的光标处按退格键。要完全停止该关键字触发，请在 /config 中关闭 Ultracode 关键字触发。

关键字的工作位置

该关键字仅在您自己输入的提示中选择加入：在交互式提示、IDE 扩展面板、Remote Control 客户端或在 Agent SDK 应用程序中，该应用程序将您的键盘输入的 origin 标记为 { kind: "human" }。当它通过另一种方式到达会话时，它不会启动工作流：

• 使用 -p 传递的提示
• Agent SDK 应用程序发送的未标记为人类输入的提示
• 计划任务提示
• 中继到对话中的 webhook 有效负载或拉取请求评论

让 Claude 使用 ultracode 决定

Ultracode 是一个 Claude Code 设置，它结合了 xhigh 推理努力与自动工作流编排。启用它后，Claude 为每个实质性任务规划工作流，而不是等待您要求。

/effort ultracode

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

要在您选择模型时启用它，将 /model 选择器的努力滑块移动到 ultracode，使用箭头键。调整努力级别列出启用 ultracode 的路由。

启用 ultracode 后，Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流：一个理解代码，一个进行更改，一个验证它。这适用于会话中的每个任务，所以每个请求使用更多令牌并花费比较低努力级别更长的时间。

/effort ultracode 持续当前会话；要让每个会话都以它开始，设置 ultracode 设置。当您返回日常工作时，使用 /effort high 下降。/effort 菜单仅在 ultracode 可用时提供它。

在运行前批准计划

在 CLI 中，每次运行的提示显示计划的阶段和这些选项：

• 是，运行它：启动运行
• 是，不再为 <path> 中的 <name> 询问：启动，并从现在起跳过此项目中此工作流的此提示。Claude Code 在您按名称运行捆绑、保存或插件工作流时提供此选项，而不是为当前任务编写的脚本。
• 查看原始脚本：在决定前读取脚本
• 否：取消

Ctrl+G 在您的编辑器中打开脚本。Tab 让您在运行启动前调整提示。

您是否看到此提示取决于您的权限模式：

在 claude -p 和 Agent SDK 中，Claude Code 从不显示此提示。它通过与会话其余部分相同的权限评估运行 Workflow 工具调用，所以拒绝规则、询问规则和 dontAsk 模式适用于启动，就像它们适用于每个工具调用一样。要让工作流在这些运行中启动，使用以下之一：

• 权限规则：您的允许规则中的 Workflow 批准每个工作流，Workflow(<name>) 按名称批准一个保存的工作流。
• 自动权限模式：分类器审查调用并可以批准它。
• 绕过权限模式：Claude Code 批准调用。
• 一个 PreToolUse hook：一个hook为调用返回 allow 批准它。
• 您的主机：一个 --permission-prompt-tool批准它，或者，使用 Agent SDK，一个 canUseTool回调或一个 PermissionRequest hook批准它。

在桌面应用中，批准卡显示工作流名称、阶段列表和令牌使用警告，带有一次、总是和拒绝操作。进度视图出现在"后台任务"侧窗格中。

工作流生成的子代理使用您的权限规则，Claude Code 按子代理运行的权限模式下的规则选择它们的权限模式。要在长时间运行中避免提示，在启动前将代理需要的工具添加到您的允许规则。

保存工作流以供重用

当 Claude 为您将重复的任务编写工作流时，您可以将该运行的脚本保存为命令。像您在每个分支上运行的审查这样的过程然后每次运行相同的编排。

运行 /workflows，选择您想保留的运行，然后按 s。在保存对话中，Tab 在两个保存位置之间切换：

• .claude/workflows/ 在您的项目中：与克隆仓库的每个人共享
• ~/.claude/workflows/ 在您的主目录中：在每个项目中可用，仅对您可见。如果您设置了 CLAUDE_CONFIG_DIR，此位置是该路径下的 workflows/ 目录。

保存对话显示个人位置的已解析路径。

按 Enter 保存。工作流在未来会话中从任一位置作为 /<name> 运行。

Claude Code 在写入前检查保存位置是否有符号链接，并显示错误而不是通过一个写入。它检查的内容取决于您保存的位置：

• 项目位置：如果 .claude、.claude/workflows 或目标文件是符号链接，Claude Code 拒绝。
• 个人位置：Claude Code 仅在目标文件本身是符号链接时拒绝，所以由点文件工具管理的 ~/.claude 目录仍然有效。

在 v2.1.216 之前，Claude Code 跟随链接，这可能会将文件放在您选择的位置之外。

在具有多个 .claude/ 目录的单体仓库中，您可以将工作流保存在它们适用的包旁边。截至 v2.1.178，保存到项目位置会写入您的工作目录和仓库根之间已存在的最近的 .claude/workflows/ 目录，或如果尚不存在则写入仓库根。项目工作流也从该路径上的每个 .claude/workflows/ 加载，当多个定义相同名称时 Claude Code 运行最接近工作目录的那个。

如果项目工作流和个人工作流共享名称，项目工作流运行。

在插件中分发工作流

要在团队或仓库中共享工作流，将其包含在插件中。将脚本放在插件根目录的 workflows/ 目录中，或使用 workflows 清单字段指向不同的位置。

插件工作流由插件名称命名空间。一个名为 acme-tools 的插件，其 meta.name 为 release-audit 的脚本作为 /acme-tools:release-audit 运行。

将输入传递给保存的工作流

保存的工作流可以通过 args 参数接受输入。脚本将其读取为名为 args 的全局变量。使用此功能在调用时提供研究问题、目标路径列表或配置对象，而不是为每次运行编辑脚本。

以下提示使用问题编号列表运行保存的工作流：

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 JavaScript to TypeScript, 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

跨许多来源研究一个主题

在更改日志、问题和文档中扇出读者，然后综合。捆绑的 /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() 为列表中的每个项目运行一个，parallel() 同时运行一组代理任务并等待所有任务完成。

如果您在运行中途停止 agent() 调用或它遇到不可恢复的 API 错误，则 agent() 调用解析为 null。在自动模式中，分类器可以在子代理启动之前阻止 agent() 调用。被阻止的调用解析为 null 并在运行的进度视图中显示原因。pipeline() 在结果数组中保留每个 null，这就是为什么示例以 .filter(Boolean) 结尾以删除这些条目。

如果您在 agent() 调用上传递 schema，该子代理将返回与形状匹配的 JSON 而不是散文。Claude Code 在启动子代理之前检查架构：当它可以证明架构自相矛盾时，调用失败并显示一个错误，命名矛盾，子代理永远不会启动。它可以证明的一个矛盾是 additionalProperties: false 排除的 required 键。

如果子代理的输出在五次尝试后仍然无法通过验证，调用将失败并显示一个错误，其中包括最后的验证失败。要更改尝试次数，请设置 MAX_STRUCTURED_OUTPUT_RETRIES。

编辑保存的脚本

要更改您保存的工作流，编辑其 .js 文件或要求 Claude 进行更改。在编辑或要求之前，运行 /workflow-authoring 捆绑技能以加载 Claude 工作的脚本编写参考。该技能需要 Claude Code v2.1.248 或更高版本。

要在当前会话中运行编辑后的版本，运行 /reload-skills 以重新读取工作流目录，然后再次运行 /<name>。

Claude Code 在加载和运行脚本时对文件的每个部分应用这些规则：

• meta 块：将 export const meta 保持为第一个语句，并将其保持为带有 name 和 description 的纯对象字面量。如果它包含除字面值之外的任何内容，例如变量、函数调用或展开，Claude Code 会从 / 自动完成中删除 /<name>。
• 主体：除了 agent()、pipeline() 和 parallel() 之外，您可以调用 phase() 在进度视图中对以下代理进行分组并添加标题，调用 log() 在阶段上方显示消息，并读取 args 全局变量。如果主体有语法错误，Claude Code 会在您运行工作流时报告它。
• phases：如果您在 meta 中列出它们，为每个条目提供您传递给 phase() 的确切标题。没有条目的 phase() 标题会获得自己的进度组。
• 时间戳和随机性：Claude Code 使脚本内的 Date.now()、Math.random() 和无参数 new Date() 抛出异常，以便重新启动的运行重复相同的 agent() 调用。改为通过 args 传入时间戳。

您也可以编辑单个运行的脚本而不是保存的副本。在暂停后恢复涵盖当您重新启动编辑的脚本时哪些代理再次运行。有关 Workflow 工具的输入，请参阅其在 Agent SDK 参考中的条目。

工作流如何运行

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

每次运行都会将其脚本写入您会话目录下 ~/.claude/projects/ 中的文件。运行开始时 Claude 会收到该路径，因此您可以要求它提供。您可以打开该文件来读取 Claude 编写的编排脚本，将其与之前运行的脚本进行对比，或编辑它并要求 Claude 从编辑后的版本重新启动。

Claude 只能从会话已允许读取的脚本文件启动工作流。要运行保存在工作目录外的脚本，请先使用 /add-dir 或 Read 允许规则 添加其目录。

运行时在运行进行时跟踪每个代理的结果，这是使运行在同一会话中可恢复的原因。

扇出中的 prompt caching

同一运行中的代理可以读取彼此的 prompt cache。使用相同模型、努力级别、代理类型、工具、输出架构和工作目录运行的两个代理会构建相同的工具和系统提示前缀，因此在匹配的兄弟代理响应开始后启动的代理会在其第一个请求中读取该兄弟代理的缓存。

工作流代理的请求不在主对话的 cache TTL bucket 之外，因此其缓存默认保持五分钟，包括在 Claude 订阅上。要将其保持一小时，请将 subagentPromptCacheTtl 设置为 1h。API 以更高的速率计费 1 小时缓存写入。

当扇出同时启动多个匹配的代理时，Claude Code 会保留除第一个之外的所有代理，直到第一个代理的响应开始，然后一起释放保留的代理，以便它们的第一个请求读取共享前缀，而不是每个都未缓存地处理它。Claude Code 将保留时间限制在 CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS 毫秒，默认为 5000。将其设置为 0 以禁用保留。

行为和限制

运行时应用以下约束：

管理运行

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

当您停止运行时，它会保留在任务面板中，直到其任何代理的进程仍在运行。如果您再次停止它，Claude Code 会重新向这些进程发送信号。

暂停后恢复

从 /workflows 恢复暂停的运行，选择它并按 p。对于您停止的运行，要求 Claude 使用相同脚本重新启动工作流。如果来自已停止运行的代理尚未退出，Claude Code 会拒绝重新启动，直到它们退出，这样这些代理的第二个副本就不会与它们并行运行。

Claude Code 按代理启动的顺序重放运行，每个代理要么返回其保存的结果，要么再次运行：

• 已完成：返回其保存的结果。第一个提示与之前运行不同的代理（因为您编辑了脚本或较早的代理返回了不同的内容）会再次运行，之后的每个代理也会再次运行，即使是已完成的代理。
• 停止时仍在运行：重新开始。停止整个运行不会将任何代理计为失败。
• 失败：再次运行，之后启动的每个代理也会再次运行，即使是已完成的代理。通过在 /workflows 中选择单个代理并按 x 来停止它，会将其计为失败。

最后一种情况意味着在扇出中间的失败会重新运行已经完成的工作。如果脚本按该顺序启动 A、B、C 和 D，并且 B 失败，重新启动会从缓存返回 A 并再次运行 B、C 和 D。

您可以在同一 Claude Code 会话中恢复运行。当您离开会话时，运行中的工作流会发生什么取决于您如何离开：

• 如果您后台运行会话，Claude Code 会在后台会话中以相同方式重放运行并继续它。
• 如果您在工作流运行时退出 Claude Code 并且代理视图已打开，退出对话框会提供 Move to background and exit，它以相同方式转移运行。如果您选择 Exit and stop tasks 或未提供该选项，运行会随会话停止。Claude Code 会将运行的保存结果保存在 ~/.claude/projects/ 中该会话的目录下，所以您使用 claude --resume 恢复的会话可以在您要求 Claude 重新启动工作流时重放它们。在您全新启动的会话中，Claude 没有较早的运行可以重新启动，会将工作流作为新运行启动。

在云会话中，Claude Code 也会将运行的结果与会话的对话历史一起保存，当会话的 VM 被回收时，这些历史会保留。当您重新打开这样的会话并要求 Claude 重新启动工作流时，已完成的代理仍会返回其保存的结果。

在本地和云会话中，当 Claude 重新启动较早的运行并且 Claude Code 根本找不到该运行的保存结果时，重新启动会失败并显示 nothing to resume 错误，而不是自动启动运行。要求 Claude 将工作流作为新运行启动。

成本

工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制，如任何其他会话。

要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。/workflows 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行，通常不会丢失已完成的工作。暂停后恢复涵盖了停止的运行保留的内容。运行时的代理上限限制单次运行可以生成多少个代理，这限制了失控脚本的成本。要保持运行的代理数量较少，选择 small 大小指南。

Claude Code 还会标记增长异常大的运行。当工作流调度超过 25 个代理，或其预计令牌总数超过 150 万时，输入框下方任务面板中的其进度行显示 Large workflow 警告。警告指向您可以停止运行的 /workflows。

警告是建议性的：它不会暂停或限制运行。当您看到它时，两个设置会改变：

• 如果您自己选择大小指南，其代理计数替换 25 个代理的阈值。内置默认指南将阈值保留在 25。
• 启用ultracode的会话不显示警告，因为打开 ultracode 已经让您选择加入大型运行。

Claude Code 按照它用于子代理的相同顺序选择每个工作流代理的模型。脚本为阶段命名的模型在该顺序中计为每次调用的模型。当没有其他东西分配一个时，代理在您的会话模型上运行。

要控制模型成本：

• 在大型运行前检查 /model，如果您通常为日常工作切换到较小的模型
• 当您描述任务时，要求 Claude 为不需要最强模型的阶段使用较小的模型

当您组织的 availableModels 允许列表阻止脚本为代理请求的模型时，该代理会改为在替代模型上运行，遵循与子代理相同的替代规则。/workflows 中的运行进度视图显示一个警告，命名请求的和替代的模型。

设置大小指南

大小指南告诉 Claude 在编写动态工作流时应该针对多少个代理。Claude Code 将指南作为建议而不是上限发送给 Claude，所以调用不同规模的提示仍然会覆盖它。需要 Claude Code v2.1.202 或更高版本。

每个值映射到一个代理计数：

默认值是 medium。在您选择值之前，/config 行显示 medium (default)，工作流的 Running in background 行显示 medium size (/config)。需要 Claude Code v2.1.219 或更高版本；较早的版本默认为 unrestricted。

要更改指南，在 /config 中为 Dynamic workflow size 设置选择一个值，或运行 /config workflowSizeGuideline=small。在 v2.1.219 及更高版本上，您也可以在任何设置文件中设置 workflowSizeGuideline 键；该值优先于 /config，当设置文件提供一个时，Claude Code 会隐藏 /config 行。

更改在下一个提示时生效。运行时代理上限仍然适用，无论设置如何。

关闭工作流

工作流在 CLI、桌面应用、IDE 扩展、非交互模式与 claude -p 和 Agent SDK 中可用。相同的禁用设置在每个表面上应用。

要为自己关闭工作流：

• 在 /config 中切换 Dynamic workflows 关闭。在会话中持续。
• 在 ~/.claude/settings.json 中设置 "disableWorkflows": true。在会话中持续。
• 设置 CLAUDE_CODE_DISABLE_WORKFLOWS=1。在启动时读取，所以它在您设置它的任何地方应用。

要为整个组织关闭工作流，在托管设置中设置 "disableWorkflows": true，或使用Claude Code 管理员设置页面上的切换。

当工作流被禁用时，捆绑工作流命令和 /workflow-authoring skill 不可用，ultracode 关键字不再触发运行，ultracode 从 /effort 菜单中移除。

相关资源

• 并行运行代理：比较子代理、代理视图、代理团队和工作流
• 创建自定义子代理：工作流编排的工作者原语
• 管理成本：多代理运行如何计入使用限制