← Back to library

Pick migrations an agent can finish with little supervision

Sergio Azócar, a front-end engineer who dreaded migrations, ran three with Claude Code: a monorepo lint and type-check toolchain, an architecture refactor, and redesigning his whole site. His filter has three conditions: lots of mechanical changes, pass-or-fail feedback from linters, types, tests and builds, and a migration guide to hand over. The toolchain change alone spanned over 700 files.

  • OutcomeClear long-postponed upgrades by choosing ones with mechanical changes, pass/fail checks and a written migration guide.
  • SetupAn afternoon+
  • LevelIntermediate
  • CreditSergio Azócar
View original
Works with
Claude Code

Published Oct 23, 2026Updated Oct 23, 2026AI dry run on sample input: passed Oct 23, 2026Source verified Oct 23, 2026

When should you use it?

  • An upgrade keeps slipping because it is tedious
  • Your repo has linting, type checks and tests
  • The target tool publishes a migration guide

Not for: Migrations needing many judgment calls about design; Repos without automated checks

What do you need, and what do you get?

You need

  • The migration guide
  • Project context file
  • Lint, type-check, test and build commands

You get

  • Updated config and code
  • Passing checks
  • Before and after timings

How does it work, step by step?

  1. Check the three conditionsConfirm volume is mechanical, checks are pass/fail, and a guide exists.
  2. Give the guide and contextShare the target tool's migration doc so it does not invent settings.
  3. Loop on checksLet it make changes, run validations, adjust and repeat.
  4. MeasureRecord timings or other metrics before and after, as the author did for linting and type checks.
  5. Merge in slicesKeep branches short so colleagues are not blocked.

The prompt

Our own prompt, inspired by Sergio Azócar and written to work in Claude Code. Values in lime are placeholders.

Prompt0 variables
We are migrating from [old tool] to [new tool]. Read the official migration guide at [link] and our project context file. Make the config changes first, then fix code until lint, type-check, tests and build all pass. Run the checks after each batch of edits and report failures by count. Record timings for the old and new tools. Commit in small steps with clear messages. Ask me before changing any rule's severity.

Inspired by Sergio Azócar: How to migrate with Claude Code and not die trying. The prompt above is written by playbooks.bot in our own words; nothing from the original is quoted.

What can go wrong?

  • Stricter new tools surface type errors the old one missed; budget time for them.
  • A long-lived migration branch still causes merge pain if others keep committing.

Our take

Sergio Azócar's three conditions make a practical filter for any team deciding which work to hand an agent. Lots of mechanical change means the job is tedious for people but repetitive for an agent. Pass-or-fail feedback from linters, type checks, tests and builds lets the agent judge its own progress without asking you. A written migration guide supplies the rules, so it does not invent them. When all three are present, agents rarely need supervision; when one is missing, expect to stay closely involved. The toolchain move touching hundreds of files is exactly the shape that fits. Two habits from the post are worth keeping. Measure before and after, such as lint time or build time, which turns a vague sense of improvement into evidence for the next migration. And merge in slices rather than one enormous change, so review stays possible and a regression can be traced to a small set of files. For architecture refactors, where feedback is less binary, review design decisions yourself before the agent applies them everywhere.

Where the time goes back: Weeks of tedious edits become days because the agent iterates against automatic checks.

FAQ

What were the gains?
He reports lint and type-check runs dropping from seconds to well under a second on later versions.
What makes a bad candidate?
Work without clear pass/fail signals or a guide, where the agent has to guess.

Source and credit

Inspired by Sergio Azócar. We describe the idea in our own words, link to the original, and wrote the prompt ourselves; nothing is quoted.

Inspired by
How to migrate with Claude Code and not die trying
Creator
Sergio Azócar
Published on
sergioazocar.com
Original date
Apr 28, 2026
License
Not openly licensed (the poster keeps all rights), so we quote nothing and link to the original
Originally for
Claude Code
AI dry run
Oct 23, 2026: passed. Dry-run tested by our AI test agent on sample input. PASS: Gates held on desk check; no live sends or purchases.
AI dry run on sample data; not run with live connected accounts. The playbooks.bot test agent filled the prompt with synthetic inputs, produced the output and checked it against the page's stated outputs and guardrails.
Verified
Oct 23, 2026: source link resolves to the original, the credited creator published it, our excerpt or prompt matches it, and the license allows our use.

Are you the creator? Claim or correct this page.

More in Operations & Admin

All 203 Operations & Admin playbooks →

Related playbooks

Operations & AdminWorkflow✓ AI dry run

Add a merge check for every way coding agents break code

Keep a running list of the specific ways coding agents have damaged your repository, from hollow tests and invented fake responses to deleted files and silenced type errors, and turn each one into an automated gate that blocks the merge, so the same mistake cannot slip through review twice.

Credit: u/alexmarquardt on r/ClaudeCode

An afternoon+
Operations & AdminWorkflow✓ AI dry run

Ask Reddit's experience before you pick a library

Let your coding agent search Reddit for long-term user reports on a library, an error message or a competitor before you commit to a choice.

Credit: u/karanb192 on r/ClaudeCode

Minutes
Operations & AdminWorkflow✓ AI dry run

Run parallel coding agents for days on one large build

Keep many coding agent sessions making autonomous progress on one big codebase by investing in tests, logs and task locks instead of supervision.

Credit: Nicholas Carlini (Anthropic)

An afternoon+