How to Write Instructions AI Agents Actually Follow

Most agent failures are instruction failures. When an agent does the wrong thing, skips a step, or improvises with confidence, the usual cause is an instruction that was vague, contradictory, or buried. Agents follow instructions literally and fill gaps with guesses instead of questions. Precise instructions turn a flaky agent into a reliable one. The sections below cover how to write them, with five before-and-after rewrites, a reusable template, and the testing routine that proves an instruction works before real work depends on it.

Why agents need different instructions than people

When you ask a colleague to handle something, they bring a lifetime of context: they know which shortcuts are acceptable, when to ask before acting, and what you meant as opposed to what you said. An agent brings none of that. It reads your words literally, fills gaps with guesses instead of questions, and has no sense of which mistakes are small and which are career-ending. Telling an agent to be careful is like telling a calculator to be careful: the word has no operational meaning to it. Every expectation you have must be spelled out as a concrete rule. This feels tedious at first, and it is. But the tedium is the entire job: the gap between what you assumed and what you wrote is exactly where agent failures live.

There is a second difference that matters just as much. People ask clarifying questions when instructions are ambiguous; agents usually do not. An agent faced with ambiguity picks the most plausible interpretation and proceeds, because proceeding is what it is built to do. That means every ambiguity in your instructions is a decision you have delegated without realizing it. The fix is not to eliminate all ambiguity (some is unavoidable) but to add an explicit rule for what to do when ambiguity appears. That rule, the stuck rule, gets its own section below.

Describe the outcome, not just the activity

Vague instructions describe an activity and leave the agent to guess what done looks like. Precise instructions describe the finished result so clearly that you could check it in seconds. Compare research competitors with produce a table of our five closest competitors with columns for price, main feature, and one weakness, saved as a markdown file. The first invites improvisation; the second is checkable. Whenever you write an instruction, ask yourself: could a stranger tell whether the job was done right just by looking at the output? If not, you have not finished writing the instruction.

The practical technique is to write the acceptance check into the instruction itself. End the task description with a sentence starting with Done means. For example, Done means: a markdown file exists at this path, with a table containing exactly five rows and three columns, and every cell filled. This does two things at once. It tells the agent precisely what to produce, and it gives you a thirty-second verification routine. Explicit done-criteria give the agent something checkable to aim at and give you something checkable to verify, which good job does not, because good job is not a specification. Anthropic frames the same idea as a test in its prompting guide: show the prompt to a colleague with minimal context on the task and ask them to follow it; if they would be confused, the model will be too.

State the constraints up front

Agents do not know your boundaries unless you state them. The things you would never do (sending an email without review, spending money, deleting files) are all things an agent will happily do if the task seems to require it. Put the boundaries where the agent reads them before it starts planning: in a block ahead of the task steps, not buried in the middle of them. That is a layout choice, not a documented property of every model; the vendor guides quoted below differ on where the question or task should go relative to long reference material, so check the placement against your own runs. Do not send anything. Drafts only. Do not open attachments. If a step requires a password, stop and ask. Four sentences like these close off the most common ways a task can run past its brief.

Write constraints as prohibitions, not suggestions. Never delete files is a rule; please be careful with files is a wish. Agents respond to the operational kind. Cover four categories every time: what the agent must never do (send, publish, pay, delete, share externally), what it must always do (cite sources, show its work, ask before proceeding past a checkpoint), budget limits (maximum steps, maximum cost, or a time box for the task), and scope limits (which folders, accounts, or systems are in bounds; everything else is off limits). If a category does not apply, say so explicitly: not applicable is clearer than silence, because silence reads as permission.

Show one good example

A single concrete example is worth paragraphs of abstract description. If you want summaries in a particular format, paste a short example of that format. If you want a certain tone in drafted emails, show one email written the way you like. Agents are pattern-matchers: an example calibrates them faster than any amount of adjectives like professional or concise, which mean different things to different people. Keep a small library of examples for tasks you repeat, and reference them in your instructions.

