Prompt Version

Origin & evolution

The idea is borrowed wholesale from source control. Git made it ordinary to pin any artefact to an immutable commit, and AI engineering applied the same move to prompts once teams discovered that prompts drift. The defining problem is the silent behaviour change: tweaking a prompt to fix one edge case can quietly degrade the main use case, and a reworded line can break downstream logic that depended on the old phrasing. If every edit overwrites the last, there is nothing to compare the regression against and nothing to roll back to.

Versioning answered this by treating each change as a unique, immutable artefact with its own ID. That gave teams three things they now expect: comparing two versions to see what actually changed, testing a version before it reaches production, and rolling back instantly when a deployed version misbehaves.

The discipline then merged with experimentation. Because each version is fixed, two of them can be served to different user groups at once, and A/B testing turns prompt engineering from an art into something measurable: version A against version B, judged on real metrics🔢MetricStrategyA unified metric that measures progress, health, or behaviour across the productView reference → rather than intuition. The version is the unit that makes the experiment🧫ExperimentValidationA test designed to validate a hypothesisView reference → honest, since each arm points at an exact, unchanging prompt.

How it works in practice

A team runs an onboarding assistant on prompt version 7. An engineer edits the template to make replies warmer, producing version 8, and ships it to 50% of new users. Over a week, version 8 lifts message-completion rate by 4 points but raises escalations to human agents, because the warmer tone buried a required disclaimer. Because both versions are pinned, the team reads the difference exactly, reverts the live traffic to version 7 in one action, and keeps version 8 on record to fix the disclaimer. The rollback takes seconds precisely because version 7 was never overwritten.

Prompt version vs. its neighbours

• Prompt template is the editable parent; the version is one frozen child of it. You change the template and get a new version; you never change a version. The template is the identity, the version is the history.
• AI model🤖AI ModelAI & Machine LearningAn AI or ML model used within the productView reference → is what a version is sent to. A behaviour shift can come from a new prompt version or a new model build, so pinning the version isolates which one moved. Knowing the version alone is not enough; you need🫀NeedUserA user need, pain, desire, or constraintView reference → the model too.
• Eval run🎟️Eval RunAI & Machine LearningAn evaluation run against a benchmarkView reference → is an execution that should record the exact prompt version it tested. The version is the input under test; the run is the measurement of it. A run without a pinned version cannot be reproduced.

In the graph

In the Unified Product Graph, prompt_version🗨️Prompt VersionAI & Machine LearningA version of a prompt template lives in the ai domain and is structurally a child of its template. The edge prompt_version_evolves_prompt_templatePrompt VersionevolvesPrompt Templatecross-domain ties every revision back to the durable template it descends from, and ai_model_prompted_via_prompt_versionAI Modelprompted viaPrompt Versionhierarchy records exactly which model build received that frozen text. Holding versions as first-class entities, distinct from the template, is what gives the graph a reproducible audit trail: any eval result or production trace can point at the precise wording that produced it, which is the whole reason the domain treats prompts without versioning as an anti-pattern.