تجاوز إلى المحتوى
جرّب المرجع الدورة المحفوظات
العربية
← كل playbooks Engineering

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.

متوسّط ~45 min

متى تلجأ إلى هذا

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. 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.

جهّز هذا أولًا

  • 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.
  • 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.

الـ workflow

  1. Survey the blast radius first

    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.

    أنت تطلب 
    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.

    ما تحصل عليه 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.

    أنت تطلب 
    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.

    ما تحصل عليه 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.

    أنت تطلب 
    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.

    ما تحصل عليه 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.

    أنت تطلب 
    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.

    ما تحصل عليه 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.

اجعله ملكك

  • **Codemod instead:** 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.
  • **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.

انتبه إلى

  • The list of "couldn't auto-convert" cases is the most important output — review those carefully. That's exactly where the real decisions (and the subtle bugs) hide.
  • 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.

ستحصل في النهاية على 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.