Examples also protect you against your own vocabulary. Everyone has words they use loosely (thorough, detailed, brief) and an agent will interpret them at face value in whatever way seems most literal. An example pins the meaning down. If brief to you means three bullet points and to the agent means one sentence, the example resolves the argument before it happens. When a task's output keeps coming back wrong in the same way, the missing piece is almost always an example of the right way, not a stronger adjective.

What the vendor guides add

Two vendors publish prompt-engineering guidance that applies directly to agent instructions. Anthropic's prompting best practices says Claude responds well to clear, explicit instructions and asks the writer to think of the model as a brilliant but new employee who lacks context on your norms and workflows. Its test is concrete: show your prompt to a colleague with minimal context on the task and ask them to follow it; if they would be confused, the model will be too. It also advises specifying the output format and constraints, and giving sequential steps as numbered lists or bullets when order or completeness matters.

OpenAI's prompt engineering guide says outputs are non-deterministic, so prompting is "a mix of art and science", and recommends pinning production applications to specific model snapshots and building evaluation suites that measure prompt behavior. It also separates model types: GPT models benefit from more explicit instructions on how to accomplish tasks, while reasoning models do better with high-level guidance, which it compares to a junior coworker versus a senior one. That limits how far this guide's advice should be pushed. Spelling out steps, formats and stop conditions is the explicit style that OpenAI describes for its GPT models; for a reasoning model, start from the goal and add detail where a run shows it is needed. Both vendors say to re-check against your own evaluations, so treat the techniques here as defaults to test.

Examples: how many, and how to mark them

Anthropic's guide gives three properties for good examples: relevant (they mirror your use case), diverse (they cover edge cases and vary enough that the model does not pick up unintended patterns) and structured (wrapped in example tags, so the model can tell them from instructions). It suggests three to five examples for best results. OpenAI's few-shot section also asks for a diverse range of inputs, and shows labelled input and output blocks with matching ids.

OpenAI also describes a layout for the whole instruction block: identity, instructions, examples, then context, with Markdown headers marking sections and XML tags marking where a piece of content begins and ends, and the context near the end because it changes between requests. Anthropic's long-context advice differs on one point: long documents go near the top, above the query, and it reports that putting the query at the end can improve response quality by up to 30 percent in its tests, especially with complex multi-document inputs. The shared principle is to keep standing rules apart from bulky, variable material; the disagreement about where the question goes is a reason to test placement. A sketch of the OpenAI-style layout, with an invented task and a placeholder input:

# Identity
You triage incoming support emails for a small software company.

# Instructions
* Output exactly one label per email: billing, bug, how-to or other.
* If an email fits two labels, choose the one the customer asks about first.
* If you cannot tell, output other and nothing else.

# Examples
<email id="example-1">I was charged twice this month.</email>
<label id="example-1">billing</label>

<email id="example-2">The export button does nothing when I click it.</email>
<label id="example-2">bug</label>

<email id="example-3">Can you recommend a good lunch spot near your office?</email>
<label id="example-3">other</label>

# Context
<email>{{EMAIL_TEXT}}</email>

The three examples differ (a billing complaint, a defect report, an off-topic message), so they cover the other label instead of teaching only the happy path. The rules sit in a block of their own and the one input that varies per request comes last, inside its own tags. The examples are invented for illustration and were not run against any model; the structure is the point.

Give the reason, and say what to do

Anthropic recommends adding the motivation behind an instruction. Instead of "NEVER use ellipses", it suggests explaining that the response will be read aloud by a text-to-speech engine that cannot pronounce them, and says Claude can generalize from the explanation. Its formatting advice has the same shape: tell the model what to do instead of what not to do, so rather than "Do not use markdown in your response", ask for smoothly flowing prose paragraphs.

