Model migration

Model migration is the practice of moving a production agentic workflow from one Claude model version to another by re-validating the prompts, effort settings, and gates against the new model's behavior rather than assuming a drop-in swap, often running the old and new versions side by side while the transition is verified.

How it works

Model migration treats a version change as a change to a dependency the workflow was built against, not a transparent upgrade. The work starts by finding where the workflow encoded assumptions about the old model: a prompt tuned to its quirks, an effort or thinking setting expressed in a parameter shape the new version may have changed, a gate calibrated to its output, an API field or default that moved between versions. Each of those is re-validated against the new model rather than assumed to carry over, since a newer model can be better on average and still behave differently on the specific path a workflow depends on. During the transition a team often runs both versions at once, a mixed fleet, so work can move over incrementally and the new version can be compared against the old on real tasks before it carries everything. The migration is done when the workflow has been verified against the new version, not when the new version became available.

Why it matters

The assumption that a newer model is a strictly better drop-in is the one that bites, because a version change can move a default, alter a request contract, or shift behavior on the exact task a gate was tuned for, and a workflow that swapped versions blindly fails in production rather than in review. Re-validation is the cost of that reality, since the more a workflow was tuned to a specific model, the more there is to re-check, which is the unglamorous tax of running agents in production rather than in a demo. A mixed fleet is the honest way through, because it lets a team compare versions on real work and move incrementally instead of betting the whole workflow on an untested swap, at the cost of carrying two versions and their differences at once. The deeper point is that a model is a dependency like any other, so a team that pins versions and migrates deliberately controls when it takes on a new model version, where a team that always tracks the latest implicitly lets the latest alias decide. Migration is also recurring rather than one-time, because the next version is always coming, so the workflow that is cheap to migrate is the one designed to be re-validated, not the one tuned so tightly to one version that every change is a rebuild.

In practice

A workflow runs reliably on one Claude version, then a newer version ships and the temptation is to switch everything at once. Instead the team pins the current version, routes a slice of the work to the new one, and compares: the request shape that set the reasoning budget on the old version behaves differently on the new one, and a gate tuned to the old model's output needs recalibrating. Because only a slice was on the new version, the differences surfaced in comparison rather than in a production incident, and the rest of the work kept running on the pinned version until the new one was verified. The swap that looked like a one-line change was really a migration, and treating it as one is what kept it boring.

Practical considerations

Pin the model version a workflow targets rather than tracking the latest implicitly, so the team chooses when it adopts a new model rather than a default moving underneath it, while remembering that pinning fixes the model version and not every source of drift, since serving-side changes can still shift behavior on a pinned id. Expect the request contract itself to shift between versions, since a parameter shape that controlled reasoning or thinking on one version can return an error or a different default on the next, a migration hazard distinct from any change in answer quality. Re-validate the gates, not just the prompts, because a check calibrated to one model's output can pass or fail differently against another even when the prompt is unchanged. Run a mixed fleet during the transition so the new version is compared on real work before it carries everything, and treat the comparison, not the availability of the new model, as the signal that the migration is done. Design for the recurring case, since the workflow tuned so tightly to one version that every change is a rebuild costs more to own than the one built to be re-validated, because the next version is always coming.

Defined by Ready Solutions AI