How do you manage Claude model tier migrations and snapshot deprecations at scale?

## The two shapes of a model identifier Anthropic exposes each model both as a **dated snapshot** — a fixed identifier whose suffix is the release date — and as a shorter **alias** that resolves to the current snapshot for that tier and version. The difference is the whole question: - The dated snapshot is immutable. The weights behind it do not change, so a prompt you tuned against it keeps behaving the way you measured. - The alias floats. When a newer snapshot ships, requests using the alias start hitting different weights with no deploy on your side. Aliases are excellent for prototyping and for notebooks where you always want the newest thing. In production they convert a vendor release into an unannounced change to your system's behaviour, which is the definition of an incident you cannot bisect. ## Model identity as configuration The structural fix is to make model choice a single, owned surface: 1. Call sites request a **role** — `fast`, `balanced`, `deep` — never a model string. 2. One config layer maps roles to pinned snapshot identifiers, overridable per environment. 3. Environment overrides let staging run the candidate model while production stays on the incumbent. 4. The resolved identifier is logged with every request and attached to any stored output, so you can always answer "which model produced this?" months later. That last point is underrated. Without the model recorded alongside outputs, a quality investigation across a migration boundary is guesswork. ## The migration procedure A tier or snapshot migration is a behavioural change to a non-deterministic component, so it earns the same rigour as a database migration: **Evals first.** Maintain a held-out set of real inputs with known-good outputs, per pipeline step. Run it against both identifiers and compare task-level metrics — not a generic benchmark score, but the thing your product actually needs to be right about. Keep the set in CI so it also guards prompt changes. **Shadow traffic.** Send a sample of live requests to both models, serve the incumbent's answer, and diff. This catches distribution effects your curated eval set misses: the weird inputs, the long tail, the customers who write in a language you forgot to include. **Prompt re-tuning is expected.** Prompts are fitted to a model. Moving up a tier often lets you *delete* scaffolding — the chain-of-thought crutches and the elaborate formatting instructions a weaker model needed. Moving down usually requires adding constraints and examples. Budget engineering time for it; a migration that reuses the prompt verbatim under-measures the new model in both directions. **Staged rollout with a rollback.** Percentage rollout by request or tenant, watching the same production metrics as always: cost per resolved task, latency percentiles, schema-valid rate, human-override or thumbs-down rate. Because the old identifier is a config value and the old snapshot still exists, rollback is a flag flip, not a redeploy. ## Living with deprecation Snapshots do not live forever. Anthropic publishes deprecation notices with retirement dates, after which calls to a retired model fail. The organisational risk is that a team pins a snapshot, forgets about it, and discovers the retirement from a production outage. Practices that prevent that: - An inventory of every model identifier in use across services, derived from the config layer rather than by grepping code. - A scheduled review that checks the inventory against current deprecation announcements. - A rule that no service may be more than one generation behind, so migrations are routine and small rather than rare and terrifying. - Never letting the forced-migration deadline be the first time the new model is evaluated. ## The strategic layer Beyond mechanics, tier lifecycle is a cost and quality strategy. Each new generation tends to move the frontier down the price curve: work that needed the top tier last year often runs acceptably on the middle tier this year. A team that re-runs its per-step evals on each release captures that as a recurring cost reduction; a team that pinned once and never revisited pays the old price forever and slowly falls behind on quality. The corresponding risk is churn. Chasing every release burns engineering time on prompt re-tuning and re-evaluation. The principal-level judgement is to pick a cadence — evaluate on each major release, migrate when the eval justifies it or a deprecation forces it — and to make the cost of a migration low enough (one config layer, evals in CI, shadow tooling that already exists) that the decision is cheap to make either way. ## Vendor-agnosticism, honestly assessed Teams often propose abstracting the provider entirely to make migration trivial. Within Claude tiers that abstraction is nearly free, because the API is identical across tiers. Across vendors it is not: request shapes, tool-call formats, streaming events and stop semantics genuinely differ, and a lowest-common-denominator wrapper costs you the features you are paying for. The defensible position is a thin internal seam — role-based model selection, centralised call helper, logged model identity — rather than a full portability layer nobody can afford to keep correct.