Lesson 6.4
Model Migration and Deprecations
How the Claude model lifecycle works, why migrations break systems that assumed stability, and a repeatable process for moving routes to a new model without regressing quality, cost or behaviour.
Models are dependencies with a lifecycle. New versions are released, older ones are deprecated with notice, and eventually retired, after which requests fail. Each new generation also changes behaviour and sometimes the API surface. An architecture that treated the model as a fixed component will experience its first migration as an incident. The professional exam expects you to treat migration as a routine, well-rehearsed operation.
The lifecycle
| Stage | What happens | Your action |
|---|---|---|
| Release | New model available; docs describe differences and a migration guide | Evaluate on your suites; plan adoption |
| Active | Supported and recommended | Pin explicit versions in production |
| Deprecated | Announced retirement date; still works | Schedule migration well before the date |
| Retired | Requests fail | Must already be migrated |
Anthropic publishes deprecation notices with timelines; subscribe to them and track every model ID in use against the schedule. Cloud platforms have their own lifecycle timing for the same models, which may differ.
Why migrations break things
Behaviour and interface both move between generations. Typical breaking changes seen across recent generations include:
- Thinking configuration. Fixed token budgets replaced by adaptive thinking and effort settings; on some tiers thinking cannot be disabled and old parameters are rejected.
- Removed conveniences. Assistant prefill and forced tool choice are not supported on newer models; designs that relied on them need structured outputs or instruction changes.
- Tokenizer changes. The same prompt costs a different number of tokens; cache minimums, context budgets and cost estimates shift.
- Conversation handling. Thinking blocks are tied to the model that produced them, and some models reject edited history; harnesses must be append-only.
- Server tool versions. Tool type strings differ by model; a version valid on the old model may be invalid on the new.
- Behavioural shifts. Newer models follow instructions more literally and more capably, so over-prescriptive prompts and emphatic language degrade output; verbosity, tool-call patterns and refusal boundaries change.
- Defaults. Default effort, display of thinking and other defaults differ; what was implicit becomes explicit.
The migration guide in the Anthropic docs enumerates the specifics for each target model. Reading it is step one, every time.
A repeatable migration process
- Inventory. Every route, its model ID, prompt version, parameters, tools and server-tool versions, and the platform it runs on. If model IDs are scattered through code rather than configuration, fix that first.
- Read the migration guide for the target model and classify each route: unaffected, parameter changes needed, design changes needed.
- Re-baseline tokens and cost. Count tokens on representative requests with the new model; recompute cache eligibility and cost per task.
- Apply interface changes in a branch: thinking and effort settings, removed features, tool versions, SDK upgrades.
- Audit prompts. Remove instructions written to work around old limitations, soften over-prescriptive step lists, and test deletions against the eval set. Shorter often wins.
- Run the migration suite. Full regression on both old and new models, repeated runs, with a comparison report by segment covering quality, cost, latency, tool-call counts and refusal rate.
- Tune effort. Levels are recalibrated between generations; sweep effort per route and pick the cheapest that holds quality.
- Shadow, then canary. Run the new model on live traffic without serving, grade with the production sampler, then ramp with rollback ready.
- Update records. ADRs, prompt catalogue, runbooks, the business case cost line, and stakeholder communication.
- Retire the old configuration once the new one is stable, before the retirement date.
Planning and communication
Start migrations when a deprecation is announced, not when retirement approaches; the process above takes weeks for a system with many routes. Communicate to stakeholders what will change for users (often faster, sometimes different in tone or length), what has been tested, and what to report. Treat a migration as a release with the same change control.
Designing for migration from day one
- Model IDs, effort, thinking settings and tool versions live in configuration per route.
- A gateway pins bundles per route so that switching is a configuration change with rollback.
- Prompts are versioned with the model they were validated on.
- The regression suite exists and is affordable to run in full.
- No dependence on features marked deprecated; beta features are tracked as risks.
- Harnesses are append-only and preserve response content exactly, including thinking blocks.
Systems built this way migrate in days; systems without these properties migrate in quarters.
Multi-platform estates
When the same route runs on the Claude API and a cloud platform, the new model may arrive on them at different times with different feature support. Plan migrations per platform, keep the feature matrix current, and avoid designs that need a feature on one platform that the other lacks.
Exam focus
- Models move through release, active, deprecated and retired; pin versions and track retirement dates.
- Expect breaking changes in thinking configuration, removed conveniences such as prefill and forced tool choice, tokenizer, conversation handling, tool versions and behaviour; read the migration guide first.
- The process: inventory, classify, re-baseline tokens, apply interface changes, audit prompts, run a comparison suite, tune effort, shadow and canary, update records, retire.
- Prompt audits usually shorten prompts; over-prescription degrades newer models.
- Design for migration: configuration-driven model settings, pinned bundles in a gateway, versioned prompts, an affordable full suite, append-only harnesses.
- Multi-platform estates migrate per platform with a maintained feature matrix.
Check yourself
5 questions
1.An operations team was surprised when a model their service depended on was retired and requests began failing. They had never looked at deprecation notices. Which practice would have prevented the outage?
2.A team must migrate a production assistant to a newer model generation before the current model is retired. Which migration process is MOST appropriate?
3.During a migration to a current-generation model, previously working code paths start returning 400 errors: one path pre-fills the start of the assistant response, another sets a fixed thinking token budget, and a third forces a specific tool with the tool choice parameter. What should the architect conclude?
4.A platform team's model registry service serves model identifiers to a dozen applications. During a migration an engineer proposes a global find-and-replace of the old identifier with the new one in the registry. What should the architect recommend instead?
5.After migrating to a newer model, a team's quality metrics are stable but costs have changed unexpectedly: some prompts that used to cache now show cache-creation tokens on every request, and input token counts per document have shifted. Which explanation and action is MOST appropriate?