Write a prompt somebody else can maintain

A prompt that works is not the same as a prompt somebody can inherit. The first is an afternoon’s effort. The second is a document, and almost nobody writes it.

Here is the shape of the failure. One person writes a prompt over a few days, tuning by feel. It works. They move teams. Six weeks later the model provider ships an update, output quality shifts, and the person now responsible is looking at four hundred words of instruction with no idea which parts matter, which were superstition, and which are load-bearing. So they rewrite it from scratch, and the organization pays twice for the same thinking.

The parts that actually do work

A maintainable prompt has five sections, and they should be visibly separate rather than run together into a paragraph. Somebody debugging it at nine at night needs to know where to look.

The role and the audience. Who the model is writing as, and who reads the output. “You are writing for a scheduler who processes ninety of these a day and will not read a preamble” constrains far more usefully than “you are a helpful assistant”.

The input contract. What arrives, in what shape, and what might be missing. If a field is optional, say so here rather than letting the model discover it. This is the section that prevents the most incidents, because production data is messier than whatever you tested on.

The task. What to produce, as a numbered sequence if order matters. Numbered steps are easier to remove one at a time when you are working out which instruction is carrying the weight.

The output shape. Exactly what comes back. A label from a fixed list, a JSON object with named keys, three bullets. This is the section your code depends on, so changing it is a breaking change and should be treated like one.

The refusals. When to decline and what to say instead. A prompt with no refusal path produces a confident answer for every input, including the ones where the honest output is “this does not contain what you asked for”.

Write down why each instruction is there

This is the part that makes a prompt maintainable, and it is the part everyone skips.

Most long prompts accumulate a layer of sediment: lines added to fix a specific complaint, never removed, their reason forgotten. “Do not use the word leverage.” “Always include the record id.” “Never guess a date.” Each was a real fix once. Now they are folklore, and nobody dares delete any of them because nobody knows what breaks.

The fix is unglamorous: a comment against each non-obvious instruction, naming the failure it prevents. Keep it next to the prompt, in the same file, versioned together.

Then the inherited prompt becomes readable. “Never guess a date — a referral with no date was being assigned today’s, which put it at the wrong end of the queue” is a line the next person can evaluate. They can check whether that failure mode still exists, and delete the line if it does not. Without the comment they can only guess, and guessing means keeping everything forever.

That is the opening. The rest of the lesson — the remaining sections, the exercise and the check-your-understanding questions — is behind the gate below.