Model upgrades are not like library upgrades. A new library version either compiles or it does not; a new model version answers every request, plausibly, in a slightly different way. Outputs shift in tone, length, formatting, and edge-case behavior. Most of those shifts are improvements. A few will interact badly with the assumptions baked into your prompts, your parsers, or your downstream systems. The teams that handle this well treat upgrades as a standard, low-drama procedure with three ingredients: pinned versions, an evaluation gate, and a staged rollout.
Start from a pinned baseline
You cannot upgrade deliberately if you do not control which version you are on. Pin the exact model ID in configuration — claude-sonnet-5 on most platforms, anthropic.claude-sonnet-5 on Bedrock — and treat any change to it as a deployment, subject to the same review and rollback discipline as a code change. Never point production at whatever is newest by default: an unpinned model means your application's behavior can change without anyone deciding it should. This also gives you a clean rollback story — reverting an upgrade is reverting one configuration value.
Gate the upgrade on an evaluation suite
The core of a safe upgrade is an evaluation set: a collection of real inputs from your application, each paired with a definition of acceptable output. When a new model version becomes available on your platform, run the full suite against both the current and the candidate version, and compare. Look at three things: overall quality (did scores go up, down, or hold?), format compliance (does the new version still produce JSON your parser accepts, still respect length limits, still follow your templates?), and regressions on specific cases (a better average can hide a handful of newly broken inputs that matter). Only when the candidate clears the bar you set in advance does it earn a production rollout. If you do not yet have an eval set, building one is the prerequisite — an upgrade decided by pasting three prompts into a playground is a guess, not a gate.
Roll out in stages, watch, then commit
An eval suite covers the inputs you thought to include; production traffic includes everything else. So even after a candidate passes the gate, roll it out incrementally: route a small share of traffic to the new version behind a configuration flag, watch your quality and error signals for a period that covers your traffic's natural variety, then expand. Keep the old version reachable until you have committed fully — the rollback path is what makes the whole process boring, in the good sense. If your application uses multiple models in a tiering setup (say, Haiku 4.5 for routine classification and Opus 4.8 for hard cases), upgrade one tier at a time; simultaneous upgrades make it impossible to attribute a change in behavior.
Prompts may need a tune-up — plan for it
Prompts accumulate scar tissue: instructions added to work around an older model's habits. A new version may not need those workarounds, and occasionally a workaround actively degrades output on the newer model. Budget a short prompt review as part of each upgrade — often you can delete instructions rather than add them. Also re-check parameters like maximum output tokens and any assumptions about response length or verbosity, since these are the settings most likely to interact with a new version's different defaults. Record what changed and why; the notes make the next upgrade faster.
Finally, know your platform's timing. New Claude versions reach Claude Platform on AWS with same-day parity with the first-party API; availability on Bedrock, Vertex AI, and Foundry follows each platform's own schedule. Build your upgrade cadence around when versions actually appear where you run, not around announcement dates.
Where to go next
Version pinning covers the "why pin" argument in more depth, and evaluating LLM features shows how to build the eval set this whole process depends on. The model lineup on the main guide lists current versions and pricing.