动态工作流需要 Claude Code v2.1.154 或更高版本,在所有付费计划上可用,具有 Anthropic API 访问权限,以及在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上可用。在 Pro 上,从 /config 中的”Dynamic workflows”行启用它们。
动态工作流是一个 JavaScript 脚本,可大规模编排子代理。Claude 为您描述的任务编写脚本,运行时在后台执行它,同时您的会话保持响应。
当任务需要比一个对话能协调的更多代理时,或当您想将编排编纂为可以读取和重新运行的脚本时,请使用工作流。示例包括代码库范围的错误扫描、500 文件迁移、需要相互交叉检查来源的研究问题,以及在提交一个之前值得从多个独立角度起草的困难计划。
何时使用工作流
子代理、skills、agent teams 和工作流都可以运行多步骤任务。区别在于谁掌握计划:
| 子代理 | Skills | Agent teams | 工作流 |
|---|
| 它是什么 | Claude 生成的工作者 | Claude 遵循的指令 | 监督对等会话的主导代理 | 运行时执行的脚本 |
| 谁决定接下来运行什么 | Claude,逐轮 | Claude,遵循提示 | 主导代理,逐轮 | 脚本 |
| 中间结果在哪里 | Claude 的上下文窗口 | Claude 的上下文窗口 | 共享任务列表 | 脚本变量 |
| 什么是可重复的 | 工作者定义 | 指令 | 团队定义 | 编排本身 |
| 规模 | 每轮几个委派任务 | 与子代理相同 | 少数几个长期运行的对等体 | 每次运行数十到数百个代理 |
| 中断 | 重启轮次 | 重启轮次 | 队友继续运行 | 在同一会话中可恢复 |
工作流将计划移入代码。使用子代理、skills 和 agent teams,Claude 是编排者:它逐轮决定接下来生成或分配什么,每个结果都进入上下文窗口。工作流脚本持有循环、分支和中间结果本身,所以 Claude 的上下文只持有最终答案。
将计划移入代码也让工作流应用可重复的质量模式,而不仅仅是运行更多代理:它可以让独立代理在报告之前对彼此的发现进行对抗性审查,或从多个角度起草计划并相互权衡,所以您获得比单次通过更可信的结果。
运行捆绑工作流
查看工作流运行的最快方式是运行 /deep-research,这是 Claude Code 包含的内置工作流,用于跨许多来源调查问题。您将看到代理在后台通过一组阶段工作,同时您的会话保持空闲,最后获得一份报告而不是逐轮记录。
运行工作流
使用您想要调查的问题运行 /deep-research。它在多个角度上扇出网络搜索,获取并交叉检查它找到的来源,并综合一份引用的报告。/deep-research What changed in the Node.js permission model between v20 and v22?
允许工作流
Claude Code 询问是否允许工作流。选择是继续。确切的提示取决于您的权限模式。有关每种模式的选项,请参阅在运行前批准计划。 观看进度
运行在后台启动。运行 /workflows,使用箭头键选择运行,然后按 Enter 打开其进度视图:该视图显示每个阶段及其代理计数、令牌总数和经过的时间。深入任何阶段以查看其代理及每个代理发现的内容。有关完整的控制集,请参阅观看运行。您也可以从输入框下方的任务面板观看:运行进行时会出现一行进度摘要。按向下箭头聚焦它,然后按 Enter 展开。 阅读报告
运行完成后,报告进入您的会话。它引用每个声明来自的来源,未通过交叉检查的声明已被过滤掉。从 v2.1.196 开始,当验证代理无法检查声明时(例如在速率限制或 API 错误之后),报告将该声明列为未验证,而不是计为被驳回。
要为您自己的任务运行工作流,让 Claude 编写一个,一旦运行完成您想要的操作,您可以保存它作为您自己的命令。
捆绑工作流
Claude Code 包含 /deep-research 作为内置工作流:
| 命令 | 它做什么 |
|---|
/deep-research <question> | 在多个角度上扇出网络搜索问题,获取并交叉检查它找到的来源,对每个声明投票,并返回一份引用的报告,其中未通过交叉检查的声明已被过滤掉。需要WebSearch 工具可用 |
您自己保存的工作流以相同方式成为命令,并在 / 自动完成中与捆绑的工作流一起出现。
观看运行
工作流在后台运行,所以会话在代理工作时保持响应。随时运行 /workflows 列出运行中和已完成的工作流,然后选择一个打开其进度视图。
进度视图显示每个阶段及其代理计数、令牌总数和经过的时间。页脚列出每个操作的键:
| 键 | 操作 |
|---|
↑ / ↓ | 选择一个阶段或代理 |
Enter 或 → | 深入选定的阶段,然后进入代理以读取其提示、最近的工具调用和结果 |
Esc | 返回一个级别 |
j / k | 当代理详情溢出时在其中滚动 |
f | 按状态过滤选定阶段中的代理列表。再次按下以循环 |
p | 暂停或恢复运行 |
x | 停止选定的代理,或当焦点在运行上时停止整个工作流 |
r | 重启选定的运行中代理 |
s | 保存运行的脚本作为命令 |
让 Claude 编写工作流
您可以通过两种方式让 Claude 为您的任务编写工作流:
您也可以运行已存在的工作流命令:一个捆绑工作流如 /deep-research,或一个您已保存的。
在您的提示中请求工作流
要在不改变会话的努力级别的情况下将单个任务作为工作流运行,在您的提示中包含关键字 ultracode。用您自己的话提问,例如”使用工作流”或”运行工作流”,也可以工作: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 关键字触发。
如果运行完成了您想要的操作,您可以之后将其保存为命令。
如果您已经用另一种方式构建了编排器,例如子代理提示的文件夹或一个分散工作的技能,您可以指向 Claude 并要求一个执行相同操作的工作流。
让 Claude 使用 ultracode 决定
Ultracode 是一个 Claude Code 设置,它结合了 xhigh 推理努力与自动工作流编排。启用它后,Claude 为每个实质性任务规划工作流,而不是等待您要求。
要启动已启用 ultracode 的会话,请使用 claude --effort ultracode 启动。需要 Claude Code v2.1.203 或更高版本。
启用 ultracode 后,Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流:一个理解代码,一个进行更改,一个验证它。这适用于会话中的每个任务,所以每个请求使用更多令牌并花费比较低努力级别更长的时间。
Ultracode 持续当前会话,当您启动新会话时重置。当您返回日常工作时,使用 /effort high 下降。它在支持 xhigh 努力的模型上可用;在其他模型上,/effort 菜单不提供它。
在运行前批准计划
在 CLI 中,每次运行的提示显示计划的阶段和这些选项:
- 是,运行它:启动运行
- 是,不再为
<path> 中的 <name> 询问:启动,并从现在起跳过此项目中此工作流的此提示
- 查看原始脚本:在决定前读取脚本
- 否:取消
Ctrl+G 在您的编辑器中打开脚本。Tab 让您在运行启动前调整提示。
您是否看到此提示取决于您的权限模式:
| 权限模式 | 何时提示您 |
|---|
| 默认,接受编辑 | 每次运行,除非您已为此项目中的该工作流选择是,不再询问 |
| 自动 | 仅首次启动。任何是在您的用户设置中记录同意,之后启动无需提示。当 ultracode 启用时完全跳过 |
绕过权限,claude -p,Agent SDK | 从不。运行立即启动 |
在桌面应用中,批准卡显示工作流名称、阶段列表和令牌使用警告,带有一次、总是和拒绝操作。进度视图出现在”后台任务”侧窗格中。
您的权限模式仅控制上面的启动提示。工作流生成的子代理始终在 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 的全局变量。使用此功能在调用时提供研究问题、目标路径列表或配置对象,而不是为每次运行编辑脚本。
以下提示使用问题编号列表运行保存的工作流:
> 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
跨许多来源研究一个主题
在更改日志、问题和文档中扇出读者,然后综合。捆绑的 /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 从编辑后的版本重新启动。
运行时在运行进行时跟踪每个代理的结果,这是使运行在同一会话中可恢复的原因。
行为和限制
运行时应用以下约束:
| 约束 | 为什么 |
|---|
| 无中途用户输入 | 仅代理权限提示可以暂停运行。对于阶段之间的签署,将每个阶段作为其自己的工作流运行 |
| 无来自工作流本身的直接文件系统或 shell 访问 | 代理读取、写入和运行命令。脚本协调代理 |
| 最多 16 个并发代理,在 CPU 核心有限的机器上更少 | 限制本地资源使用 |
| 每次运行 1,000 个代理总数 | 防止失控循环 |
管理运行
运行启动后,您可以从 /workflows 视图管理它,或通过展开输入框下方任务面板中的其进度行来管理。
暂停后恢复
如果您停止运行,您可以恢复它:已完成的代理返回其缓存结果,其余的实时运行。从 /workflows 恢复暂停的运行,选择它并按 p,或要求 Claude 使用相同脚本重新启动工作流。
恢复在同一 Claude Code 会话中工作。如果您在工作流运行时退出 Claude Code,下一个会话将从头启动工作流。
工作流生成许多代理,所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制,如任何其他会话。
要在提交大型任务前评估支出,请先在小范围上运行工作流:一个目录而不是整个仓库,或一个狭窄的问题而不是一个宽泛的问题。/workflows 视图显示每个代理的令牌使用情况,随着运行进行,您可以随时在那里停止运行而不会丢失已完成的工作。运行时的代理上限限制单次运行可以生成多少个代理,这限制了失控脚本的成本。要默认保持每次运行更小,在 /config 中设置大小指南。
Claude Code 还会标记增长异常大的运行。当工作流调度超过 25 个代理,或其预计令牌总数超过 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 在其编写的脚本中针对的代理计数。
| 值 | 发送给 Claude 的指导 |
|---|
unrestricted | 无指南。这是默认值。 |
small | 目标少于 5 个代理。 |
medium | 目标少于 15 个代理。 |
large | 目标少于 50 个代理。 |
更改在下一个提示时生效。运行时代理上限仍然适用,无论设置如何。
关闭工作流
工作流在 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 菜单中移除。