How to run a framework migration with coding agents

Coding agents made the typing part of a framework migration cheap. The rest of it is still a lot of work. Your repository uses the old API in forty places, has a wrapper around half of them, and includes one test helper nobody wants to touch.

An agent can do the repetitive editing, and in a cloud sandbox it can do several batches at once. You still need a migration plan that separates a mechanical replacement from a change in behavior. Otherwise the agent makes the compiler happy while the application does something different.

Treat the migration as a sequence of reviewable changes. One coherent change per task. Each batch gets its own compatibility requirements and its own review.

Pin the version and record a baseline

Start with the versions in the repository and the official migration documentation for the target release. Have the agent inventory the affected imports, wrappers, configuration, and tests before editing.

For example: An application moving to a framework's new routing API should inventory navigation calls, route handlers, redirects, and test utilities. A search for one deprecated function won't find behavior hidden behind your own helper.

Run the existing checks at the starting revision. Record failing tests and whether they are repeatable. Identify a few application behaviors that matter to the migration, such as a deep link, an authenticated redirect, and a failed form submission. These become runtime checks after each relevant batch.

If the current application cannot be verified, fix that setup or state the verification limit before rewriting its foundations.

Migrate one representative path first

Choose a small path that exercises the new API without involving every exception in the codebase. Ask the agent to explain the behavioral differences it finds.

An example prompt:

Migrate the account settings route to the target routing API using the official migration guide and the repository's pinned versions. Preserve its URL, authorization behavior, and redirect destination. Update the relevant tests and verify direct navigation and form submission in the running app. Keep unrelated routes unchanged. Stop if preserving behavior requires a wider architecture decision.

Review this first batch closely. It later becomes the example subsequent tasks follow, so a mistaken assumption here would be repeated for every subsequent batch.

Write down decisions that came out of the review. For instance, if the new API changes when a request value becomes available, explain the approved handling. "Follow the first PR" is less useful when the agent must infer which part of the diff was intentional.

Split the remaining work by behavior

Group similar routes or modules into batches that can be tested together. Keep shared configuration and common adapters under one owner. Avoid assigning separate agents to edit the same compatibility helper.

Independent batches can run in parallel when each has its own environment. Isolation covers processes and files. It does not cover semantic conflicts at merge time.

If you don't want to provision those environments, each Hoplite run gets its own sandbox, so ten batches don't mean ten checkouts on your laptop.

Give every batch the target version, the approved example, its file boundaries, and the checks it must run. If a batch discovers an exception, have the agent report it instead of extending the shared design on its own.

Where a batch depends on another unmerged change, sequence the work or make the PR dependency explicit. Stacked pull requests keep a dependent batch reviewable while its parent is still open.

Review the behavior changes

Pay particular attention to defaults that changed between versions. Error handling, caching, serialization, and execution order can behave differently even when the replacement call accepts the same arguments.

Have the agent list intentional behavior changes separately from compatibility fixes. Read updated tests for weakened assertions or deleted cases. A migration that passes because the test stopped checking the old requirement needs a product decision, not another green checkmark.

Exercise the affected user paths in a running build. Verify the application after integrating batches, because each branch's independent success does not prove their combined behavior.

Plan the rollback before rollout

Keep the last working application revision identifiable. Decide whether reverting code also requires restoring configuration or handling changed persisted data. A framework migration that includes a database change may need a compatibility period so the previous application can still run.

Separate irreversible data changes from mechanical code edits where possible. Document the conditions that would stop rollout and the person responsible for that decision. Don't ask an agent to improvise production rollback while users are discovering the failure.

Assign the inventory and one representative migration path first. Once that PR preserves the behavior you care about, use its reviewed decisions to scope the remaining batches.