How to run a codebase-wide migration with an AI agent

Most codebases have a migration or two that everyone steps around: moving off a deprecated client, renaming a function forty files import, swapping one logging call for another everywhere it appears. They linger not because they are hard but because they are boring and slightly dangerous. Each edit is trivial, the whole set is mind-numbing, and the one call site you miss does not show up in review, it shows up in production. An agent is well suited to this, but only if you give it the right instructions.

Be specific in the prompt. Spell out the old pattern, the new one, and the edge cases you already know are coming. The agent guesses when you are vague, so the more you say up front about what counts as a call site and how to handle the awkward ones, the fewer times it has to stop and ask. A good migration prompt ends up reading a bit like a small spec, which is fine.

Make it count before it cuts. You want the agent to find every occurrence first, including the indirect ones a grep would skip, and tell you the total and how it is spread across packages. Treat that number as a checkpoint. If it reports three matches and you were sure there were forty, the search is wrong, and far better to learn that now than after a batch of edits has landed on a partial map.

Then make it work in batches and check itself between them. Edit a group, rebuild, run the tests, repeat. Keep the repo compiling the whole way through, so a problem in the third batch surfaces in the third batch instead of buried under thirty-seven later edits. And when something is genuinely ambiguous, the agent should hand the call back to you rather than commit to a confident guess, because a wrong guess that compiles is the expensive kind.

Pier works this way out of the box. The codebase-wide migration use case walks through a real one: count the sites, edit in batches, keep the build green between each, hand back one changeset to review. Bumping a major version with breaking changes goes the same way.

Migrations are also cheap to run, which surprises people. The agent reads the entire repo to map the work and then writes very little, and reading is the inexpensive part of the bill, so a job that would run up a serious tab on a top-tier model barely registers on Pier. The cost per task page has the actual figures for work like this.