跳转到内容
Claude Code Tutorial

大型迁移与批量改造

大型迁移与批量改造

Section titled “大型迁移与批量改造”

有些活儿，不是改一个文件能搞定的——它要横扫整个 repo。

举几个例子：

  • 全库重命名：把 master 分支改成 main，把 UserModel 改成 Account
  • 批量加错误处理：100 个 API handler 全部加 try/catch + 日志
  • 模式迁移：从 Redux 迁到 Zustand，从 Class 组件迁到 Hooks
  • 依赖替换：把 moment.js 全替换成 dayjs，API 调用全部改写
  • 全量审计：扫整个代码库找硬编码密钥、SQL 注入、过时 API

这种活，传统做法是一个人开一个分支改半年，merge 时冲突满地。Claude Code 给了一种新解法：Fan out——并行铺开。

Fan out：每个 agent 一个独立 checkout

Section titled “Fan out：每个 agent 一个独立 checkout”

官方 best-practice 把这套做法叫 Fan out across files——把一个大改造拆成 N 个独立子任务，每个子任务交给一个独立的 agent。

关键在于独立 checkout。Git Worktree 是配套工具：

Terminal window
# 主 worktree，在 main 分支
git worktree add ../migration-main main


# 给每个 agent 一个独立 worktree，避免互相踩
git worktree add ../migration-auth feature/auth-migration
git worktree add ../migration-api feature/api-migration
git worktree add ../migration-db feature/db-migration

每个 worktree 是一份完整的工作目录，但挂在不同的分支上。三个 agent 可以同时在三个目录里改代码，互不冲突。

然后在每个 worktree 里启动一个 Claude 会话：

Terminal window
cd ../migration-auth && claude -p "migrate all components in src/auth/ from Redux to Zustand. read the migration guide at docs/migration.md first. commit each component separately with conventional commit messages. run tests after each commit, /rewind on failure"


cd ../migration-api && claude -p "migrate all components in src/api/ from Redux to Zustand. read the migration guide at docs/migration.md first. commit each component separately with conventional commit messages. run tests after each commit, /rewind on failure"

每个会话在自己的目录、自己的分支、自己的上下文里干活。跑完之后，三个分支分别提 PR，独立审查、独立合并。

2026 年 6 月：Dynamic Workflows，fan out 上百个 subagent

Section titled “2026 年 6 月：Dynamic Workflows，fan out 上百个 subagent”

Claude Code 在 2026 年 6 月引入了 Dynamic Workflows，让 fan out 的规模上了一个数量级——从一个主代理能动态派生上百个 subagent。

适合的场景：

  • 80 个模型 × 提示组合的基准测试：每个 subagent 跑一个组合，结果汇总
  • 大迁移：把一个仓库 200 个文件分成 100 个组，每组一个 subagent
  • 全量审计：每个 subagent 审一个目录，找出所有违规
  • 批量重构：每个 subagent 处理一个模块

主代理的角色从「执行者」变成「调度员」：

fan out a subagent per file in src/api/ (50 files). for each:
- migrate the file from moment.js to dayjs
- follow the migration pattern in docs/migration.md
- run the test for that file after migration
- report back: success / failure / needs manual review


aggregate the results. for any failures, list the file and the error.
don't proceed with rebase or merge — just report

主代理拿到 50 份报告后，整合、决定哪些需要人工介入。这种规模是单线程串行做不出来的。

6 纪律：3-5 个是甜区，repo 级才上更多

Section titled “6 纪律：3-5 个是甜区，repo 级才上更多”

并行 fan out 不是越多越好——子代理多了，协调成本指数上升。来自社区的「6 纪律」明确说：

并行度 适合场景 风险
1-2 小重构、单文件改造 几乎无
3-5 甜区——大多数场景 低
6-10 大迁移，模块边界清晰 中（合并冲突）
10-100+ repo 级活（全库审计、批量基准） 高（成本、协调）

甜区是 3-5 个。这个量级既享受了并行加速，又不会让合并冲突和处理逻辑失控。除非是真的 repo 级活（全量审计、批量基准测试），别一上来就 fan out 上百个。

更多并行度带来的代价：

  • 合并冲突：100 个分支合并时，文件冲突量爆炸
  • 协调成本：主代理要追踪 100 份进度
  • token 成本：每个 subagent 一份上下文，加起来不便宜
  • 可审计性下降：100 个改动里有一个出问题，定位难

用 headless + –max-budget-usd 控成本

Section titled “用 headless + –max-budget-usd 控成本”

Fan out 上百个 subagent 时，成本是不可忽视的维度。Claude Code 提供了 headless 模式和预算控制：

Terminal window
claude -p --max-budget-usd 50 "fan out migration across all files in src/api/" \
  --output-format json \
  --max-turns 200
  • --max-budget-usd 50：硬上限——花费到 50 美元自动停。避免一个跑飞的迁移烧光预算。
  • --output-format json：结构化输出，方便主代理解析
  • --max-turns 200：每个 subagent 最多 200 轮，防止某个 agent 死循环

headless 模式适合长时间、无人值守的迁移——下班前启动，第二天回来收结果。

几种典型场景的配方

Section titled “几种典型场景的配方”

全库重命名

Section titled “全库重命名”
fan out across the repo to rename UserModel to Account:
- step 1: Explore subagent scans and lists every file referencing UserModel
- step 2: for each file, a subagent applies the rename (class, imports, type references, comments)
- step 3: another subagent updates tests and docs
- step 4: run full test suite, /rewind any file that breaks
- step 5: commit per-file with message "refactor: rename UserModel to Account in <file>"


budget: $20, hard cap via --max-budget-usd

批量加错误处理

Section titled “批量加错误处理”
fan out across all API handlers in src/api/ (80 handlers). for each:
- wrap the handler body in try/catch
- log the error with request id and user id
- return a structured 500 response (not the default Express handler)
- add a test for the error path
- commit per-handler


use 5 parallel subagents (sweet spot). /rewind on any test failure.

80 个模型 × 提示组合基准

Section titled “80 个模型 × 提示组合基准”
dynamic workflow: for each (model, prompt_template) pair in the matrix (80 pairs):
- spawn a subagent
- run the prompt against the model
- record: latency, token count, output quality score (via rubric)
- save results to bench/<model>_<prompt>.json


aggregate into a markdown table sorted by quality score.
budget: $200, hard cap.

全量安全审计

Section titled “全量安全审计”
fan out a security subagent per top-level directory in src/ (10 directories). for each:
- scan for: hardcoded secrets, SQL injection, command injection, missing auth checks
- output findings ranked by severity
- save to audit/<directory>.json


aggregate into a single audit report. highlight high-severity findings.
don't fix anything — audit only.

Fan out 的几条纪律

Section titled “Fan out 的几条纪律”
  • 任务边界要清晰：每个 subagent 处理什么、不处理什么，写明白。边界模糊会导致两个 agent 改同一处。
  • 共享文档：所有 subagent 读同一份「migration guide」，确保改动风格一致。这份文档质量决定整体质量。
  • 小而独立：每个子任务最好能独立 commit、独立 revert。一个子任务挂了不影响其他。
  • 报告统一格式：让每个 subagent 用同样的格式回报告（成功/失败/需人工），主代理才能自动化整合。
  • 预算硬上限：--max-budget-usd 是底线。再小的活儿，加上限。
  • dry-run 一次：正式跑前，先在 1-2 个文件上 dry-run，验证迁移模式可行。模式有 bug，跑 100 个文件等于白跑。

下一站

Section titled “下一站”