Writing a Prompt as a Specification

Most prompts start as a sentence typed quickly and get edited only when results disappoint. That works for a one-off question. It fails when the prompt is part of a product, because nobody can say what it is supposed to do, so nobody can tell when it has stopped doing it. A specification is a document that states what a correct output looks like. A prompt written as one can be tested, versioned and handed to someone else.

The parts of a specification prompt

A useful prompt usually contains a few distinct parts. The task states what the model should do, in one sentence if possible. The inputs describe what the model will receive, where each piece appears in the message, and what it may look like, including missing or messy cases. The constraints say what must hold: length limits, required fields, sources the model may or may not use. The output format defines the exact shape of the answer.

Examples show two or three inputs with their correct outputs, chosen to cover a typical case and at least one edge case. A final clause says what to do when the input is insufficient or ambiguous. Without that clause, the model will decide for you, and it will decide differently on different days. State the audience and what they will do with the output. That single line settles many questions about tone, detail and length that would otherwise be guessed. A summary for an engineer reviewing a change and a summary for a customer reading a status update need different specifications, even when the task is described in the same words.

Constraints and the edges

Most failures happen at the edges. What should happen when the input is empty, when two instructions conflict, when a value falls outside the expected range, or when the request lies outside the task? If the prompt does not say, the model will choose a plausible behavior, and plausible behavior varies.

Write each edge as an explicit rule. A sentence such as "If the customer name is missing, return null for the name and set needs_review to true" can be checked by a test. Keep the rules few and specific. A long list of vague cautions such as "be careful with sensitive details" is less useful than three exact rules that someone could verify.

When two rules can conflict, state which one wins. A line such as "the source document takes priority over general knowledge" settles a question that would otherwise be decided by the model's habits. Precedence rules are easy to skip because the conflict has not yet appeared, and they are cheap to add now.

Examples that teach the boundary

Examples are the strongest part of a prompt when they are chosen well. Pick examples that show the typical input and at least one case where the easy answer is wrong. If the task has a common mistake, include a negative example and label it clearly as wrong. Avoid examples that all look alike, because the model will copy their surface features along with their substance. Keep the examples in the same format as the real inputs, and check that each one is actually correct, since a wrong example teaches a wrong rule. An example is evidence about what you want, not a rule to be copied word for word. State the rule in words as well, so the example is not the only place the rule lives. If the example is later changed or removed, the rule still stands.

Versioning and testing

Give each prompt an identifier and a short change record. The record should say what changed, why, and which evaluation results support the change. Store prompts in version control next to the code that calls them, or in a system where every version can be restored.

Test the prompt against a set of examples with stated expectations. For simple tasks the expectation can be an exact output. For open-ended ones it is usually a property, such as "contains exactly three bullet points" or "does not include a customer's phone number." Run the set after every change. A prompt edit that fixes one case and breaks four others is common, and only a test set reveals it. Record who approved each change and which test results they relied on. That record is useful when a prompt behaves oddly months later, and it turns a prompt from a personal habit into something a team can review.

Common mistakes and a practice exercise

Several mistakes recur. Goals stated as adjectives, such as "make it professional" or "be concise," have no test attached. A prompt that asks for several tasks at once produces outputs where one task quietly suffers. An unstated audience turns tone into a guess. Instructions that conflict, such as "be thorough" alongside "keep it under fifty words," get resolved unpredictably. Hidden assumptions, such as that the input is always in English or always complete, fail without any visible warning.

For practice, take a prompt you use, or a vague one you wrote recently. Rewrite it as a specification with the parts described above. Then write five test cases: two typical inputs, two edge cases, and one input that tries to break the output format. Run both the original and the rewritten version on all five, and note which passes. The comparison makes the value of the specification concrete, and the rewritten version becomes the first entry in a prompt you can maintain.