在大型代码库审计、跨文件迁移或深度研究任务中，你是否曾感到手动协调多个AI代理既耗时又容易出错？当任务规模超出单次对话的上下文窗口，或者需要将复杂的审查流程固化下来时，传统的逐轮交互就显得力不从心。这正是Claude Code的“动态工作流”功能大显身手的场景。本文将深入解析如何利用动态工作流，将复杂的智能体编排任务从临时的对话指令，转变为可重复执行、可大规模并行的自动化脚本。无论你是希望自动化日常代码审查，还是需要并行处理数百个文件的迁移，掌握工作流都将极大提升你的开发效率。

1. 动态工作流：智能体编排的工程化实践

1.1 什么是动态工作流？

动态工作流是Claude Code中用于大规模编排子代理的JavaScript脚本。它允许你将一个复杂的、多步骤的任务（例如“审计整个 src/routes/ 目录下的所有API端点缺失的认证检查”）描述给Claude，Claude会为你生成一个可执行的脚本。这个脚本在后台运行时，会创建并管理多个子代理并行或按顺序工作，而你的主会话窗口依然可以保持响应，处理其他任务。

简单来说，工作流将“计划”从Claude的上下文记忆中移出，并编码到了脚本里。这使得Claude不再需要逐轮记住上一步的结果并决定下一步，而是由脚本这个“总指挥”来掌控流程、循环、分支和中间状态。最终，只有经过处理和分析的最终结果才会返回到你的对话中。

1.2 何时应该使用工作流？

Claude Code提供了多种并行处理能力，理解它们的区别有助于你做出正确选择：

特性	子代理 (Subagents)	技能 (Skills)	代理团队 (Agent Teams)	动态工作流 (Dynamic Workflows)
本质	Claude生成的临时工作者	Claude遵循的指令集	监督对等会话的主导代理	运行时执行的JavaScript脚本
决策者	Claude，逐轮决定	Claude，遵循提示词	主导代理，逐轮决定	脚本本身
中间结果存储	Claude的上下文窗口	Claude的上下文窗口	共享的任务列表	脚本变量
可重复性	工作者定义（可复用）	指令（可复用）	团队定义（可复用）	编排逻辑本身（高度可复用）
适用规模	每轮几个委派任务	与子代理类似	少数几个长期运行的对等体	每次运行数十到数百个代理
中断恢复	重启轮次	重启轮次	队友可继续运行	在同一会话中可暂停和恢复

选择工作流的核心场景：

1. 任务规模超大 ：当任务需要协调的代理数量远超单个对话能有效管理的范围时，例如扫描包含500个文件的代码库。
2. 流程需要固化 ：当你希望将一套复杂的审查、修复、验证流程标准化，并能在不同项目或分支上重复执行时。
3. 需要对抗性验证 ：当任务结果需要高可信度时，工作流可以编排多个独立代理对彼此的发现进行交叉检查和对抗性验证。
4. 追求最终效率 ：你只关心最终的高质量报告，而不想被中间每一步的交互和确认所打扰。

2. 环境准备与核心概念

2.1 版本与权限要求

要使用动态工作流功能，你需要满足以下条件：

• Claude Code版本 ：v2.1.154 或更高版本。
• 访问权限 ：在所有付费计划上可用，并且需要具有Anthropic API的访问权限。该功能也在Amazon Bedrock、Google Cloud Vertex AI和Microsoft Foundry上提供。
• 功能启用 ：在Pro计划中，你可能需要在 /config 设置中手动启用“Dynamic workflows”选项。

2.2 核心组件理解

在深入实操前，理解工作流涉及的几个核心组件至关重要：

1. 脚本 (Script) ：工作流的核心，是一个由Claude生成或你手动编写的JavaScript文件。它使用 agent() 和 pipeline() 等函数来创建和协调子代理。
2. 子代理 (Agent) ：由工作流脚本创建的具体执行单元。每个子代理执行一项具体的任务，如分析一个文件、进行一次网络搜索等。
3. 阶段 (Stage) ：工作流执行过程中的逻辑分组。一个工作流通常包含多个阶段，例如“发现文件”、“并行审计”、“汇总报告”。在进度视图中可以清晰地看到每个阶段。
4. 运行 (Run) ：一次工作流脚本的执行实例。你可以在 /workflows 界面中查看所有运行的状态、进度和详情。
5. Ultracode ：一个特殊的“努力级别”设置。当设置为 /effort ultracode 时，Claude会自动为会话中每个实质性的任务规划工作流，而不是等待你手动请求。

3. 快速上手：运行你的第一个工作流

