实战 B4：Claude Code 多 Agent 编排——Dynamic Workflow 与 Ultracode 深度实战

实战教程系列 系列 B：B1 配置实战 | B2 日常开发 | B3 审查与重构 | B4 多 Agent ← 本文 | B5 大型项目

Claude Code 的 Dynamic Workflow 是目前市面上最激进的多 Agent 方案——它不是简单地"多开几个线程"，而是一套完整的编排引擎。本文通过三个真实规模的案例，展示它的实际能力边界。

案例 1：50 个文件的 API 迁移

场景：你的团队决定把 50 个 REST 端点迁移到 tRPC。每个文件需要：

1. 把 export const handler = ... 改为 export const procedure = ...
2. 把 req.query.xxx 改为 input.xxx
3. 把 res.json(data) 改为 return data
4. 更新相关的 import 路径
5. 更新对应的测试文件

传统方式：一个一个改

如果你手动改，或者在 Claude Code 中逐个文件处理：

• 每个文件约 2-3 分钟（prompt + 执行 + 验证）
• 50 个文件 ≈ 2-3 小时
• 容易遗漏边缘情况

Dynamic Workflow 方式

ultracode: migrate all API route files under src/routes/ from REST handlers 
to tRPC procedures.

For each file:
1. Replace handler signature: export const X = (req, res) => {...} → procedure.input(...).query/mutation(...)
2. Replace req.query.X / req.body.X → input.X
3. Replace res.json(data) / res.status(N).json(data) → return data / throw TRPCError
4. Update imports: remove express Request/Response types, add tRPC types
5. Run tests for the migrated file.
6. If tests fail, fix the migration before moving to the next file.

At the end, report: files migrated, tests passed/failed, any files that need manual review.

Workflow 实际执行过程

Claude Code 写了一个 workflow 脚本：

1. Phase 1 - Discovery（5 个 agent 并行）：扫描 src/routes/ 目录，识别所有需要迁移的文件，按复杂度分组
2. Phase 2 - Migration（10 个 agent 并行）：每个 agent 负责 5 个文件，独立迁移
3. Phase 3 - Verification（5 个 agent 并行）：对迁移结果运行测试，失败的 agent 自动重试修复
4. Phase 4 - Report：汇总所有结果

运行 /workflows 查看进度：

Phase 1: Discovery      [Done]  5 agents, 12s, 8K tokens
Phase 2: Migration      [Done]  10 agents, 4m32s, 127K tokens
Phase 3: Verification   [Done]  5 agents, 2m15s, 45K tokens
Phase 4: Report         [Done]  Synthesizing...

结果：

• 48 个文件自动迁移成功
• 2 个文件需要手动审查（包含非标准的 handler 写法）
• 总耗时约 7 分钟，对比手工 2-3 小时

Workflow 脚本（Claude 生成的）

你可以查看 Claude 写的 JS 脚本：

// workflow script (simplified)
async function run({ spawn, fanOut }) {
  // Phase 1: Discover
  const files = await spawn("List all .ts files under src/routes/ that contain REST handlers");
  
  // Phase 2: Migrate in parallel
  const results = await fanOut(files, async (file) => {
    const result = await spawn(`Migrate ${file} from REST to tRPC following the migration rules. Run tests after.`);
    return { file, ...result };
  }, { concurrency: 10 });
  
  // Phase 3: Verify failures
  const failed = results.filter(r => !r.passed);
  if (failed.length > 0) {
    const retries = await fanOut(failed, async (f) => {
      return await spawn(`Fix the migration for ${f.file}. Error: ${f.error}. Run tests.`);
    });
  }
  
  // Phase 4: Report
  return { migrated: results.length, passed, failed };
}

案例 2：500 个 API 端点的安全审计

场景：你的平台有 500 个 API 端点，需要审计每个端点是否正确实现了认证和授权。

Prompt

ultracode: audit every API endpoint under src/pages/api/ for missing auth checks.

For each endpoint:
1. Check if it has an auth middleware or auth check
2. Check if the auth check is applied BEFORE any data access
3. Check if role-based access (admin/user) is correctly enforced
4. For each finding, cross-validate with another agent before reporting

At the end:
- List endpoints missing auth (critical)
- List endpoints with auth in wrong order (high)
- List endpoints with incomplete role checks (medium)
- Provide fix suggestions for each finding

交叉验证机制

Dynamic Workflow 的一个关键特性是交叉验证——两个独立的 agent 审查同一个发现，只有双方都确认才报告为 confirmed finding。这大大降低了误报率：

Agent A: "GET /api/users - no auth check found"  → Agent B verifies → Confirmed
Agent A: "POST /api/orders - missing admin check" → Agent B verifies → Disputed (auth middleware handles it)

结果

• Critical 发现：3 个端点完全缺少认证（已确认）
• High 发现：7 个端点的认证检查在数据访问之后
• Medium 发现：12 个端点缺少细粒度角色检查
• 误报过滤：8 个初始发现被交叉验证驳回
• 总耗时：约 12 分钟，500 个端点

案例 3：Ultracode 全天体验——成本与收益

场景：你花一天时间用 Ultracode 模式处理一个复杂项目，记录实际的成本和产出。

开启 Ultracode

/effort ultracode

一天的会话记录

全天统计：

• 完成了 5 个任务，全部成功
• 总 Token 消耗约 510K
• 总耗时约 47 分钟（agent 执行时间，不含等待）
• 对比不使用 Ultracode：同样的任务大约需要 3-4 小时的连续交互

何时开启 Ultracode

应该开的场景：

• 涉及 10+ 个文件的重构
• 需要交叉验证的审计任务
• 多模块并行开发（前端+后端+测试同时推进）
• 一次性的大规模代码迁移

不应该开的场景：

• 单文件的小改动（overkill，成本高）
• 需要频繁人工决策的任务（workflow 会停下来等你）
• 快速迭代的 UI 开发（响应等待时间太长）

黄金规则

进入大型重构 → /effort ultracode → 完成任务 → 立即 /effort medium

不要"忘记关"——Ultracode 的 token 消耗是 medium 的 10-50 倍。做完重活就切回来。

Dynamic Workflow vs 传统 Subagent 的实测对比

用一个 100 文件的类型迁移任务做 AB 对比：

结论：Dynamic Workflow 在规则明确、规模大、可自动验证的任务上碾压传统方式。在需要频繁人工判断的任务上，传统方式的灵活性更好。

总结

下一章：B5: Claude Code 大型项目实战

实操清单

• 找一个 10+ 文件的重构任务，用 Dynamic Workflow 执行一次
• 运行 /workflows 查看 workflow 的阶段进度和 agent 详情
• 对比 Dynamic Workflow 和逐文件手动执行的耗时和成功率
• 对 50+ 端点的项目做一次安全审计，观察交叉验证的误报过滤效果
• 在大型重构任务中开启 Ultracode，记录全天 token 消耗和工作产出
• 任务完成后立即切回低 effort：/effort medium
• 总结团队适用的 Ultracode 使用规则（什么场景开、什么场景关）