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

动态工作流通过 Claude 编写的脚本来编排大量子代理，你可以反复运行。适用于代码库审计、大规模迁移和交叉验证研究。

[!NOTE]
动态工作流需要 Claude Code v2.1.154 或更高版本，支持所有付费计划、Anthropic API、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry。Pro 计划用户可在 /config 的 Dynamic workflows 行开启。

动态工作流是一段 JavaScript 脚本，用于大规模编排子代理。 Claude 为你描述的任务编写脚本，运行时在后台执行，你的会话始终保持可交互状态。

适用场景：当一个任务需要的代理数量超出单次对话所能协调的范围，或者你希望把编排逻辑固化为可阅读、可重跑的脚本时，就该使用工作流。 典型案例包括：全代码库 bug 扫描、500 文件迁移、需要多源交叉验证的研究问题、以及值得从多个角度起草方案再做最终决策的复杂规划。

何时使用工作流¶

子代理、技能、代理团队和工作流都能完成多步骤任务，区别在于"谁持有执行计划"。

工作流将执行计划移入代码。 在子代理、技能和代理团队中，Claude 是编排者：它逐轮决定下一步生成或分配什么，所有结果都落入上下文窗口。而工作流脚本自身掌控循环、分支和中间结果，Claude 的上下文只保留最终答案。

将计划代码化还能实现可重复的质量模式，不仅仅是运行更多代理： 工作流可以让独立代理对彼此的发现进行对抗性审查后再汇报，或从多个角度起草方案并相互权衡，从而获得比单次执行更可信的结果。

运行内置工作流¶

体验工作流最快的方式是运行 /deep-research，这是 Claude Code 内置的研究型工作流。 你会看到代理在后台分阶段工作，会话保持空闲可用，最终收到一份报告而非逐轮对话记录。

步骤 1：启动工作流¶

用一个你想调研的问题运行 /deep-research。它会从多个角度发起网络搜索、抓取并交叉验证找到的来源，最终综合出一份带引用的报告。

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

步骤 2：授权工作流¶

Claude Code 会询问是否允许运行该工作流。选择 Yes 继续。具体提示取决于你的权限模式，详见运行前批准计划。

步骤 3：查看进度¶

运行在后台启动。执行 /workflows，用方向键选中该运行，按 Enter 打开进度视图：

/workflows

视图显示每个阶段的代理数量、Token 消耗和耗时。可以钻入任何阶段查看其代理及各自发现。详见监控运行状态。

你也可以在输入框下方的任务面板查看：运行期间会显示一行进度摘要。按下箭头聚焦，按 Enter 展开。

步骤 4：阅读报告¶

运行完成后，报告直接呈现在你的会话中。报告会标注每项结论的来源，未通过交叉验证的声明已被过滤掉。

从 v2.1.196 起，当验证代理无法核查某项声明（如遇到速率限制或 API 错误）时，报告会将该声明列为"未验证"，而非视为已被反驳。

如果想为自定义任务运行工作流，请让 Claude 编写一个。 一旦运行结果符合预期，你可以保存它作为自己的命令。

内置工作流列表¶

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

/deep-research 仅在你主动调用时运行。v2.1.218 之前，Claude 也可能自行启动它。

你自己保存的工作流也会以同样方式变成命令，出现在 / 自动补全中，与内置工作流并列。

监控运行状态¶

工作流在后台运行，会话始终可交互。 随时运行 /workflows 查看正在运行和已完成的工作流，选中一个打开进度视图。

/workflows

进度视图显示每个阶段的代理数量、Token 消耗和耗时。底部列出可用的快捷键：

让 Claude 编写工作流¶

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

• 在提示词中请求工作流： 用自然语言描述或包含关键词 ultracode，Claude 就会为该任务编写工作流。
• 用 ultracode 让 Claude 自动决定： 设置 /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 为该任务编写工作流脚本，而非逐轮处理。该关键词仅选择 Claude 如何组织工作：以这种方式启动的工作流运行在会话现有的权限模式中，其代理的工具调用接受与会话中其他工具调用相同的权限检查和沙箱限制。

如果运行结果符合预期，可以之后将其保存为命令。 如果你已有其他形式的编排器（比如一组子代理提示词文件夹，或一个扇出工作的技能），可以将其指给 Claude 并要求生成等效的工作流。

取消或关闭关键词¶