That sits in tension with the earlier advice to write constraints as prohibitions, and a workable resolution is to split by consequence. For routine style and scope, state the positive instruction with its reason. For actions that are hard to undo, keep a hard boundary but shape it the way Anthropic's own sample does. Its "balancing autonomy and safety" prompt encourages local, reversible actions such as editing files or running tests, and asks the model to check with the user before actions that are destructive (deleting files or branches, dropping tables), hard to reverse (force-pushing, hard resets, amending published commits) or visible to others (pushing code, commenting on pull requests, sending messages). It adds that destructive actions should not be a shortcut around an obstacle. That is a prohibition with categories, a reason and an exit, which is more usable than a bare NEVER.

Emphasis has a cost as well. Anthropic notes that Claude Opus 4.5 and 4.6 are more responsive to the system prompt than earlier models, so prompts written to reduce undertriggering can now overtrigger, and it suggests softening aggressive language: where you might have written "CRITICAL: You MUST use this tool when...", write "Use this tool when...". Those two models are named on the page, so treat the point as measured on them. Persistence instructions need similar care. OpenAI's agentic-tasks example tells the model to keep going until the query is completely resolved. That suits reversible, local steps and not the destructive categories above, which is why a stuck rule and an ask-first list belong in the same instruction set as any keep-going language.

A before and after, with the reasoning

The rewrite below is hypothetical and was not run against any model. It starts from the kind of instruction people write when they are worried:

You are a careful assistant. CRITICAL: NEVER delete anything! ALWAYS double-check your work. Clean up the downloads folder and don't make a mess. Be thorough but quick.

Each sentence means well and fails the colleague test. The rewrite follows, then the reason for each change.

Goal: Sort the files in ~/Downloads into subfolders named documents, images, installers, archives and other, so that no file is left at the top level of ~/Downloads.

Why the constraints exist: I will review the result before I delete anything, so every change must be easy to undo. Use move operations only, and append one line per move to moves.log in the form "old path -> new path".

You may do these without asking: create subfolders inside ~/Downloads and move files within ~/Downloads.
Ask me first, and wait for my answer, before: deleting any file, moving anything outside ~/Downloads, or opening a file you do not recognize.

If a file's type is unclear, move it to other and list it in your summary. If a move fails twice, stop and report the path and the error message.

Done means: nothing is left at the top level of ~/Downloads, every move appears in moves.log, and your final message lists how many files went into each subfolder and names every file placed in other.

• A vague task became a checkable goal. "Clean up the downloads folder" has no finish line. The goal now names the destination folders and the end state, in line with Anthropic's advice to be specific about the output and constraints.
• "Don't make a mess" became a named mechanism. Moves only, plus a log of each move, is what tidy means here, and the stated reason (the owner reviews before deleting) lets the agent judge cases the list does not cover.
• "NEVER delete anything!" became an ask-first list. A bare prohibition is either ignored in an edge case or over-applied. The rewrite uses the shape of Anthropic's reversibility sample, with freedom for local reversible actions and a stop for destructive or out-of-scope ones, and drops the capitals.
• "ALWAYS double-check your work" became a done condition. A check the agent can fail beats an exhortation: the final message must list counts per subfolder and every file placed in other, which you can verify in seconds.
• "Be thorough but quick" was deleted. The two words pull apart and the agent has to pick one, as the list of contradictory rules below warns. The two-failure stop is the real speed control.
• A stuck rule was added. The original says nothing about unrecognized files or failed moves; the rewrite gives a default (move to other and report) and a stopping point (two failures).

Whether the rewrite works for your agent and model is an empirical question. Anthropic says to treat model-specific techniques as measured on that model and to re-check them against your own evaluations, and OpenAI recommends snapshots and evaluations for the same reason. The three-run test later in this guide is the smallest version of that habit.

When the model changes, retest