最快体验工作流的方式是运行Claude Code内置的捆绑工作流 /deep-research 。这个工作流专为深度研究设计，它会并行搜索多个信息源，交叉验证结果，并生成一份带有引用的综合报告。

3.1 启动深度研究工作流

在你的Claude Code会话中，直接输入以下命令：

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

按下回车后，Claude Code会询问你是否允许运行此工作流。根据你的权限模式，你会看到不同的确认选项：

• 默认 (接受编辑) ：每次运行都会询问，除非你之前为该项目中的此工作流选择了“是，不再询问”。
• 自动 ：仅在首次启动时询问。一旦同意，后续启动将无需提示。
• 绕过权限 (如 claude -p 或 Agent SDK)：不会询问，立即启动。

选择“是，运行它”以继续。

3.2 监控运行进度

工作流启动后，会在后台运行。你的主会话窗口不会被阻塞。你可以通过以下方式监控进度：

1. 使用 /workflows 命令 ： 在会话中输入 /workflows ，会打开一个列表视图，显示所有运行中和已完成的工作流。使用方向键选择你刚启动的运行，按 Enter 键进入其详细的进度视图。

2. 进度视图详解 ： 进度视图会清晰地展示工作流的各个阶段，例如：

   • 阶段 1: 生成搜索查询 (1个代理)
   • 阶段 2: 并行网络搜索 (5个代理并发)
   • 阶段 3: 获取并分析内容 (5个代理并发)
   • 阶段 4: 交叉验证与综合 (1个代理) 每个阶段都会显示代理数量、消耗的总令牌数以及经过的时间。

3. 任务面板 ： 当工作流运行时，Claude Code输入框下方会出现一个任务面板，显示一行进度摘要。你可以按向下箭头聚焦到该行，然后按 Enter 键展开查看更详细的信息。

3.3 查看最终报告

当所有阶段完成后，工作流运行结束，一份详细的研究报告会自动发送到你的主会话窗口中。这份报告会引用每个结论的来源，并且那些未被多个独立来源交叉验证的声明会被过滤或标记为“未验证”，从而保证了信息的可靠性。

通过这个简单的例子，你已经体验了工作流的核心价值： 将复杂的、多步骤的、需要并行处理的任务，打包成一个简单的命令，并在后台自动完成，最终给你一个高质量的结果。

4. 创建自定义工作流：从提示词到可复用脚本

虽然内置工作流很方便，但真正的威力在于为你的专属任务创建自定义工作流。你不需要自己编写JavaScript，只需用自然语言告诉Claude你的需求。

4.1 通过关键字触发工作流创建

最直接的方式是在你的提示词中包含关键字 ultracode 。Claude检测到这个关键字后，就会明白你需要为这个任务创建一个工作流脚本，而不是在对话中逐轮处理。

示例：代码库安全审计 假设你需要审计项目 src/routes/ 目录下所有API路由处理程序，查找缺失的身份验证检查，并且在报告前对每个发现进行对抗性验证。

你可以这样输入：

ultracode: audit every route handler under src/routes/ for missing authentication checks, and adversarially verify each finding before reporting it

或者使用更自然的语言，效果相同：

请使用工作流来审计 src/routes/ 下的每一个路由处理器，查找缺失的认证检查，并在报告前对每个发现进行对抗性验证。

Claude收到指令后，会开始为你规划工作流。它会展示一个包含多个阶段的计划（例如：“列出文件”、“并行审计”、“对抗性验证”、“生成报告”），并请求你的批准。批准后，工作流即在后台开始执行。

4.2 启用Ultracode模式进行自动编排

如果你希望在整个会话中，让Claude自动判断何时使用工作流，可以启用Ultracode模式。

/effort ultracode

启用后，Claude会为会话中每一个它认为“足够复杂”的实质性任务自动规划工作流。例如，一个“重构这个模块”的请求，可能会被拆分成“理解代码”、“制定重构计划”、“执行更改”、“验证更改”等一系列工作流。这适用于你准备进行一系列重型任务的场景。记得在完成后切换回常规模式（如 /effort high ）以节省资源。

4.3 保存成功的工作流以供复用

当你运行了一个工作流并且效果令人满意时，你可以将其保存为一个自定义命令，方便日后一键调用。

1. 运行 /workflows 命令。
2. 在列表中选择你想要保存的那个已完成的工作流运行。
3. 按下键盘上的 s 键。
4. 系统会询问保存位置：
   • 项目位置 ( ./.claude/workflows/ ): 保存的工作流会随项目代码库一起，团队其他成员克隆项目后也可使用。
   • 个人位置 ( ~/.claude/workflows/ ): 仅保存在你的本地机器上，在所有项目中都可用。
