"It was in the prompt" is not an answer to "why did it do that?"
The conversation repeats itself at every company that puts an agent into production. The agent does something odd — promises a delivery date that does not exist, answers something that was not its job, invents a procedure — and someone asks what happened. The answer is always the same: "it was in the prompt." And then come the three awkward questions. Which version of the prompt? Who wrote that line? Did anyone test what happens when you take it out?
There is almost never an answer, and it is not sloppiness: it is that the word prompt nudges you into treating the text as a message. A message gets written once, sent and forgotten. But what governs an agent in production is not a message: it is the document that defines what it does, what it does not touch and who it calls when it gets stuck. That has another name in any organisation: a job description. And job descriptions have an owner, a version and a review date.
It is not a convenient metaphor. Anthropic's own documentation recommends thinking of the model as "a brilliant but new employee who lacks context on your norms and workflows," and offers a golden rule that works just as well on humans: show your instructions to a colleague with minimal context and ask them to follow them; if they would be confused, the model will be too. Source: Prompting best practices, Claude Platform Docs, accessed 11 September 2026.
This guide is about writing that document. It is not a prompting course or a magic template to copy: it is the minimum structure that survives production, the part almost everybody gets wrong, and the habit that separates iterating from praying.
The six things that have to be written down
Platform, model and use case do not change this. If any of these six blocks is missing, the agent will fill it in on its own, and what it fills in is not something you decided. In the architecture OpenAI describes, an agent is three pieces — model, tools and instructions — and the instructions are the "explicit guidelines and guardrails defining how the agent behaves." Explicit is the operative word. Source: A practical guide to building agents, OpenAI, accessed 11 September 2026.
| Block | What it answers | What happens if it is missing |
|---|---|---|
| Identity and channel | Who it is, who it talks to and where | Tone and register drift by the day |
| Scope | What it handles and what it does not | It answers everything, including what it does not know |
| What it can decide | Where proposing ends and executing begins | It executes things nobody authorised |
| Output format | What shape the result comes out in | The destination system rejects it silently |
| What it does when it does not know | The honest default exit | It fills the gap with something plausible |
| When it escalates | The exact threshold that calls a human | Nobody finds out until there is a complaint |
Look at the right-hand column: none of those failures shows up as an error. They all show up as behaviour, which is far more expensive to detect. An agent that crashes tells you; an agent missing its scope block works away happily for weeks answering things that were never its job.
The negative-rules mistake (and what to write instead)
This is the most useful correction in the whole guide, and it cuts against what nearly everybody does. When an agent misbehaves, the reflex is to add a prohibition: "never promise delivery dates," "no emoji," "never quote prices." The list of nos grows week by week until it is a rulebook, and the behaviour keeps showing up.
Anthropic's documentation is explicit about this: tell the model what to do instead of what not to do. Its own example for controlling format is exactly this: instead of "do not use markdown in your response," write "your response should be composed of smoothly flowing prose paragraphs." And when the prohibition is unavoidable, the same guide recommends attaching the reason: "NEVER use ellipses" performs worse than "your response will be read aloud by a text-to-speech engine, so never use ellipses since the engine will not know how to pronounce them." The model generalises from the explanation; from the bare prohibition, it does not. Source: Prompting best practices, Claude Platform Docs, accessed 11 September 2026.
The operational translation is simple and it is work: every time you are about to write a "do not," stop and answer two questions. What do I want it to do instead? and why? What comes out of that is the rule to write.
| What gets written | What actually works |
|---|---|
| "Never promise delivery dates" | "When asked about a delivery date, give the one the order system returns. If it returns nothing, say you will confirm and open a query, because a wrong date turns into a complaint." |
| "Do not make things up" | "Answer only with what you find in the documentation. If it is not there, say so in those words and offer to pass the question to a person." |
| "Do not give discounts" | "Discounts are approved by the sales lead. If a customer asks for one, log the request with the amount and notify sales; do not confirm anything yourself." |
There is one exception worth knowing: hard safety constraints — the things that must never happen under any circumstance — are written in the negative and written flatly, and it helps to repeat them at the start and at the end of the document. But that is two or three lines, not forty. The rest of your rulebook of nos is, almost always, a positive specification nobody has sat down to write.
What it decides, what it proposes and what it does not touch
The block that saves the most money is the shortest one. Take every action the agent can execute and sort it into three columns: it does this alone, it leaves this proposed for someone to confirm, or it does not touch this. And write it with numeric thresholds, not adjectives: "large amounts" is not a threshold, "above 300 euros" is.
To decide which column each action belongs in, OpenAI's guide proposes rating the risk of each tool — low, medium or high — on four factors: read-only versus write access, reversibility, the permissions it requires and its financial impact. That rating is what triggers the pause or the escalation, and it is a far more defensible criterion than the intuition of Tuesday's meeting. Source: A practical guide to building agents, OpenAI, accessed 11 September 2026.
This block of the instructions and the agent's technical permissions are two different things that have to say the same thing. The instructions say what it should do; the permissions determine what it can do. If the document says it does not issue refunds but the credential has the scope to issue them, the only thing standing between your company and an improper refund is the model behaving well, which is not a control. How you close that gap is in what permissions to give an AI agent, and the map of how much autonomy to release and in what order is in levels of agent autonomy.
What it does when it does not know, and when it calls a human
Without an explicit instruction, the default behaviour in the face of a gap is to fill it with something plausible. Not because the model lies, but because nobody has given it a better exit. The better exit is one line and it changes daily operations: "if the answer is not in the documentation, say so in those words, do not infer it, and offer to pass the question to a person."
Escalation is the other half. OpenAI treats it as a first-class safeguard and describes two triggers worth copying verbatim: exceeding a failure threshold — if the agent has not understood the intent after N attempts, transfer — and high-risk actions, meaning anything sensitive, irreversible or high-stakes; the examples it gives are cancelling orders, authorising large refunds and making payments. Source: A practical guide to building agents, OpenAI, accessed 11 September 2026.
Write those two triggers with numbers and with a recipient. Not "escalate when necessary," but "after two attempts without identifying the order, hand the conversation to customer support with the summary and the history." The difference between those two wordings is the difference between an escalation that happens and one that does not.
One thing at a time: the habit that separates iterating from praying
Nearly everybody tunes instructions the same way: spot an odd behaviour, rewrite four paragraphs, eyeball two test cases and ship it. If it improves, you do not know which of the four changes fixed it. If it gets worse, you do not know which one broke it. That is not iterating, that is praying with intermediate steps.
The habit that turns it into engineering fits in three rules. One. Change one thing at a time and write it down: what you changed, why, and what you expected. Two. Keep the before and the after of the same cases — the ten or fifteen that represent your real operation, odd ones included — because without the before you have nothing to compare against. Three. Leave the previous version somewhere you can restore in under a minute, because the change that breaks something almost never breaks it during the test; it breaks it the following Tuesday.
These three rules are manual and they work in a spreadsheet, which is where they should start. Once the agent stops being one agent and becomes a fleet, keeping the log by hand stops holding, and this turns into an operational function with a single source of truth, a test suite before deploying and a one-minute rollback: that is testing and versioning AI prompts, and it is a service, not a tip. What decides the jump is not the size of the team, it is the number of people who can touch the document.
And a warning that saves weeks: if the agent fails because it cannot find the information, the problem is not in the instructions and rewriting them will not fix it. It is in what it can look up — how that gets built and evaluated is in training an AI agent — or in what it should remember between conversations, which is an AI agent's memory. The three get fixed in different ways, and confusing them is the most common way to lose a month.
The one-page sheet: who signs it and when it was reviewed
Close the document with a five-field header. It is not bureaucracy: it is what turns a loose text into an artefact somebody maintains.
- Owner. A named person, not a department. Whoever answers when the agent does something odd.
- Version and date. A number that goes up and the day it went up. Without this you cannot say what was running last week.
- What changed and why. Two lines per version. It is the log that stops you repeating a failed experiment six months from now.
- Test cases. Where the ten or fifteen cases used to check every change live, and who keeps them current.
- Next review. A date. Instructions expire when the policy, the catalogue or the destination system changes, and nobody tells you.
If your agent is already in production and this document does not exist, the order is this: write the "what it can decide" block and the "when it escalates" block first, because those are the two with money in front of them. The rest can wait a week. And the day someone asks "why did it do that?" again, you will be able to open a file, look at a version and answer.
We write that document with the client in the room and leave it signed, versioned and with its test cases attached: it is part of building AI employees that actually work, inside the general logic of building an AI agent that survives production. We do not sell the prompt. We charge for anyone on your team being able to read what your agent does and why, without asking anybody.