Dynamic Workflows 是什么
Dynamic Workflows 是 Claude Code v2.1.154（2026 年 5 月 28 日）引入的核心功能。在此之前的 Claude Code 是单 agent 架构——你发出指令，一个 agent 串行处理所有步骤。即使 claude agents 能创建后台会话，每个会话仍然是独立的 agent，需要你手动拆分任务和协调结果。
Dynamic Workflows 改变了这个模型。你描述目标，Claude 自动完成三件事：
- 规划（Plan）——把任务拆解为子任务，决定依赖关系和并行策略
- 调度（Spawn）——为每个子任务创建独立的 subagent，分配到后台并行运行
- 监控（Monitor）——跟踪所有 subagent 的进度，协调结果，处理失败
关键区别：claude agents 是你手动创建的独立后台会话，每个会话做一件你指定的事。Dynamic Workflows 是你描述目标后 Claude 自己决定怎么拆、拆成几个、谁先谁后。适合"我知道要什么，但手动拆分太繁琐"的场景。
底层的 Workflow tool 会在终端底部显示一个持久的状态行，实时展示当前活跃的 agent 数量。你可以继续在主会话做其他事——workflow 在后台跑，完成后通知你。
什么时候该用 Dynamic Workflows
判断标准很简单：任务是否涉及多个独立子任务，且手动拆分和协调会消耗大量时间？
适合 Dynamic Workflows
| 场景 | 为什么适合 |
|---|---|
| 大型代码重构 | 需要同时修改数十个文件，文件之间有依赖关系 |
| 批量代码审查 | 多个 PR 或多个目录的代码质量检查 |
| 多文件并行编辑 | API 迁移、批量重命名、统一代码风格 |
| 文档批量生成 | 为多个模块生成 API 文档、README、CHANGELOG |
| 测试修复 | 批量修复失败的测试用例 |
| 多模块依赖升级 | 同时升级多个包的版本并处理 breaking changes |
不适合 Dynamic Workflows
| 场景 | 为什么不适合 | 替代方案 |
|---|---|---|
| 单文件小改动 | 拆分开销大于执行开销 | 直接在主会话编辑 |
| 快速问答 | 不涉及代码修改 | 直接对话 |
| 探索代码库 | 只读任务，不需要并行 | Plan mode + 单 agent |
| 需要深度推理的单点问题 | 并行没有收益 | 主会话 + /effort xhigh |
| 强依赖顺序的串行任务 | 无法并行 | 普通 Auto mode |
一句话：超过 10 个文件，或者超过 3 个独立子任务 → 用 Dynamic Workflows。否则直接做更快。
上手：从零创建一个 Workflow
1. 确认版本
claude --version
# 需要 ≥ v2.1.154
# 如果版本低，升级
npm install -g @anthropic-ai/claude-code@latest
2. 进入 Claude Code 并描述大型任务
claude
在对话中直接描述你的任务。关键是给出清晰的目标和边界，而不是逐步指令：
> 把这个 Express 项目迁移到 Fastify。项目有约 40 个路由文件，
> 5 个中间件，和对应的测试。要求：保持所有测试通过，
> 每个模块迁移后独立可验证。
Claude 会识别这是一个适合 workflow 的大型任务，自动规划并创建 workflow。
3. 观察 Workflow 自动拆分
Claude 会在终端底部显示 workflow 状态行，类似：
⣿ Workflow: express-to-fastify-migration | 12/18 agents running | 3 completed | 0 failed
你可以同时做其他事——在主会话继续提问、编辑其他文件、甚至启动另一个 workflow。
4. 用 /workflows 查看所有运行
> /workflows
这个命令列出所有 workflow 运行的状态：运行中、已完成、失败。每个 workflow 显示其子 agent 数量和进度。
5. 监控进度和回收结果
当所有 subagent 完成后，Claude 会在主会话中汇报结果。如果某个 subagent 失败，Claude 会决定是否重试或调整策略。
退出 Claude Code 后，如果有后台 workflow 还在运行，终端会提示：
Waiting for 3 background agents/workflows to finish
实战案例
案例 1：大型框架迁移
场景：将一个 Express + CommonJS 的 API 服务迁移到 Fastify + ESM，共 40 个路由文件、5 个中间件、配套测试。
提示词：
> 把这个项目从 Express + CommonJS 迁移到 Fastify + ESM。
>
> 项目结构：
> - src/routes/ 下约 40 个路由文件
> - src/middleware/ 下 5 个中间件
> - 每个路由文件都有对应的测试
>
> 规则：
> - 先迁移中间件，再迁移路由
> - 每个文件迁移后运行对应测试确认通过
> - import 路径用 .js 扩展名（ESM 要求）
> - 不要改变 API 行为
Workflow 会做什么：Claude 分析依赖关系，将中间件迁移作为第一批任务（因为路由依赖中间件），然后按模块独立性将路由文件分成多组并行迁移。每组迁移后运行测试验证。
效果对比：
| 方式 | 耗时 | 人工介入 |
|---|---|---|
| 手动迁移 | 1-2 天 | 全程 |
| 单 agent 串行 | 4-6 小时 | 偶尔修正 |
| Dynamic Workflow | 1-2 小时 | 极少，主要在最后审查 |
案例 2：批量代码审查
场景：团队有 15 个待审查的 PR，需要在周五前全部完成。每个 PR 修改 3-10 个文件。
提示词：
> 审查当前仓库所有 open 的 PR。
>
> 审查标准：
> - 正确性：逻辑错误、边界条件、空指针
> - 安全：SQL 注入、XSS、敏感数据暴露
> - 性能：N+1 查询、不必要的全量加载
> - 风格：与项目现有代码风格一致
>
> 每个 PR 输出：通过/需修改 + 具体问题列表
Workflow 会做什么：每个 PR 分配给独立的 subagent 并行审查。subagent 读取 diff，分析代码，按标准输出审查结果。
提示：这种场景适合用 fast mode 的 subagent。Fast mode 以 2x 标准费率换 2.5x 速度，对审查类任务的性价比很高。
案例 3：多模块文档生成
场景：为一个 monorepo 中的 8 个 package 生成 API 文档。每个 package 有 10-30 个导出函数/类。
提示词：
> 为 packages/ 下的每个 package 生成 API 文档。
>
> 要求：
> - 每个函数/类/接口有描述、参数说明、返回值、示例
> - 从源码中的 TSDoc 注释提取信息
> - 输出格式：每个 package 一个 Markdown 文件到 docs/api/
> - 中文文档
Workflow 会做什么：每个 package 分配给一个 subagent，8 个 subagent 并行读取源码、提取类型信息、生成文档。
与其他 Claude Code 功能的关系
Dynamic Workflows vs claude agents
| 维度 | claude agents |
Dynamic Workflows |
|---|---|---|
| 任务拆分 | 你手动指定每个 agent 做什么 | Claude 自动拆分 |
| 协调 | 你手动协调 | Claude 自动协调 |
| 适用场景 | 你清楚知道要拆成几个独立任务 | 你知道目标但不想手动拆分 |
| 可控性 | 高——每个 agent 的指令精确 | 中——Claude 决定拆分策略 |
Dynamic Workflows vs /bg
/bg 是把当前任务扔到后台执行，仍然是单 agent。Dynamic Workflows 是多 agent 并行。两者不冲突——workflow 中的 subagent 本身就是后台 session。
Dynamic Workflows vs Auto mode
Auto mode 解决"频繁确认"的问题。Dynamic Workflows 解决"单 agent 瓶颈"的问题。两者可以组合：workflow 的 subagent 在 Auto mode 下运行，减少人工确认。
Dynamic Workflows vs Worktrees
Worktree 提供文件系统隔离。Workflow 的 subagent 可以在不同 worktree 中工作，避免并行编辑冲突。v2.1.157 支持 EnterWorktree 在 session 中切换 worktree，workflow 可以利用这个能力为不同 subagent 分配独立工作目录。
Dynamic Workflows vs Routines
Routines 是按事件或定时触发的云端 agent。Dynamic Workflows 是本地触发的即时编排。两者面向不同场景：Routines 适合 CI/CD 集成和定期任务，Dynamic Workflows 适合即时的大型任务。
注意事项和限制
当前限制
- Subagent 数量没有公开上限，但实际受 API rate limit 和费用限制。大型 workflow（100+ agents）需要关注
/usage - Subagent 之间不共享上下文——每个 subagent 是独立的会话。如果任务之间有强依赖，协调开销会比较大
- 调试困难——如果一个 subagent 出了问题，你需要单独查看那个 agent 的日志，不如单 agent 调试直观
- 结果合并需要审查——多个 subagent 同时修改代码时，可能产生冲突。建议在 worktree 隔离环境中运行
费用控制
Dynamic Workflows 会同时消耗多个 agent 的 token。建议：
# 运行前确认当前用量
/usage
# 对简单子任务使用 fast mode（2x 费率，2.5x 速度）
# Workflow 会自动为不需要深度推理的 subagent 选择 fast mode
# 大型 workflow 建议先用 Plan mode 评估规模
claude --permission-mode plan
> 分析这个迁移任务，预估需要多少子任务
最佳实践
- 给清晰的目标和边界——workflow 的规划质量直接取决于你的描述精度
- 先小后大——第一次用 workflow 先试一个小任务，理解它的拆分逻辑后再上大型任务
- 配合 CLAUDE.md——参见 Claude Code 实战项目，在 CLAUDE.md 中写清楚项目规则，所有 subagent 都会读取
- 用 worktree 隔离——并行修改文件时避免冲突
- 审查结果——workflow 完成后花时间审查，不要盲目信任所有 subagent 的输出