Write the spec before you write the prompt

Watch someone write a production prompt and the first thing they do is open a blank box and start typing instructions. “You are a helpful assistant that…” Then they run it, read the output, add a sentence, run it again. An hour later the prompt is three times longer and nobody can say what it is supposed to do.

The problem is rarely the wording. The prompt is answering a question that was never written down, so every edit is a guess at the question.

Five lines before the first instruction

We write a short spec before we write the prompt. It fits on an index card, and it answers five things:

• Who reads the output. A customer, an analyst, another program, a reviewer who signs off. The same facts get written very differently for each, and the model cannot guess which one you meant.
• What comes in. The shape of the input, where it comes from, and what is allowed to be missing. A prompt written against clean examples meets messy traffic on its first day.
• What comes out. The format, the fields, the length, the tone. If code parses the result, this is a contract, and it should be written like one.
• What it does when it cannot answer. Decline, ask, return an empty field, hand off to a person. If you do not decide this, the model decides it for you, usually by guessing confidently.
• What it must never do. The short list of outputs that would be an incident rather than a bad answer: inventing a policy, quoting a price, naming a person who was not in the input.

None of that is prompt engineering. It is the same requirements conversation you would have before writing any other component. It just tends to get skipped because a prompt feels like a sentence rather than a system.

The spec is what makes review possible

Without a spec, a prompt review turns into a taste argument. One person thinks the output is too long, another thinks it is too cautious, and there is nothing to settle it. With a spec, the review is a check: does this output match what we said we wanted, and does the prompt say what we said it would?

It also tells you which examples belong in your test set. The fallback case and the “never do” list each deserve real inputs that exercise them. That is the evaluation half of treating prompts like code, and the spec is where you find out what to evaluate.

Where it goes wrong

We have watched teams make the same few mistakes with this.

• Writing the spec after the prompt works. At that point it describes whatever the model happened to do, which is not the same as what the feature needed.
• Leaving out the fallback. It is the line that matters most in production and the one least likely to come up in a demo.
• Keeping the spec somewhere other than the prompt. If the two live in different places, the spec stops being true the first time someone edits the prompt in a hurry.

The fix for all three is the same: the spec sits next to the prompt, changes with it, and gets read in the same review.

Then write the prompt

With the five lines in hand, the prompt mostly writes itself, because you are translating decisions rather than discovering them. This is also where a tool helps. AlphaPrompt turns a plain idea into a structured prompt, grades it with concrete suggestions, and keeps every version searchable, so the prompt has one home instead of a scratch file. More on what it does is on the AlphaPrompt page.

Whatever you use, try it once on the next prompt you write: five lines first, then the instructions. The rewrites you skip will be the ones you used to blame on the model.