5. 按 Enter 保存。

保存后，该工作流就会成为一个新的命令。例如，如果你将上面的审计工作流保存为 audit-routes ，那么以后在任何项目中，你只需要输入 /audit-routes 即可运行整个审计流程。

4.4 向保存的工作流传递参数

保存的工作流可以接受输入参数，使其更加灵活。参数通过 args 变量传递给工作流脚本。

调用示例：

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

在这个命令中， [1024, 1025, 1030] 这个列表会作为 args 传递给工作流脚本。在脚本内部，你可以直接像使用数组一样使用 args 。

Claude生成的工作流脚本会自动处理 args 。一个简单的参数化工作流脚本开头可能如下所示：

export const meta = {
  name: 'triage-issues',
  description: 'Triage a list of issue numbers',
};

// args 包含了调用时传递的参数，例如 [1024, 1025, 1030]
const issueNumbers = args; 

const results = await pipeline(issueNumbers, issueNumber =>
  agent(`Analyze issue #${issueNumber} and summarize its priority.`, { label: `Issue-${issueNumber}` })
);

return results;

5. 工作流脚本解析与高级编排模式

虽然Claude会为你生成脚本，但了解其结构有助于你进行调试或提出更精准的修改要求。

5.1 工作流脚本基本结构

一个典型的工作流脚本包含一个 meta 对象和脚本主体。

// 文件通常保存在 .claude/workflows/your-workflow-name.js
export const meta = {
  name: 'audit-routes', // 工作流名称
  description: 'Audit every route handler for missing auth checks', // 描述
};

// 脚本主体 - 使用顶级 await
// 1. 发现阶段：列出所有需要审计的文件
const found = await agent('List every .ts file under src/routes/.', {
  // 指定期望的输出格式为包含文件列表的对象
  schema: { 
    type: 'object', 
    required: ['files'], 
    properties: { 
      files: { 
        type: 'array', 
        items: { type: 'string' } 
      } 
    } 
  },
});

// 2. 并行审计阶段：为每个文件启动一个子代理
const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { 
    label: file // 为代理设置标签，便于在进度视图中识别
  }),
);

// 3. 过滤并返回有发现的审计结果
return audits.filter(Boolean); // 过滤掉 null 或 undefined 的结果

关键函数说明：

• agent(prompt, options) : 创建一个执行特定提示词的子代理。 options 中可以指定 schema 来约束输出格式，或 label 用于标识。
• pipeline(items, taskFn) : 核心并行处理函数。它对 items 数组中的每个元素，调用 taskFn 来创建一个代理任务，并自动管理这些任务的并发执行和结果收集。

5.2 常见工作流模式示例

以下是一些经典的工作流模式，你可以直接将这些自然语言描述作为提示词使用：

1. “修复直到通过”模式 ： 适用于需要迭代修复直到满足某个条件的任务，如通过类型检查。

   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
   

2. “并行迁移”模式 ： 适用于需要批量修改大量文件，且希望隔离修改以避免冲突的场景。

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

3. “审查汇总”模式 ： 适用于代码审查，先并行审查每个文件，再汇总成一份报告。

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

4. “研究综合”模式 ： 类似于 /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
   

6. 工作流运行管理、成本控制与故障排查

6.1 管理工作流运行

• 暂停与恢复 ：在 /workflows 视图中，选中一个运行中的工作流，按 p 可以暂停它。再次按 p 可以从中断处恢复。已完成的代理结果会被缓存，恢复时无需重做。
• 停止运行 ：选中运行或某个代理，按 x 键可以停止它。停止整个运行会终止所有未完成的代理。
• 查看脚本 ：在运行前批准计划时，可以按 Ctrl+G 在编辑器中打开Claude生成的原始脚本进行查看或微调。

6.2 理解成本与资源限制

工作流通过并行运行大量代理来提升效率，但这也会消耗更多的令牌（Token），直接影响使用成本。

成本控制策略：

1. 先小规模测试 ：在对整个仓库运行审计前，先在一个子目录上运行工作流，以估算令牌消耗。
2. 监控进度 ：通过 /workflows 视图实时查看每个代理的令牌使用量，如果发现消耗过快，可以及时停止。
3. 模型选择 ：工作流中的代理默认使用你当前会话的模型。对于不需要最强推理能力的阶段（如简单的文件收集），你可以在提示词中要求Claude为这些阶段分配更小、更便宜的模型。
4. 了解限制 ：运行时对资源有保护性限制，例如最多16个并发代理（在资源有限的机器上会更少），以及每次运行最多1000个代理总数，这也能防止意外循环导致成本失控。

6.3 常见问题与排查思路

问题现象	可能原因	排查与解决思路
无法触发工作流（输入 ultracode 无反应）	1. Claude Code版本过低。 2. 动态工作流功能未启用。 3. 权限模式限制。	1. 检查版本号 ( claude --version )，确保 >= v2.1.154。 2. 检查 /config 中 “Dynamic workflows” 是否开启。 3. 确认当前会话有足够的权限创建代理。
工作流启动后被立即停止	1. 代理尝试执行未被允许的Shell命令或工具调用。 2. 达到了并发代理数上限。	1. 在运行前，将工作流可能需要的命令添加到工具的允许列表中。 2. 检查系统资源。对于大型任务，考虑分批次运行。
工作流运行时间过长，令牌消耗巨大	1. 任务范围定义过于宽泛（如“检查所有代码”）。 2. 脚本中存在未预期的循环或低效逻辑。	1. 始终先进行小范围测试 。使用更精确的路径或条件限定任务范围。 2. 在运行前查看Claude生成的计划，评估其阶段和代理数量是否合理。
保存的工作流命令在其他项目中不生效	1. 工作流保存到了个人目录，但项目目录下有同名工作流。 2. 工作流脚本存在项目特定的硬编码路径。	1. 项目目录 ( ./.claude/workflows/ ) 下的工作流优先级高于个人目录 ( ~/.claude/workflows/ )。检查冲突。 2. 修改工作流脚本，使用相对路径或通过 args 参数传入路径。
工作流报告“未验证”声明较多	1. 网络搜索被速率限制。 2. 信息来源不可访问或已过期。	1. 这是 /deep-research 等工作的正常行为，它如实反映了信息可验证性。 2. 尝试更换研究角度或使用更稳定的数据源。

7. 最佳实践与工程化建议

将动态工作流集成到你的日常开发流程中，可以将其价值最大化。以下是一些来自实践的建议：

1. 从具体、可衡量的任务开始 ：不要一开始就尝试用工作流解决最宏大的问题。从“审计这个目录下的X类型错误”或“为这50个组件生成单元测试骨架”这类明确的任务入手，积累成功经验。

2. 设计可复用的、参数化的工作流 ：在创建工作流时，就考虑其复用性。使用 args 参数来接收目标路径、问题列表、配置选项等，而不是将值硬编码在脚本中。这样，一个“代码审查”工作流就可以用于不同的分支或项目。

3. 将工作流纳入代码审查与CI/CD流程 ：可以将保存的工作流脚本像其他源代码一样纳入版本控制（如果保存在项目目录）。在团队内部，可以建立一套标准工作流库，用于自动化代码风格检查、安全漏洞扫描、依赖许可证审计等重复性任务。虽然工作流本身不易直接集成到CI流水线中，但其产出的报告或自动化修改的代码，可以作为CI流程的输入。

4. 善用“对抗性验证”提升质量 ：工作流的核心优势之一是能轻松编排多个代理进行交叉验证。在设计工作流时，除了让一个代理执行任务，可以安排另一个代理扮演“质疑者”或“评审者”的角色，对前者的输出进行批判性检查。这能显著提升最终结果的准确性和可靠性。

5. 成本意识与优化 ：

   • 设定预算警报 ：如果你在团队或生产环境中大量使用工作流，密切关注API使用量和成本。
   • 分解大任务 ：对于超大型任务（如迁移数千个文件），可以设计工作流将其分解为多个批次执行，并在每批次之间进行人工检查或设置检查点，避免一次性运行成本过高或出错后全盘重来。
   • 结果缓存 ：对于相对静态的分析任务（如文档生成），考虑将工作流的结果缓存起来，避免每次执行都重新计算。

6. 文档与知识共享 ：为你创建的每个重要工作流编写简短的README，说明其用途、输入参数、预期输出以及任何注意事项。这对于团队协作和未来的维护至关重要。

动态工作流将Claude Code从一个强大的对话式编程助手，升级为了一个可编程的、自动化的智能体编排平台。它代表了AI辅助开发从“交互式工具”向“自动化系统”演进的关键一步。通过将复杂的多步骤任务编码为可重复执行的脚本，你不仅解放了自己的时间，更建立了一套可靠、可扩展的智能质量保障和生产力增强体系。现在，就从定义一个你最想自动化的重复性任务开始，构建你的第一个智能体工作流吧。