TL;DR
- 2,000+ files migrated in one day instead of three months
- 80% processed cleanly on first pass, 95% by end of migration
- Parallel Claude instances (20x) processed files simultaneously
- Best for: framework migrations, coding standard updates, API version changes
- Cost: hundreds of dollars in API vs. hundreds of thousands in engineering labor
Large-scale code migrations can process thousands of files in hours using parallel Claude Code instances—transforming three-month projects into two-week efforts.
The migration looked impossible.
Two thousand files needed to change. Every component. Every import. Every pattern. From the old framework to the new one.
“We’d done migrations before. Fifty files, a hundred files. This was twenty times larger. At our normal pace, it would take three months.”
Three months of tedious, mechanical changes. Three months of engineers doing work that felt like assembly line labor.
The team lead asked: what if we didn’t do it manually?
The Migration Challenge
Framework migrations are particularly painful.
It’s not just renaming things. It’s changing patterns:
- Import statements shift syntax
- Component lifecycle methods rename
- State management approaches differ
- API calls wrap differently
Each file needs individual attention. The changes aren’t copy-paste. They require understanding.
“You can’t find-and-replace a framework migration. Each file is slightly different.”
The Headless Revolution
Claude Code could run headless — without human interaction.
A script could invoke Claude with a prompt, get output, use that output in the next step. No GUI. No waiting for human input.
“Headless mode meant we could loop. Process one file, move to the next, keep going.”
The insight: batch the unbatchable.
The Architecture
The team built a migration pipeline:
Phase 1: File Discovery Claude analyzed the codebase. Identified every file using the old framework. Generated a list of 2,147 files needing migration.
Phase 2: Migration Queue The list became a queue. Each file: a task. Each task: “migrate file X from Framework A to Framework B following these patterns.”
Phase 3: Processing Loop A script looped through the queue. For each file:
- Invoke Claude with the file contents and migration prompt
- Receive the migrated version
- Write the new file
- Run validation tests
- If tests pass, mark complete. If tests fail, retry or flag for manual review.
Phase 4: Human Review Files that passed automated validation got human spot-checks. Files that failed got manual attention.
The Prompt Engineering
The migration prompt was precise.
You are migrating from Framework A to Framework B.
Input: Contents of file X.tsx
Rules:
- Replace 'import { Component } from "frameworkA"' with 'import { Component } from "frameworkB"'
- Lifecycle method componentDidMount becomes useEffect with empty dependency array
- Class components become functional components with hooks
- State management via setState becomes useState hooks
- [15 more specific rules...]
Output: The fully migrated file. Complete, runnable, preserving all original functionality.The rules encoded what a human would do. Claude followed them consistently.
The First Batch
They started with 100 files as a test.
Claude processed them in sequence. About two minutes per file — analyzing, transforming, validating.
Three hours later: 87 files successfully migrated. 13 needed manual intervention.
“87% automated success rate. That’s not perfect. But it’s 87% of the work done without human effort.”
The Scaling Strategy
For 2,000 files, sequential processing would take days.
They parallelized.
Multiple Claude sessions ran simultaneously. Ten files processing in parallel. Twenty. The migration became a distributed operation.
“We spun up twenty parallel instances. Each one working on different files. The queue drained fast.”
Twenty instances, two minutes per file, minimal overlap: the 2,000 files processed in about four hours.
The Failure Handling
Not every migration succeeded.
Some files had unusual patterns Claude hadn’t seen. Some had edge cases the prompt didn’t cover. Some just failed mysteriously.
“The failed files went to a retry queue. Different prompt, more context. If still failing, flagged for human.”
About 15% of files needed retries. About 5% needed human intervention. The rest — 80% — processed cleanly on the first pass.
The Validation Loop
Automated migration without validation is dangerous.
After each file transformed, the system ran tests. Type checking. Unit tests. Integration tests where applicable.
“If the migrated file broke tests, we knew immediately. Claude could retry with the test failure as context.”
The validation loop caught errors before they accumulated. Each file verified before moving on.
The Human Layer
Even successful migrations needed review.
The team set up a review process. Senior engineers spot-checked batches. Looked for patterns Claude missed. Identified systematic issues.
“Claude got most things right. But ‘most’ isn’t ‘all.’ Human review caught the subtle stuff.”
When reviewers found patterns Claude was missing, they updated the prompt. The system learned mid-migration.
The Time Compression
Traditional timeline: three months of engineering time. AI-assisted timeline: four hours of processing, plus two weeks of review and fixes.
“We went from ‘impossible project’ to ‘done in two weeks.’ That’s not incremental improvement. That’s a different category.”
The engineers who would have spent three months on mechanical changes spent two weeks on interesting problems: the edge cases, the architectural decisions, the subtle bugs.
The Cost Analysis
Processing 2,000 files wasn’t free.
Token costs: significant for a single day. The team estimated several hundred dollars in API usage.
“But compare that to three months of engineering salary. The AI cost was a rounding error.”
The economics were absurdly favorable. What would cost hundreds of thousands in labor cost hundreds in compute.
The Pattern Recognition
Claude improved as the migration progressed.
The prompt evolved. Edge cases got documented. Failure patterns got addressed.
“By file 1,500, our success rate was 95%. The first 500 were our learning phase.”
The migration became a feedback system. Failures taught lessons. Lessons improved prompts. Better prompts meant fewer failures.
The Side Benefits
Beyond the migration itself, the team gained:
Documentation: Claude’s prompts documented the migration rules. Future migrations could reference them.
Knowledge transfer: Junior engineers learned framework patterns by reviewing Claude’s migrations.
Confidence: The team proved they could handle large-scale changes. Future migrations seemed manageable.
“We didn’t just migrate the code. We built a capability.”
The Repeatability
Other teams heard about the approach.
“How’d you migrate so fast?”
The answer: headless Claude, looped processing, parallel execution. The pattern was reproducible.
Similar migrations at other companies started adopting the approach. A framework migration went from “dreaded project” to “well-understood process.”
The Limitations
The approach had constraints.
“It worked because framework migrations have rules. Consistent patterns. If the transformation was too creative or judgment-dependent, automation would have struggled.”
Mechanical changes at scale: perfect for AI. Architectural redesigns requiring human judgment: still needed humans.
The Future State
The team saw this as the beginning.
“Today we migrated frameworks. Tomorrow we might automate other large-scale changes: coding standard updates, API version migrations, security fixes across a codebase.”
Any change that was rule-based and repetitive was a candidate for scaled automation.
“The two-thousand-file day proved something. Scale that seemed impossible is possible. You just need the right tools.”
The Final Reflection
Two thousand files. One day. A transformation that would have consumed a quarter of engineer-years.
“I’ve been programming for twenty years. I’ve never seen leverage like this.”
The migration wasn’t magic. It was engineering: careful prompts, validation loops, human oversight. But the scale was unprecedented.
“We used to think about what we could do with our time. Now we think about what AI can do with processor time. The math is different.”
Different math. Different possibilities. Two thousand files, processed while the team watched in amazement.
