Define a prompt versioning and review convention

A prompt is executable application behaviour. Editing it without a version, evaluation diff or review record makes failures difficult to reproduce and roll back.

Keep version and approval distinct

The offline foundations lab stores two authored prompt records.

from foundation_cases import prompt_version_case

result = prompt_version_case()
assert result["unique_versions"] is True
assert result["review_complete"] is False
assert result["published"] is False
print(result["versions"])

refund-v1.0.0 is the initial contract; refund-v1.1.0 adds unsupported-case abstention. Both reference the same evaluation set and have reviewer pending, so neither is presented as approved or published.

Version the rendered behaviour

Store the instruction template, few-shot examples, output schema, tool descriptions, retrieval template and relevant decoding settings. Templates can render differently depending on framework defaults, so retain a redacted rendered request or digest for evaluated cases.

Use a simple convention your team can enforce. A major change may alter task/output compatibility; a minor change may add supported behaviour; a patch may clarify wording without intended contract change. Regardless of label, rerun the relevant evaluation because small text edits can change behaviour.

Require a release record

For every candidate, capture author, timestamp, reason, linked issue, model snapshot, task-set version, per-slice results, critical regressions, cost/latency notes, reviewer and disposition. Preserve rejected versions and why they failed. Release through an approved pointer so rollback restores the previous complete configuration.

Separate development, reviewed and production states. A passing automated gate does not authenticate human approval. Prevent applications from loading arbitrary working-copy prompts when a released version is required.

The Generative & Agentic AI course connects prompt versioning to evals, deployment manifests and incident recovery.

Exercise

Create three versions of one prompt, changing only one dimension at a time. Render and hash each, run a fixed task set, record transitions and reject one candidate. Demonstrate rollback by moving an approved pointer rather than editing files in place.

Continue learning

This article is part of the LLM fundamentals and prompt design sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Use a model-generated explanation without treating it as proof.
• Continue with Choose retrieval, fine-tuning or a better task definition.

Reference: Semantic Versioning specification.