如果你不想启动工作流，按 macOS 上的 Option+W 或 Windows/Linux 上的 Alt+W 取消本次高亮，或在光标紧跟高亮关键词后面时按退格键。要彻底禁用关键词触发，在 /config 中关闭 Ultracode keyword trigger。

关键词的生效范围¶

该关键词仅在你亲自输入的提示词中触发： 交互式提示符、IDE 扩展面板、Remote Control 客户端，或 Agent SDK 应用将你键盘输入的 origin 标记为 { kind: "human" } 时。以下方式传入会话时不会启动工作流：

• 通过 -p 传递的提示词
• Agent SDK 应用发送但未标记为人工输入的提示词
• 定时任务的提示词
• webhook 负载或 Pull Request 评论转发到对话中的内容

[!NOTE]
v2.1.210 之前，上述所有路由（包括 webhook 负载或 Pull Request 评论转发）中的关键词也会启动工作流。

用 ultracode 让 Claude 自动决定¶

Ultracode 是 Claude Code 的一项设置，结合了 xhigh 推理 effort 和自动工作流编排。 开启后，Claude 会为每个实质性任务主动规划工作流，无需你逐次要求。

/effort ultracode

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

开启 ultracode 后，Claude 自行判断任务是否需要工作流。一个请求可能产生多个连续工作流：一个用于理解代码，一个用于修改，一个用于验证。这适用于会话中的每个任务，因此每个请求会消耗更多 Token、花费更长时间。

Ultracode 仅在当前会话有效，新会话时重置。 回到日常工作时用 /effort high 降档。该功能仅在支持 xhigh effort 的模型上可用；不支持的模型中 /effort 菜单不会显示此选项。

运行前批准计划¶

在 CLI 中，每次运行前的提示会显示规划的阶段和以下选项：

• Yes, run it：开始运行
• Yes, and don't ask again for <name> in <path>：开始运行，并对此项目中此工作流以后不再询问
• View raw script：在决定前查看脚本
• No：取消

Ctrl+G 在编辑器中打开脚本。Tab 可在运行前调整提示词。

是否显示此提示取决于你的权限模式：

在桌面应用中，会显示一张审批卡片，包含工作流名称、阶段列表和 Token 消耗提醒，提供 Once、Always 和 Deny 操作。进度视图出现在后台任务侧边栏中。

你的权限模式仅控制上述启动提示。 工作流生成的子代理始终以 acceptEdits 模式运行，并继承你的工具白名单，无论你会话的模式如何。文件编辑会自动批准。

不在白名单中的 Shell 命令、网络请求和 MCP 工具仍可能在运行中途提示你。要避免长时间运行被打断，启动前将代理需要的命令加入白名单。

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

保存工作流以复用¶

当 Claude 为你会重复执行的任务编写了工作流时，可以将该运行的脚本保存为命令。 这样，像每个分支都要跑的代码审查这样的流程就能每次执行相同的编排逻辑。

运行 /workflows，选中要保留的运行，按 s。在保存对话框中，Tab 切换两个保存位置：

• 项目中的 .claude/workflows/：与克隆仓库的所有人共享
• Home 目录下的 ~/.claude/workflows/：在所有项目中可用，仅你可见。如果你设置了 CLAUDE_CONFIG_DIR，此位置为该路径下的 workflows/ 目录。

保存对话框会显示个人位置的解析路径。v2.1.208 之前，即使设置了 CLAUDE_CONFIG_DIR，也显示 ~/.claude/workflows/；但文件实际仍保存在配置的目录下。

按 Enter 保存。工作流在后续会话中以 /<name> 形式从任一位置运行。

Claude Code 在写入前会检查保存位置是否包含符号链接，若检测到则显示错误而非穿透写入。 具体检查规则取决于保存位置（v2.1.216 起）：

• 项目位置：如果 .claude、.claude/workflows 或目标文件是符号链接，Claude Code 会拒绝。
• 个人位置：仅当目标文件本身是符号链接时拒绝，因此用 dotfiles 工具管理的 ~/.claude 目录仍然正常工作。

v2.1.216 之前，Claude Code 会直接跟随链接，这可能导致文件被写入到你选择的位置之外。

