Intermediate

Model Versioning

Claude model IDs come in two forms: dated snapshots (e.g. claude-sonnet-4-6-20251022) and aliases (e.g. claude-sonnet-4-6). Using the wrong one in production can cause silent behaviour changes. This page explains the difference and how to manage migrations safely.

Snapshots vs Aliases

Dated snapshots — pinned, stable

Format: claude-[family]-[version]-[date]
Example: claude-sonnet-4-6-20251022

Always resolves to the same model
Behaviour is frozen — no silent changes
Required for reproducible outputs
Safe for production deployments
Deprecated with advance notice when retired

Aliases — convenience, not stability

Format: claude-[family]-[version]
Example: claude-sonnet-4-6

Automatically points to the latest snapshot
Updates when Anthropic ships improvements
Behaviour can change without notice
Useful for exploration and prototyping
Not recommended for production without evaluation gates

The silent failure mode

If you use an alias (claude-sonnet-4-6) in production and Anthropic updates the underlying snapshot, your application's behaviour changes automatically — possibly breaking evals, changing tone, altering structured output formats, or producing different results. You won't see an error; you'll see different outputs. Always pin to a dated snapshot in production.

Current Model IDs (as of 2025–2026)

Tier	Alias	Pinned snapshot example
Haiku	`claude-haiku-4-5`	`claude-haiku-4-5-20251001`
Sonnet	`claude-sonnet-4-6`	`claude-sonnet-4-6-20251022`
Opus	`claude-opus-4-6`	`claude-opus-4-6-20251101`

Always check the Anthropic models documentation for the latest snapshot IDs. Dates in the example above are illustrative.

Where to Set the Model ID

Avoid hardcoding model IDs in application logic. Centralise them so you can update in one place:

Environment variable: CLAUDE_MODEL=claude-sonnet-4-6-20251022. Read from process.env.CLAUDE_MODEL in your application. Changing the model in production means updating the env var without a code deploy.
Config file: Store model IDs in a central config (e.g. config/ai.ts or config.yaml) alongside other AI settings (temperature, max tokens, timeout). Import from there throughout the codebase.
Multiple models in one application: If different tasks use different model tiers, define a named map — e.g. MODELS.classifier = Haiku, MODELS.reasoner = Sonnet. This makes routing explicit and auditable.

Migration Strategy When a New Version Drops

When Anthropic releases a new model snapshot, don't just swap the ID and ship. Follow this sequence:

Step 1 — Review the release notes

Anthropic publishes model changelogs noting capability improvements, behaviour changes, and any breaking changes to output format or tool calling. Read these before migrating.

Step 2 — Run your eval suite on the new version

Run your existing evaluation dataset against both the old and new snapshot. Measure accuracy, format compliance, tone consistency, and task-specific metrics. The new version may score better on average but regress on edge cases specific to your use case.

Step 3 — Shadow deploy (if high-stakes)

For critical production applications, run the new version in "shadow mode" — process live traffic against both models simultaneously, log both responses, but only serve the old version to users. Compare outputs at volume before switching.

Step 4 — Gradual rollout

Route 5–10% of traffic to the new version, monitor error rates and user feedback, then increase the percentage. Roll back immediately if regressions appear.

Step 5 — Update before deprecation

Anthropic provides advance notice before retiring old snapshots. Track deprecation dates and plan migrations before the deadline — forced migration under time pressure is riskier than planned migration.

Tracking Model Changelog and Deprecations

Anthropic changelog: The official source is the Anthropic documentation and API changelog. Subscribe to release announcements.
Log the model ID per request: Include the model ID in your application logs alongside request metadata. When investigating a quality issue, knowing exactly which model version produced a response is essential for debugging.
Version your eval datasets: Store eval results with the model version and date. This creates a historical record that lets you see how quality evolved across versions.

Checklist: Do You Understand This?

Dated snapshots are pinned and stable; aliases auto-update and can silently change behaviour
Always use dated snapshot IDs in production — never aliases
Centralise model IDs in an environment variable or config file, not scattered across application code
Before migrating to a new snapshot: review changelog, run your eval suite, shadow-deploy if high-stakes
Log the model ID with every request so you can diagnose quality issues against specific versions
Track deprecation dates and migrate proactively — don't wait for forced cutover