How to version prompts in production

A good way to version prompts in production is to treat them like application code: immutable, traceable, testable, and rollable back.

Practical approach

1. Give every prompt a stable ID

Use a human-readable name plus a version.

Example:

• support_reply:v1
• support_reply:v2
• classification_invoice:v3

Avoid overwriting the same prompt in place. Create a new version instead.

---

2. Store prompts in a prompt registry

Keep prompt definitions in a central place, such as:

• a database table
• a config service
• a Git-backed repo
• a prompt management tool

Each entry should include:

• prompt ID
• version
• template text
• variables/schema
• model settings
• owner
• created_at
• changelog
• status: draft, active, deprecated

---

3. Make versions immutable

Once v2 is deployed, never edit it.
If you need a change, create v3.

This makes rollback and debugging much easier.

---

4. Reference prompts by alias in production

Use an alias like:

• support_reply:prod

That alias can point to v2 today and v3 tomorrow.

This gives you:

• safe releases
• instant rollback
• controlled rollout

---

5. Version the prompt inputs too

Prompt text is only half of it. Also version:

• input schema
• output format/schema
• tools/function definitions
• system messages
• safety policies
• few-shot examples

A prompt may behave differently if any of these change.

---

6. Pair prompt versions with evals

Before promoting a new version:

• run offline test cases
• compare outputs against previous version
• check quality metrics
• test edge cases
• validate structured output

Use regression tests like you would for code.

---

7. Log prompt version with every request

At runtime, log:

• prompt ID/version
• model name/version
• temperature/top_p
• tool versions
• input hash or request ID
• output hash
• timestamp
• user/session metadata if allowed

This is critical for debugging and audits.

---

8. Roll out gradually

Use deployment strategies such as:

• canary release
• A/B test
• percentage rollout
• tenant-based rollout
• feature flags

Example:

• 5% of traffic on v3
• if metrics hold, increase to 50%
• then 100%

---

9. Keep a changelog

For every prompt version, record:

• what changed
• why it changed
• expected impact
• known risks
• evaluation results

This helps your team understand why a prompt exists.

---

Simple versioning model

A practical naming scheme:

prompt_name / major.minor.patch

Example:

• support_reply/1.0.0
• support_reply/1.1.0
• support_reply/2.0.0

Use:

• major for breaking changes
• minor for behavior changes that preserve compatibility
• patch for wording fixes or small adjustments

---

Example registry record

{
  "prompt_id": "support_reply",
  "version": "1.2.0",
  "status": "active",
  "template": "You are a support agent. Answer concisely...",
  "input_schema_version": "1.0.0",
  "model": "gpt-4.1-mini",
  "temperature": 0.2,
  "owner": "support-ai",
  "created_at": "2026-10-22T12:00:00Z",
  "changelog": "Improved tone for refund requests"
}

---

Recommended production pattern

If you want a robust default:

1. Store prompts in Git or a registry
2. Use immutable versions
3. Deploy via aliases
4. Run evals before promotion
5. Log version on every request
6. Roll out gradually
7. Keep rollback one-click

---

Common mistakes

• editing prompts in place
• not logging the version
• changing prompt and model at the same time without tracking
• no evals before release
• no rollback path
• treating prompts as “just text”

---

If you want, I can also give you:

1. a prompt versioning schema
2. a Git-based workflow
3. a database table design
4. a production rollout checklist