How Do You Version and Test Prompts Like Code?

How Do You Version and Test Prompts Like Code?

Put the prompt in a file, put the file in Git, and write test cases that run on every change. The prompt becomes a reviewable artefact with a history instead of a string somebody pasted into a dashboard. Everything else in this article is detail on top of that one move.

Teams resist it because a prompt feels like writing, not code. But a prompt is the logic of your feature. When it changes, behaviour changes, and if nobody can see the diff, nobody can review the decision.

We have built enough AI automations now to know how this fails. It is never dramatic. The output just gets slightly worse and nobody can say when it started.

Why Do Prompts Break Without Anyone Noticing?

Because the failure is quiet. Code that breaks throws an error. A prompt that breaks returns a confident, well-formatted, slightly wrong answer. There is no stack trace and no alert. The only signal is a human eventually noticing the output feels off, which can take weeks.

Three things cause the drift. Someone edits the prompt to fix one case and quietly breaks four others. The model provider ships a new version with different behaviour. Or the input data shifts, and the examples in the prompt no longer look like the things it now receives.

None of those are visible from the output of a single run. They are only visible when you run the same set of inputs before and after a change and compare. That comparison is what an eval is.

Where Should Prompts Actually Live?

In your repository, as plain text or YAML files, next to the code that calls them. Not in a database row, not in a vendor console, and not pasted into an automation tool's text box where the last edit has no author and no date.

The practical benefit is review. A prompt change arrives as a pull request, a colleague reads the diff, and the reasoning lives in the PR description. Six months later, when the output looks wrong, you can find out exactly which change caused it and who decided it.

Keep the prompt separate from the code that fills it in. A file holding the template and a small function that injects variables is easier to test than a prompt assembled from string concatenation across three modules. We cover the writing side of this in our notes on prompt engineering for web work.

What Does a Prompt Test Case Look Like?

An input, an expectation, and a way to check the two match. OpenAI's evals guide describes the same shape with a specific vocabulary: an eval is a configuration describing the desired behaviour, testing criteria are the graders that determine if the model output is correct, and a run executes prompts against a dataset.

OpenAI's recommended loop is three steps. Describe the task to be done as an eval, run it with test inputs, then analyse the results and iterate on the prompt. The guide notes this mirrors behaviour-driven development, where you specify how the system should behave before you build it.

The simplest useful grader in that guide is string_check, which supports operations such as eq for an exact match and contains for a substring. That covers more real cases than people expect. Classification, extraction, and routing tasks all have checkable answers.

How Do You Grade an Answer With No Single Right Answer?

Pick a grading method that matches the shape of the task. Anthropic's documentation on developing tests lays out four approaches and they map cleanly onto real work. Exact match for categorical tasks such as sentiment classification. Cosine similarity for consistency. ROUGE-L for summarisation. An LLM as the grader for judgement calls.

The cosine similarity method uses sentence embeddings, and Anthropic explains the logic plainly: values closer to 1 indicate higher similarity, which makes it ideal for checking consistency, because similar questions should yield semantically similar answers even if the wording varies.

For subjective qualities, Anthropic describes LLM-based grading in three forms: a Likert scale for nuanced attitudes, binary classification for yes or no judgements, and an ordinal scale for ranking. The Likert version is aimed at things like empathy, professionalism, or patience that traditional metrics cannot quantify.

How Many Test Cases Do You Need?

More than feels comfortable, and rougher than feels rigorous. Anthropic's guidance is direct on this: prioritise volume over quality, because more questions with slightly lower signal automated grading beats fewer questions with high quality human hand-graded evals. The coverage is what catches the regression.

That inverts how most teams start. The instinct is to write ten immaculate cases with carefully worded ideal answers. The advice is to write a hundred rough ones that can be graded by a machine, because the hundred will catch regressions the ten never see.

Anthropic's other two principles are worth writing on the wall. Be task-specific, designing evals that mirror your real-world task distribution including edge cases. And automate when possible, structuring questions to allow automated grading such as multiple choice, string match, code-graded, or LLM-graded.

What Tools Actually Do This?

Promptfoo is the one we reach for most when the work lives in a repository. Its documentation describes it as an open-source CLI and library for evaluating and red-teaming LLM apps, built around simple declarative test cases rather than trial and error.

The parts that matter day to day are the delivery options and the speed. It runs as a command-line tool, a Node package, or a CI/CD integration, and it uses caching, concurrency, and live reloading to make the feedback loop fast enough that people actually use it.

The hosted alternatives from the model providers are fine too, and OpenAI's evals product is a reasonable place to start if your stack is already there. The choice matters far less than having any of them running at all.

How Do You Run Prompt Tests in CI?

Treat the eval as a check on the pull request, not a report someone reads later. When a prompt file changes, the pipeline runs the test set against it and posts the score. If the score drops below a threshold you agreed in advance, the check fails and the change waits.

Two practical warnings. Model calls cost money and take time, so a full suite on every commit gets expensive fast. Run a small smoke set on each push and the full suite on pull requests to the main branch. And cache aggressively, because most commits do not change the prompt at all.

Also accept that the score will not be stable to three decimal places. Set the threshold as a range rather than an exact number, or your build fails for reasons that have nothing to do with your change. We wrote more about that in our piece on evaluating AI automations in production.

What Should You Record When a Prompt Changes?

Four things, and they take a minute to write. Which model and version you tested against. The eval score before and after. The specific case that motivated the change. And the cases you knowingly made worse, because almost every prompt change trades one behaviour for another.

That last one is the discipline most teams skip, and it is the one that saves you later. A prompt improved for long documents is usually a prompt made slightly worse for short ones. If that trade is written down, the next person can see it was a choice rather than a bug.

Record the model version explicitly. A prompt tuned against one model version can behave differently on the next, and without a recorded baseline you cannot tell a provider change from your own. Where a human still signs off, our notes on human in the loop workflows cover how to place that review well.

Where Should a Small Team Start This Week?

Move one prompt into a file and write twenty test cases for it. Not your hardest prompt, and not a perfect set. Take the one that already caused an argument, collect twenty real inputs from your logs, and write down what a good answer looks like for each.

Run them, look at the score, and resist the urge to fix anything yet. The first number is not a grade on your prompt. It is the baseline that makes every future change measurable, and until it exists, every prompt edit is a guess with confidence attached.

If you want a hand setting that up, or a second opinion on where an automation is quietly drifting, we are happy to talk it through. We do this work with B2B teams every week at phoenix.studio, and the first eval usually takes an afternoon.