How do I set up a prompt registry for tracking prompt changes and approval history across our AI product team?

A good prompt registry is basically source control + metadata + approvals + audit trail for prompts. The goal is to make every production prompt discoverable, versioned, reviewable, and attributable.

1) Define what the registry must track

At minimum, each prompt entry should store:

• Prompt ID / name: stable identifier
• Owner: person or team responsible
• Purpose / use case: what the prompt is for
• Current version
• Prompt content
• Status: draft, in review, approved, deprecated, blocked
• Environment: dev, staging, prod
• Model compatibility: which model(s) it’s intended for
• Variables / inputs: placeholders and required fields
• Test cases / eval results
• Approval history: who approved, when, and notes
• Change history / diff
• Links: ticket, experiment, incident, design doc

2) Use a versioning model

Treat prompts like code.

Recommended approach:

• Semantic versioning if changes affect behavior meaningfully:
  • 1.0.0 initial production version
  • 1.1.0 small behavioral tweaks
  • 2.0.0 major rewrites
• Or use incremental revision numbers if your team wants simplicity:
  • prompt_checkout_summary:v12

Each version should be immutable once approved. Never overwrite a released prompt in place.

3) Establish a prompt lifecycle

A simple workflow:

1. Draft
2. Review
3. Test / eval
4. Approved
5. Released to production
6. Deprecated / archived

You can gate promotion between stages with required checks:

• owner review
• safety review
• legal/compliance review, if needed
• evaluation threshold met
• sign-off from product/engineering

4) Decide where the registry lives

Common options:

Option A: Git-based registry

Best if your team already uses Git and wants tight version control.

• Store prompts as files in a repo
• Each prompt in YAML/JSON/Markdown
• Use pull requests for changes and approvals
• Git history becomes the audit trail

Pros:

• Easy diffs
• Strong approval workflow
• Familiar to engineering teams

Cons:

• Less friendly for non-technical users
• Harder to search/visualize without tooling

Option B: Database-backed web app

Best if you need a productized registry UI.

• Prompts stored in DB
• UI for editing, review, approval, search, and history
• API for runtime systems to fetch approved prompt versions

Pros:

• Great UX for cross-functional teams
• Better search, filters, analytics

Cons:

• Requires building/maintaining a tool

Option C: Hybrid

Very common and often best:

• Git for source-of-truth prompt files
• Web UI for browsing, approvals, and deployment
• Sync approved versions into a runtime store

5) Design the data model

A practical schema might include:

Prompt table

• prompt_id
• name
• description
• owner
• use_case
• status
• current_version
• created_at
• updated_at

Prompt version table

• version_id
• prompt_id
• version_number
• content
• change_summary
• created_by
• created_at
• approved_at
• approved_by
• released_at
• environment
• model_target
• metadata (JSON for tags, variables, eval links)

Approval history table

• approval_id
• version_id
• reviewer
• decision
• comments
• timestamp

Evaluation table

• eval_id
• version_id
• test_suite
• score
• pass_fail
• notes

6) Add approval rules

Define approval requirements per prompt type. Example:

• Low-risk prompts: owner + one reviewer
• Customer-facing prompts: owner + PM + engineer
• High-risk prompts: owner + PM + legal/compliance + safety

Useful rules:

• No production release without an approved version
• Only one active prod version per prompt
• Any material change requires re-approval
• Approvals expire after major model changes or after a time window

7) Track diffs clearly

Make it easy to answer:

• What changed?
• Why did it change?
• Who approved it?
• What impact did it have?

Store:

• line diff of prompt text
• structured diff of variables/instructions
• changelog entry with rationale
• linked experiment or incident notes

8) Connect prompts to runtime usage

Your registry should know:

• which app/service uses which prompt
• which version is active in each environment
• deployment timestamps
• rollback path

This lets you quickly answer: “Which users were affected by prompt v14?”

9) Add testing and evaluation

Before approval, require evidence:

• sample inputs/outputs
• rubric-based evaluation
• regression tests
• red-team / safety checks if relevant

Even a lightweight eval harness helps prevent accidental quality regressions.

10) Practical implementation pattern

If you want a simple starting point:

Folder structure in Git

prompts/
  customer_support_reply/
    prompt.md
    metadata.yaml
    versions/
      v1.0.0.md
      v1.1.0.md
      v2.0.0.md

Example metadata

name: customer_support_reply
owner: support-ai-team
status: approved
current_version: v1.1.0
model_target: gpt-4.1
variables:
  - customer_name
  - issue_summary
approvals:
  - reviewer: alice
    role: pm
    date: 2026-07-10
  - reviewer: bob
    role: engineer
    date: 2026-07-11

11) Governance tips

• Assign a prompt owner for every prompt
• Require a change summary for every edit
• Keep approved versions immutable
• Use audit logs
• Restrict prod publish rights
• Review prompts regularly for drift, stale instructions, and policy changes

12) What “good” looks like

A mature prompt registry lets anyone on the team answer:

• What is the current approved prompt?
• Who approved it and why?
• What changed from the last version?
• Is it safe to use in production?
• Where is it deployed?
• Can we roll back quickly?

If you want, I can also give you:

1. a Notion/Airtable template for a prompt registry,
2. a GitHub-based workflow with PR approvals, or
3. a database schema + API design for building one internally.