Prompts as Versioned Artefacts

# Prompts as Versioned Artefacts

## Why prompts need version control at all

A production prompt is not documentation. It is code. It has an interface (the inputs the caller provides), a contract (the schema it promises to fill), a runtime cost (tokens, cache hits, latency), and failure modes (hallucinations, refusals, format drift). Change a comma and the model behaves differently. Change a rubric line and safety metrics move. Change a few-shot ordering and prompt-cache hit rate collapses (chapter 01).

The industry treats prompts inconsistently. Some teams check them into `.py` files as string constants — versioned by git, but coupled to code deploys. Some teams put them in a database that a PM can edit at runtime — decoupled from deploys, but with no CI, no diff, no code review. Some use a "prompt registry" product (LangSmith Hub, LangFuse, PromptLayer, Weights & Biases Weave, Vellum, Humanloop, Bedrock Prompt Management, Vertex AI Prompt Optimizer) — better tooling, but still needs the practices this chapter names.

The right question is not "which of these do we buy?" — it is: **what does a versioned prompt need to guarantee, and how do we get those guarantees on whatever substrate we picked?** This chapter names the guarantees, shows how to build them, and lands the rollback flow that lets you undo a regressing prompt in minutes, not the next code deploy.

## Five guarantees a prompt-as-artefact must give you

Whether you store prompts in git, in a registry, or in a database, the guarantees below are the hard requirements. Anything less and you cannot ship prompt changes with confidence.

### 1. Identity — every rendered prompt has a version id

Every prompt sent to the model is the render of an identified artefact, not an ad-hoc string. `system_prompt_v3.jinja` at git SHA `4a2b1c…` rendered with tenant=`acme` and locale=`en-US` produces a prompt whose full identity is `(template_id, template_version, render_variables_hash)`. That identity is logged with every completion.

Concrete: the completion log row includes `prompt_id`, `prompt_version`, and a hash of the rendered bytes. When someone asks "which version generated this bad response?" the answer is a git SHA or a registry version id, not "the one that was live yesterday around 3."

### 2. Immutability — a published version is frozen

Once you publish `v3`, you never mutate `v3`. Bug fix, typo, one-comma tweak — all go into `v4`. This is a rule you enforce with tooling, not with discipline; a "you can edit yesterday's version" mode in a registry is a feature you should turn off.

Why: everything downstream — cache hits, eval results, telemetry aggregations, incident forensics — references the version id. Mutating a published version silently invalidates every historical claim tied to it.

### 3. Environment binding — the runtime knows which version is live for which surface

Which prompt version is live in production, which is on the beta canary, which is in staging, and which experiments are running are configuration state, not code state. A prompt version becomes live for a surface via a change to a config artefact (a `prompts.yaml`, a feature-flag rule, a registry environment binding), not by editing the prompt file itself.

Concrete shape: