Prompt Versioning and Management

A prompt is the primary interface between your application and the language model. It encodes your requirements, constraints, tone, and output format. When a prompt changes, the system's behavior changes — often subtly, sometimes catastrophically. Without versioning, prompt changes are untracked, unreviewable, and impossible to roll back.

Storing prompts as code

The simplest approach is to store prompts in your source repository alongside the code that uses them. Each prompt is a text file or a structured template with clearly named variables. Changes go through pull requests, code review, and your standard CI pipeline. This ensures every prompt change is attributed, reviewed, and deployed with the code that depends on it.

# prompts/support_agent_v2.txt
SYSTEM_PROMPT = """
You are a support agent for Acme Cloud Storage.
Always verify the customer account before sharing billing information.
Respond concisely: answer the question, then ask if there is anything else.
Do not discuss competitor products.
"""

# Load at startup, pass explicitly
def get_system_prompt(version: str = "v2") -> str:
    path = f"prompts/support_agent_{version}.txt"
    return open(path).read()

Prompt templates with variables

Most prompts need dynamic content: user names, retrieved documents, or task-specific context. Use a lightweight template system (Python f-strings, Jinja2, or Mustache) to separate the static skeleton from the dynamic values. Render the final prompt at runtime by injecting variables — this keeps the versioned skeleton readable and testable independently of runtime state.

Prompt registries

As teams grow, a prompt registry provides a central store where prompts are named, versioned, and tagged (staging, production). Engineers pull prompts by name and version at runtime rather than embedding them in code. This allows prompt updates to be deployed independently of code releases — useful for fast iteration — while maintaining a full audit trail.

• Name prompts descriptively: include the task and audience (e.g., support-agent-billing-v3)
• Tag each version with the eval scores it achieved before promoting to production
• Never delete old prompt versions — you may need to roll back
• Review prompt diffs in pull requests with the same attention you give code diffs