Instructions age. Anthropic's guide says prompts built to reduce undertriggering on tools may overtrigger on Claude Opus 4.5 and 4.6, that instructions such as "If in doubt, use [tool]" cause overtriggering, and that Claude Opus 5 verifies its own work well without being told, so verification instructions carried over from earlier prompts can cause over-verification. Each statement names a model; none is a claim about agents in general. What generalizes is the habit: when the model or its version changes, rerun your test log before assuming the old wording still fits. OpenAI's advice to keep production prompts in application code, with review, tests and normal deployment, is the team version of the same idea; for one person, it means one dated file for the instructions and the failure log beside it.

Tell it what to do when stuck

An agent with no stuck-procedure will do the worst possible thing: guess quietly and keep going. Every instruction set needs an explicit rule for uncertainty. The safest default is stop and ask, but that can be too cautious for long tasks, since an agent that asks about every minor ambiguity will need you babysitting it the whole way. A better pattern is a tiered rule: try one reasonable alternative, and if that fails, stop and report exactly where it got stuck and what it needs from you. This keeps the agent moving through minor hiccups while guaranteeing you hear about real problems.

• Never invent missing information. Mark unknowns clearly instead of filling them in.
• If a tool call fails twice, stop and report the error rather than trying a third variation.
• When a choice affects cost, timing, or other people, ask instead of deciding.
• End every task with a short summary of what was done and what was skipped.

The stuck rule deserves special attention on tasks that run longer than a few minutes, because stuck compounds. A confused agent does not sit still: it retries, rephrases, and re-routes, each attempt consuming time and budget while the underlying problem stays unsolved. A clear stop-and-report rule converts an expensive spiral into a cheap notification. Write the rule to name the exact deliverable of stopping: not just stop, but stop and tell me the step number, what you tried, the error you got, and what you need from me to continue. That turns the interruption into something you can resolve from the report alone, without reconstructing the run.

Keep instructions short enough to be followed

Long instruction documents get skimmed by agents as well as people. If your instructions run past a page, the agent will start dropping constraints halfway through a long task. Split the difference: keep a short core instruction set of the five to ten rules that always apply, and add task-specific details per job. Review your core set every month or so. Every rule should have earned its place by preventing a real mistake; rules that never matter are noise that drowns out the ones that do.

Order matters within the short set, too. Constraints first, then the goal, then the steps, then the format, then the stuck rule, then the done rule. This ordering mirrors how the agent uses the information: it needs to know its boundaries before it starts planning, and it needs the format before it starts producing. Instructions that bury never send email in paragraph six are instructions that are harder to follow on step twelve of a long task, where the rule sits far from the step it governs. If a constraint is important enough to matter, it is important enough to be first.

Five instruction rewrites you can steal

The fastest way to learn this skill is to see vague instructions rewritten precisely. Each pair below is a hypothetical example, invented to illustrate the technique, not taken from any real deployment. Steal the patterns, not the words.

Rewrite one: research. Before: Look into our competitors and tell me what you find. After: Produce a markdown table of our five closest competitors. Columns: company name, starting price, main feature, one weakness. Save it as competitors.md in the project folder. For each row, include the source URL you used. If you cannot verify a fact, write unverified instead of guessing. This rewrite converts an open-ended activity into a checkable artifact, adds sourcing requirements, and includes the never-invent rule that research tasks need most.

Rewrite two: email triage. Before: Go through my inbox and handle the routine stuff. After: Read today's inbox. For each automated message that needs a response: save a draft reply, and do not send anything. Flag messages that need my decision with the label needs-me. File newsletters and notifications into the Reading folder. Leave messages from people untouched; they are not part of this task. Stop and report after 25 messages. The rewrite defines the exact actions, states the critical constraint (drafts only), scopes the work (today's inbox, 25 messages), and specifies what to do with each category.

Rewrite three: code cleanup. Before: Clean up this codebase a bit. After: In the src/ folder only: remove unused imports, fix inconsistent indentation to two spaces, and rename variables that are single letters (except loop counters). Do not change any logic, do not add features, do not modify tests. After finishing, list every file you changed and what you changed in it. The rewrite bounds the blast radius (src/ only), enumerates exactly what clean up means, prohibits the dangerous interpretations, and requires a change log, which is the verification mechanism.

