Key Takeaway
Choosing a prompt versioning strategy early prevents the drift between development and production prompts that causes hard-to-debug quality regressions.
When to Use This Template
Use this ADR when your application has more than a handful of prompts, when multiple team members are editing prompts, or when you have experienced a production incident caused by an untested prompt change. Prompt versioning is a prerequisite for reliable A/B testing, safe rollbacks, and audit trails. This decision should be made before your prompt count makes migration painful.
ADR Template
# ADR: Prompt Versioning Strategy
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Date
YYYY-MM-DD
## Decision Makers
- [Name, Role]
## Context
### Current State
- Number of prompts in production: [count]
- Prompt change frequency: [e.g., "2-3 changes/week"]
- Current versioning: [e.g., "in-code, deployed with application"]
- Team members editing prompts: [count and roles]
- Recent incidents from prompt changes: [count and severity]
### Requirements
- Rollback speed: [e.g., "must be able to rollback within 5 minutes"]
- A/B testing: [required | nice-to-have | not needed]
- Audit trail: [required for compliance | nice-to-have | not needed]
- Non-engineer editing: [product managers need to edit prompts | engineering only]
- Testing pipeline: [automated evaluation required | manual testing acceptable]
## Options Considered
| Criterion | In-Code (Git) | Database-Backed | Prompt Registry | SaaS Platform |
|-----------|--------------|-----------------|-----------------|---------------|
| Version tracking | Git history | DB versioning | Built-in | Built-in |
| Rollback speed | Redeploy | Instant | Instant | Instant |
| Review workflow | PR review | Custom | Built-in | Built-in |
| A/B testing | Feature flags | Custom | Built-in | Built-in |
| Non-eng editing | No | Yes (with UI) | Yes | Yes |
| Deployment coupling | Coupled | Decoupled | Decoupled | Decoupled |
| Operational cost | None | DB maintenance | Service maintenance | Subscription |
| Lock-in risk | None | Low | Medium | High |
## Decision
We will use [approach] because [rationale].
### Migration Plan
1. Inventory existing prompts: [list of prompts to migrate]
2. Migration steps: [how to move prompts to new system]
3. Cutover strategy: [how to switch from old to new without downtime]
4. Rollback plan: [how to revert if migration causes issues]
## Consequences
- Workflow changes: [how prompt editing workflow changes]
- Tooling requirements: [new tools or infrastructure needed]
- Testing pipeline: [how prompt testing integrates with CI/CD]
- Team training: [onboarding effort for new workflow]
## Review Trigger
- [ ] Prompt count exceeds [threshold]
- [ ] Team editing prompts grows beyond [threshold] people
- [ ] Prompt-related incidents exceed [threshold]/quarter
- [ ] A/B testing requirement changesSection-by-Section Guidance
In-Code vs. Decoupled
In-code prompt versioning (prompts as TypeScript constants or template files in git) is the simplest approach and works well for small teams with fewer than 20 prompts. The main limitation is that prompt changes require a full deployment, making rapid iteration slow and rollbacks expensive. Once your team needs to iterate on prompts faster than your deployment cycle, or non-engineers need to edit prompts, a decoupled approach becomes necessary.
Testing Integration
Regardless of which versioning approach you choose, establish a prompt evaluation pipeline before it becomes critical. At minimum, maintain a set of test inputs with expected outputs that runs automatically when a prompt changes. This catches regressions that are invisible in code review. For production prompts, add a shadow testing stage where the new prompt runs alongside the old one on live traffic without affecting users.
Start with in-code versioning and migrate to a decoupled system only when you hit a specific pain point (slow iteration, non-engineer editing needs, A/B testing requirement). Premature migration to a prompt management platform adds operational complexity without proportional benefit for small prompt sets.
Never edit production prompts directly in a database or prompt registry without a review process. Prompt changes can have outsized impact on application behavior. Treat prompt changes with the same rigor as code changes: review, test, deploy with rollback capability.
Version History
1.0.0 · 2026-03-01
- • Initial ADR template for prompt versioning strategy