在含有多个 .claude/ 目录的 monorepo 中， 你可以将工作流放在它所适用的包旁边。从 v2.1.178 起，保存到项目位置时会写入工作目录到仓库根之间最近的已存在的 .claude/workflows/ 目录，如果不存在则写入仓库根。项目工作流也会从该路径上的每个 .claude/workflows/ 加载，同名时运行离工作目录最近的那个。

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

在插件中分发工作流¶

要在团队或仓库间共享工作流，可将其包含在插件中。 将脚本放在插件根目录的 workflows/ 目录中，或通过 workflows manifest 字段指向其他位置。

插件工作流按插件名命名空间化。一个名为 acme-tools 的插件中包含 meta.name 为 release-audit 的脚本，运行时的命令为 /acme-tools:release-audit。

向保存的工作流传递输入¶

保存的工作流可以通过 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 tool 条目了解完整选项集。

工作流的运行机制¶

工作流运行时在隔离环境中执行脚本，独立于你的对话。 中间结果保留在脚本变量中，而非进入 Claude 的上下文。

每次运行都会将脚本写入 ~/.claude/projects/ 下你会话目录中的文件。Claude 在运行开始时收到文件路径，你可以询问它。你可以打开该文件查看 Claude 编写的编排逻辑，与之前运行的脚本做 diff，或编辑后让 Claude 从修改版重新启动。

运行时会跟踪每个代理的结果，这使得运行可以在同一会话内恢复。

行为与限制¶

运行时施加以下约束：

管理运行¶

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

暂停后恢复¶

如果你停止了一次运行，可以恢复它。 已完成的代理通常返回缓存结果，其余代理实时运行。

两条规则决定哪些结果能保留：

• 停止时仍在运行的代理不会保存，恢复时从头开始。
• 重放按代理启动顺序进行。缓存结果在第一个未完成的代理处中断，该代理之后启动的所有代理都会重新运行，即使它们已经完成。

第二条规则使得在扇出期间停止的代价较高。假设脚本按顺序启动了 A、B、C、D 四个代理，你在 B 还在运行时停止。恢复时：A 从缓存返回；B 因未完成而重新运行；C 和 D 也会重新运行，因为它们在 B 之后启动，即使两者在你停止前已完成。

因此，将工作分散到多个小代理的工作流比一个长代理保留的进度更多。

在 /workflows 中选中已暂停的运行按 p 恢复，或要求 Claude 用相同脚本重新启动。

恢复仅在同一 Claude Code 会话内有效。如果在工作流运行期间退出 Claude Code，下次会话会从头开始。

成本¶

工作流会生成大量代理，单次运行可能消耗比会话内逐步完成同一任务明显更多的 Token。 运行计入你计划的用量和速率限制，与其他会话相同。

在承诺大型任务前，先在小范围试运行来评估开销： 一个目录而非整个仓库，或一个窄问题而非宽泛问题。/workflows 视图在运行过程中显示每个代理的 Token 消耗，你可以随时停止运行而通常不会丢失已完成的工作。暂停后恢复部分说明了停止的运行保留了什么。运行时的代理上限限制了单次运行能生成的最大代理数，从而约束了失控脚本的成本。要让运行使用更少的代理，选择 small 规模指导。

Claude Code 也会对异常增长的运行发出警告。 当工作流调度超过 25 个代理，或其预计 Token 总量超过 150 万时，输入框下方任务面板的进度行会显示 Large workflow 警告。该警告指引你到 /workflows 视图停止运行。需要 Claude Code v2.1.203 或更高版本。

该警告仅为提醒，不会暂停或限制运行。两项设置会改变警告的触发时机：

• 如果你自行选择了规模指导，其代理数量会替换 25 个代理的阈值。内置的默认指导将阈值保持在 25。
• 开启 ultracode 的会话不显示该警告，因为开启 ultracode 本身已表明你接受大规模运行。

工作流中的每个代理使用你会话的模型，除非脚本将某个阶段路由到不同模型，或设置了 CLAUDE_CODE_SUBAGENT_MODEL 环境变量（该变量会覆盖两者）。 控制模型成本的方法：

• 在大型运行前检查 /model，确认是否在用日常切换的小模型
• 描述任务时要求 Claude 对不需要最强模型的阶段使用较小模型

设置规模指导¶

规模指导告诉 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 管理员设置页面的开关。

关闭后，内置工作流命令不可用，ultracode 关键词不再触发运行，ultracode 从 /effort 菜单中移除。

相关资源¶

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