Large-Scale Refactors — /batch, Worktrees, and Merge Strategy
How to decompose, execute, and merge large-scale codebase changes — deprecated API migrations, naming standardization, dependency upgrades — using /batch, agent teams, and a disciplined merge strategy.
Quick Reference
- →Qualifies as large-scale: codebase-wide pattern changes, API migrations, dependency upgrades requiring code changes
- →/batch for independent units: 5–30 parallel agents each work on one unit, each opens a PR
- →Decomposition decision: independent files → /batch; interdependent changes → agent teams; sequential → one session
- →Create a checkpoint branch before starting any large refactor
- →Merge order is critical: lowest-dependency packages or modules first
- →Each PR should include its own tests — don't batch tests into a separate PR
- →Agent teams for coordinated refactors: API changes + implementation + test updates as a unit
- →Managing 20+ PRs: review for pattern correctness, not line-by-line scrutiny
What Qualifies as Large-Scale
Large-scale refactors are changes that cross file, module, or package boundaries and require consistent application of a pattern across many units. The defining characteristic isn't the number of lines changed — it's the number of independent change sites.
- ▸Deprecated API migration: replace 200 usages of deprecated.method() with newApi.method() across the codebase
- ▸Naming convention standardization: rename all event handlers from handleX to onX to match the style guide
- ▸Dependency upgrade: migrate from library v1 to v2 where the API changed and each usage needs updating
- ▸Error handling pattern: replace raw try/catch with structured Result types across all service files
- ▸Authentication pattern: add auth checks to all API routes that currently lack them
- ▸Logging standardization: replace console.log with structured logger across all services
| Change type | Scale indicator | Right tool |
|---|---|---|
| Single file, complex logic | 1 file, many changes | Single session |
| Few related files | 2–10 files, same module | Single session |
| Many independent files | 10–200 files, same pattern | /batch |
| Coordinated multi-layer change | Cross-layer, interdependent | Agent teams |
| Sequential pipeline | Step N requires step N-1 | Single session, sequential |
Before choosing /batch, apply the independence test: can file A's change be reviewed and merged without knowing anything about file B's change? If yes, they're independent — /batch is the right tool. If reviewing A requires understanding B's change, they're coordinated — use agent teams instead.