ع
Start Topics Teams Reference What's new Saved
playbook

Run a wide, boring migration without breaking things

The repo-wide change you've been dreading — swap a library, rename an API, bump a pattern across 80 files — done in one sweep, with a clear list of the cases it couldn't convert one-to-one for you to decide by hand.

medium ~45 min
when to reach for this

You need to move the whole repo from moment to date-fns, or rename an API used in 80 places, or migrate every component to a new pattern. At enterprise scale this is the change that spans dozens of files and crosses several teams' code — the one that's been sitting in the backlog for a quarter because nobody wants to own the find-and-replace. It's wide, boring, and error-prone — exactly the work humans do badly and skip steps on. This is where an agent shines: it does the mechanical 90% perfectly and, crucially, hands you a list of the 10% that needs a real decision instead of silently guessing.

gather this first
  • The exact before/after: the old thing, the new thing, and one example you've already converted by hand so Claude has a target to match.
  • The project folder open in Claude Desktop, a clean git working tree, and a passing test suite — you want to see the migration as a reviewable diff and prove it didn't break anything.
  • Any known exceptions — places that legitimately shouldn't change — so they're called out up front.
the workflow

  1. Survey the blast radius first

    Open the project folder in Claude Desktop and ask in the chat — surveying a repo needs no terminal. Before changing anything, get the full inventory: you want to know the size and shape of the job — and spot the weird usages — before a single edit.

    you ask
    We're moving from `moment` to `date-fns`. Find every usage across the repo and group them: the straightforward one-to-one conversions, the ones with no clean equivalent, and anything unusual. Give me the counts and the file list. Don't change anything yet.

    what you get back A grouped inventory — "62 simple .format() calls, 9 that use a feature with no direct equivalent, 3 doing something weird with timezones" — so you know what you're in for before you commit.

    Reach for a subagent on the survey if the repo is large, so the wide search doesn't crowd out the context you need for the migration itself. See /features/subagents/.

  2. Convert the mechanical majority

    Now do the boring 90% — the clean one-to-one swaps — and leave the hard cases untouched and flagged. Match your hand-converted example exactly. The sweep comes back as a visual diff in Desktop; skim it in the file pane and accept it before moving on.

    you ask
    Convert all the straightforward cases to match this example I did by hand: [paste your converted example]. Leave the ones with no clean equivalent untouched, but mark each with a `// TODO: migrate manually —` comment explaining why. Show me the diff.

    what you get back A large, mechanical diff covering the easy cases, with the genuinely-hard ones left in place and clearly tagged for you — not silently mangled to make the migration "complete."

  3. Decide the hard cases together

    Go through the flagged few. This is the part that actually needs your judgment — Claude lays out the options, you make the call.

    you ask
    Walk me through each `TODO: migrate manually` case. For each, show the old code, explain why there's no clean equivalent, and give me the 2 best options with the tradeoff. I'll decide each one.

    what you get back A short, case-by-case decision list — old code, why it's tricky, and real options — so the hard 10% gets human judgment instead of a confident guess.

  4. Prove it with the suite and a clean diff

    Run the tests, then read the whole diff. A migration that turns the suite green and reads cleanly is one you can actually merge. Running the suite is the Power Track half (a terminal-enabled session); if you don't have one, run it yourself and paste any breakage back into the Desktop chat.

    you ask
    Run the full test suite. Fix anything the migration broke, then give me the complete diff to review in logical chunks — the mechanical conversions separate from the manual decisions.

    what you get back A green suite and a diff split into "the boring sweep" and "the decisions," so review is fast and you can see exactly where judgment was applied.

make it your own
  • Codemod instead (Power Track): for a truly enormous repo, ask Claude to write a codemod / script that does the transform, run it on a sample, and review the script — sometimes a reviewable transform beats 500 individual edits. Writing and running the script is a terminal-enabled (Power Track) move; the inline-edit path above stays fully on Desktop.
  • Staged rollout: migrate one module, get it green and reviewed, then say "now do the same across the rest the same way" — so the pattern is proven before it's everywhere. Stage the commits (see the git-workflow playbook): the boring sweep as one commit, the hand-decided cases as another, so the diff stays reviewable instead of arriving as one undifferentiated wall.
  • One sweep inside a bigger replatform: this playbook is the mechanical cousin of modernize-subsystem — this is one boring, well-defined sweep (swap the library, rename the API); that orchestrates a whole multi-step modernization across a subsystem. When a migration is really one move in a larger arc, run it here for the sweep itself and let modernize-subsystem sequence the arc around it.
watch out for
  • The "couldn't auto-convert" list is the most important output — read it carefully. That's exactly where the real decisions (and the subtle bugs) hide, so it's the one part you don't skim. Scale doesn't earn the sweep a pass: a wide change still gets read and tested green before it lands — breadth is not an excuse to merge a diff nobody reviewed. And reach for a subagent on the survey so the sheer size of the job doesn't crowd the migration itself out of context — see /features/subagents/.
  • Don't let it claim "migrated everything" by quietly forcing the hard cases into something that compiles but behaves differently. Make it flag, not guess.
  • Do it on a clean tree so the migration is a reviewable diff. A huge change mixed in with unrelated edits is impossible to review and dangerous to merge.

you'll end up with The wide, dreaded change lands in one sweep — the mechanical 90% converted and tested, the tricky 10% surfaced and decided with your judgment — instead of a week of error-prone find-and-replace.

Questions people ask

What do I need to have ready before starting the migration?
Three things: the exact before/after pair (old thing, new thing, one example you've already converted by hand), a clean git working tree, and a passing test suite. The survey and the conversion sweep run entirely in Claude Desktop as visual diffs you accept in the file pane; only running the test suite at the end is a Power-Track step. The clean tree matters because the migration needs to show up as a single, reviewable diff — not buried in unrelated edits.
How do I stop Claude from silently mangling the hard cases just to claim the migration is complete?
Explicitly tell it to leave cases with no clean equivalent untouched and mark each with a `// TODO: migrate manually —` comment explaining why. The instruction "Don't let it claim migrated everything" is load-bearing — the flagged list is the most important output of the whole workflow.
How long does a typical repo-wide migration take?
The survey step takes a few minutes; the mechanical conversion pass depends on repo size but usually runs in under 10 minutes. Budget 45 minutes total — most of that is the survey, your review of the flagged hard cases, and the test run, not the actual conversion.
Can I adapt this to writing a codemod script instead of inline edits?
Yes — for a truly enormous repo, ask Claude to write a codemod or script that does the transform, run it on a sample first, and review the script itself. A single reviewable transform is often safer than hundreds of individual file edits, and it's rerunnable if the repo changes before the migration is merged.