Write the job down before you write the prompt
Most unreliable AI features fail before the first model call. A one-page brief is the cheapest fix there is.
Sample post Placeholder content that shows the blog's design. Replace it before launch.
When an AI feature behaves differently every time, the first instinct is to tweak the prompt. Add a sentence, bold a word, try another model. Sometimes it helps. Usually it moves the problem somewhere else.
The real issue tends to come earlier: nobody wrote down what a good answer looks like.
The brief is the spec
Before any prompt, I write a short brief. It fits on one page and answers four questions:
- What goes in? The real inputs, including the messy ones: empty fields, pasted HTML, a PDF someone scanned sideways.
- What comes out? The exact shape of a good answer, and who or what consumes it next.
- What does “wrong” look like? The mistakes that matter, ranked. A missing field is annoying; an invented one is dangerous.
- What is the model not allowed to do? Touch production data, guess when unsure, answer outside the task.
Why this pays off
A brief turns taste into something you can check. Once “good” is written down, every later layer has something to hold on to:
- the output schema comes straight from question two,
- the tests come from question three,
- the guardrails come from question four.
Without it, each of those layers ends up encoding a slightly different opinion of what the feature is for.
A small example
Say the job is pulling contact details out of organization websites. A first brief might be one line: “Extract the email and phone.” A useful one reads more like this:
Input: the visible text of one web page (may be empty or truncated)Output: { email: string | null, phone: string | null, source_url: string }Wrong: inventing an address > returning a personal address > missing oneNever: guess. If it isn't on the page, return null.Four lines, and the model now has a way to be right, a way to say “I don’t know”, and a clear sense of which mistakes cost the most.
Start here
If your AI feature feels unpredictable, don’t open the prompt first. Open a blank page and write the job down. It is the least glamorous step, and it is the one everything else builds on.