Iterating on Prompts

Tuning by feel never converges: one sample looks better, and a different kind of input breaks in production. Get a ruler, move one thing, and compare against the previous run.

The first chapter settled how to say it: brief the job clearly, and it can come back right the first time. But one success and a repeatable one are different things. In real work, a prompt rarely comes out right the first time — it gets tuned. And tuning has a precondition: you have to be able to judge whether this change actually made the result better — otherwise a change is only a new wording.

After reading, you should be able to answer:

Why does "changed it, tried one sample, felt better" carry almost no information?
How many samples belong in that test set, how do you pick them, and why are the edge cases non-negotiable?
When the score improves, what else do you have to look at before trusting the change?

Make changes attributable, and the rest of the discipline follows

For an adjustment to be explainable, two things have to be held under control at once: only one variable goes in at a time, and there is a fixed thing to measure the result against. The first tells you who did the work; the second tells you how much work was done. Lose either one and the conclusion after the edit is just an impression.

Touch one place at a time. Change three places at once and even an improvement tells you nothing about whose credit it is — and worse, two may have been right while one was wrong, with the net effect showing up as a tiny gain, so the harmful one survives alongside the others. It then becomes a sentence nobody dares delete.

Leave one line of record per change. Note what you changed, what problem it targeted, and how the score moved. That line turns out to be worth a great deal — half a year on, if someone asks whether a given constraint can be removed, you have the evidence in hand.

Roll back anything that did not help. Do not keep a line because you spent time writing it. Every extra sentence in a prompt costs money, dilutes the focus, and adds to the maintenance burden later.

The order you work in has a priority too: fill in what is missing from the parts, then add examples, then tune techniques, with parameters last. The earlier the step, the more score it buys back.

What that ruler should look like

The "fixed thing" mentioned above is the sample set that keeps coming up in this chapter.

Take twenty to thirty inputs drawn from real situations and pair each with an answer you would accept — or, at the very least, with a standard for calling it right or wrong. Every prompt decision you make from then on gets measured against it.

When you choose them, let ordinary cases make up the bulk and deliberately keep a few edge cases: overlong inputs, incomplete ones, oddly formatted ones, and the ones where you want it to answer "I don't know." One pattern is worth knowing in advance — the edge cases are always the first to be sacrificed, and they are precisely the ones that break in production.

This work takes half a day to a full day. Of everything you invest in prompt work, it returns the most for a one-time cost, because every later decision — editing the prompt, swapping models, adding a technique — gets judged against it. Model selection and fallback lean on the same set.

The data has a second use: it is drawn from the same pool you take prompt examples from. The good samples go into the prompt as examples; the rest stay behind as the test set — just be careful that the same item never serves both roles, or the number you measure is meaningless.

The official guidance puts "build an evaluation before you edit the prompt" first in the iteration loop. anthropic-prompt-eng That is not process fussiness: without a ruler you are changing two variables at once — the prompt, and your own impression of it.

Why trying one sample does not count

With the ruler in hand, the step that gets skipped most is running the whole set.

Trying a single sample afterwards and deciding it "feels better" is the most common self-deception in this work, and the reason is simple: the item you picked is usually exactly the scenario the change targeted. The edit was made to get that kind of input through, so of course it passes. Run the whole set; read the total and read it item by item.

Set the whole run beside the previous one

Once the results for the full set are in hand, the easiest mistake is staring at this run's absolute number.

A number with nothing to compare against says very little. A set of 24 samples passing 20 this time — good or bad? That depends on where it stood last time, and on which 20 passed. So every change has to be set side by side with the previous run over the same set, and compared down to individual items.

Passing 19 last time and 20 this time looks like movement in the right direction. Spread the items out, though, and "four better, three worse" means the change carries real risk — it may simply have traded one class of error for another. This pattern, a small gain overall with large movement underneath, slips through review most easily and is the most likely to produce a new failure class in production.

So read results on at least three levels:

The total, to see whether the direction is right.
The item-level diff, to see whether errors were relocated.
The regressions, to see whether they are cases you actually care about. Some items matter far more than others; if those got worse, a higher total still should not ship.

One more discipline about timing: do not let other changes sit between the edit and the evaluation. Swap the model version, change retrieval parameters, and edit the prompt on the same day, and a score change tells you nothing about the cause. Introduce one variable at a time, and that variable includes the model itself.

Tell "unclear" apart from "unstable" by running it three times

These two problems have completely different fixes, but they look alike, so separate them first.

Run one input three times in a row: wrong all three times in the same way means the prompt itself is unclear, and you should go fill in a missing part; results drifting up and down across the three means the problem lives in randomness, and you should adjust the sampling.

When in doubt, run one input three times — a small habit that saves a great deal of wasted tuning. It splits the vague feeling of "it answered badly" into two actionable diagnoses.

The most repeated piece of advice in the official guides — "change one variable at a time and record the result" — is essentially these two disciplines. openai-prompt-eng

Before you stop, check the sample set has not expired

The longer you tune, the more likely a different problem appears: two odd samples just will not pass, so you add an awkward instruction aimed squarely at them. Those two pass as hoped, and everything else in production gets worse.

The signal is clear: you have started writing rules around single samples. Stop and ask whether that sample is genuinely representative. If it is a lone outlier, accept that it fails occasionally.

There is a deeper judgment here too: your sample set expires. After launch, real inputs change shape — users phrase things differently, the business adds a rule, an upstream data format shifts. The test set has to follow real traffic, or you spend your time optimizing a distribution that no longer exists. How to keep an evaluation set alive is covered separately.

Clear that hurdle and only then does it make sense to ask when to stop. A prompt is not after perfection; it is after "good enough and stable." Getting the failure share from half down to a tenth, and grinding that last tenth away, are two very different jobs — the second usually costs more. Spending that remainder on validation and fallbacks or human review is usually the better trade.

Three signs that you can stop:

The common inputs are stable, and remaining failures cluster in a few uncommon scenarios.
Failures are detectable. When it goes wrong you know immediately, rather than hearing it from a user.
There is a fallback. The failure branches are written — retry, degrade, hand to a human — instead of showing users a broken result.

When all three hold, move your effort elsewhere. Further prompt polishing now returns less than thickening the validation layer.

This is defining done before you start applied to prompts: decide what counts as done and how you will know, then begin editing. Once changes are attributable, recorded, and reversible, the remaining job is keeping it from falling apart — because prompts scattered through code quickly become a blob nobody dares touch.