Rewrite four: scheduling. Before: Find a time for the team meeting next week. After: Find a one-hour slot next week (Monday to Friday) when all five people on the team list are free, between 10am and 4pm Eastern. Propose the three earliest options as calendar holds titled Team Sync (tentative). Do not send invitations. If no slot fits all five, report the best partial options and say who is missing from each. The rewrite removes every ambiguity: duration, window, timezone, who counts, what to do with the result, and the fallback when the ideal is impossible.

Rewrite five: summarization. Before: Summarize this report. After: Summarize the attached report in no more than ten bullet points. Each bullet must reference the section or page it comes from. Preserve every number, date, and named commitment exactly as written; do not round or paraphrase figures. End with one line stating anything important you were unsure about. The rewrite sets the length, demands traceability, protects the facts that matter most in summaries (numbers), and creates a channel for uncertainty instead of letting it become silent guessing.

Common instruction mistakes

Beyond vagueness, a handful of specific mistakes show up repeatedly in instructions that do not work. Watch for these in your own writing:

• Contradictory rules. Be thorough but keep it brief. Move fast but double-check everything. When instructions conflict, the agent picks one, and you do not get to choose which. Resolve every trade-off yourself: thorough within a 300-word limit, or brief except for the pricing section.
• Adjectives without calibration. Professional, detailed, concise, friendly: these shift meaning between people and are meaningless to an agent without an example. Either show an example or convert the adjective to a number: no more than 150 words, at least three options, exactly one page.
• Constraints buried at the bottom. The never-do rules belong first, not last. Where a rule sits relative to the step it governs matters on a long task, so state each never-do rule once near the top and again at the step where it applies.
• Changing five things at once. When an instruction fails, resist rewriting the whole thing. Change one element (add an example, tighten the format, clarify one constraint) and test again. Rewriting everything at once teaches you nothing about what was actually broken.
• Instructions written for the happy path only. Most instructions describe what to do when everything works and say nothing about errors, missing data, or ambiguous cases. But the happy path is where the agent needs you least. Spend half your instruction-writing effort on the stuck rule and the edge cases.
• Assuming shared context. The agent does not know that Q3 means the retail quarter, that the Johnson account is the sensitive one, or that drafts go to you before legal. Anything you have not written down does not exist for the agent. When in doubt, spell it out.

Test every instruction three times

An instruction is not done when it reads well; it is done when it works repeatedly. Run every new instruction set three times on low-stakes versions of the real task before trusting it with anything that matters. Three runs reveal what one cannot: the first run tests whether the instruction is understandable, the second tests whether the success was luck, and the third tests consistency. If all three produce correct output without your intervention, the instruction is ready. If any run needs a correction, the instruction, not the agent, is what needs editing.

Keep a simple test log: the date, the instruction version, what went right, what went wrong, and the one sentence you added or changed as a result. Over a few weeks this log becomes the most valuable document in your agent setup: a record of every way your particular agent misreads instructions, and the exact phrasing that fixed each one. The entries to look for are the repeats: each recurring misreading is a sentence worth adding to the core instruction set.

A reusable template

Use this structure as a starting point for any agent task, and adapt it as you learn where your agent needs more guidance:

• Goal: one sentence describing the finished result, written as a done-criteria check.
• Constraints: what it must never do, stated first, as prohibitions.
• Steps: the sequence to follow, numbered, with the stuck rule attached to each risky step.
• Format: exactly what the output should look like, with an example.
• Stuck rule: what to do when something is unclear or fails: try once, then stop and report with specifics.
• Done rule: how it should report completion and what to include in the summary.

Fill in this template for your three most repeated tasks and save the results where you can reuse them. The first one is the slowest; later ones go faster because the constraints and stuck rules barely change. That reusable library is the real payoff of learning to write instructions: not any single task done well, but every future task starting from a proven foundation.