Writing prompts that survive a model upgrade

Most prompt breakage isn't about wording — it's about assumed defaults

A prompt that reads as clear, well-written instructions can still break on a model upgrade for reasons that have nothing to do with its wording — because it was quietly relying on a default behaviour of the old model that the new one doesn't share. Thinking on or off by default, which sampling parameters are even accepted, what effort level is applied absent explicit instruction — none of these live in the prompt's actual text, and none of them are things a prompt review would normally catch, because the prompt looks identical either way.

State what you're relying on instead of assuming it

The single most durable practice here is making implicit assumptions explicit wherever the behaviour actually matters to the outcome — if a task depends on thinking being available, say so, rather than relying on whichever model happens to be handling the request defaulting to it correctly. A prompt that explicitly states its requirements fails loudly and specifically when a new model can't meet them; a prompt that silently assumed a default fails quietly, producing a worse but plausible-looking result that's much harder to trace back to the actual cause.

Avoid hardcoding values that live in the facts layer, not the prompt

A prompt that hardcodes a specific context-window figure, a specific pricing assumption, or a specific model capability baked directly into its instructions becomes stale the moment any of those facts change upstream — and unlike code, a prompt doesn't throw a compile error when the fact it's built on becomes wrong. Reference capabilities and limits by describing what you need ("a model capable of x") rather than hardcoding today's specific numbers into the instructions themselves, so an upgrade doesn't leave the prompt quietly asserting something that's no longer true.

Version your prompts the same way you version your code

A prompt that changes behaviour across a model upgrade is exactly the kind of regression that's easy to miss without a deliberate test, because the prompt's own text didn't change at all — only the model interpreting it did. Keep a small, representative set of test cases for any prompt doing real work, and re-run them against a new model before cutting over traffic, the same way you'd re-run a test suite against a dependency upgrade rather than assuming it's fine because nothing in your own code changed.

Build the re-verification step into your upgrade process itself

The prompts most likely to survive an upgrade cleanly aren't the ones written most defensively in isolation — they're the ones attached to a process that actually re-tests them against every model change, rather than a process that assumes a well-written prompt is upgrade-proof by construction. No prompt is immune to a model's underlying defaults changing out from under it; the real protection is in the habit of checking, not in the wording alone.

Separate what's genuinely stable from what's model-specific tuning

Not every part of a prompt needs to survive an upgrade unchanged — some of it is legitimately tuned to a specific model's quirks and should be expected to need revisiting. Keeping those two categories visibly distinct within the prompt itself, rather than blending stable instructions and model-specific tuning into one undifferentiated block, makes the actual upgrade work faster: you know exactly which parts need a fresh look and which parts you can trust to still hold, instead of re-auditing the entire prompt from scratch every time a new model arrives.

See why removing temperature broke your pipeline and what actually changed from Opus 4.6 to Opus 5 for concrete examples of exactly this category of silent breakage.