How to Write Instructions Your AI Agents Actually Follow

Most disappointment with AI agents traces back to the same root cause: the instructions they were given were the kind a new hire would also have gotten wrong. Anthropic's own prompt engineering documentation, the guidance its engineers publish for building with Claude, is really a manual for writing instructions precisely enough that an agent can't misread them. None of it is secret or Claude-specific in spirit; it's the actual discipline of being clear enough that a smart but context-free reader gets it right the first time.

Why "Just Tell It What To Do" Doesn't Work

Anthropic frames the core problem directly: think of an AI model as "a brilliant but new employee who lacks context on your norms and workflows." A vague instruction like "create an analytics dashboard" leaves every meaningful decision, what to include, how much detail, what "done" looks like, up to the model's guess. The documented fix isn't more clever phrasing, it's more specificity: "Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation." Same task, but nothing left ambiguous.

The Golden Rule: Would a New Colleague Understand This?

Anthropic's own test for whether an instruction is clear enough: show it to a colleague who has minimal context on the task, and see if they could follow it without asking a clarifying question. If a human with no background would be confused by the instruction, the documentation states plainly that the model will be too. That reframes "the agent didn't do what I wanted" from a model failure into an instruction-quality check anyone can run themselves before ever touching a keyboard.

Give It Context, Not Just Commands

A flat rule like "never use ellipses" is a command with no reasoning attached, and it's brittle, because the model has nothing to generalize from if the situation shifts slightly. Anthropic's documented alternative adds the why: "Your response will be read aloud by a text-to-speech engine, so never use ellipses since the text-to-speech engine will not know how to pronounce them." The model is explicitly described as smart enough to generalize from an explained motivation in a way it can't from a bare rule, which matters for any instruction set that has to hold up across cases nobody explicitly listed.

Show, Don't Just Tell: Examples Beat Explanations

Anthropic's guidance calls worked examples "one of the most reliable ways to steer" output format, tone, and structure, more reliable than adding more descriptive language to the instructions themselves. The documented best practice is specific: 3 to 5 examples, each one relevant to the actual use case, diverse enough to cover edge cases without the model picking up an unintended pattern from too-similar examples, and clearly separated from the surrounding instructions (Anthropic's own docs use XML tags like <example> for this). A single well-chosen example of the output you want frequently does more work than another paragraph describing it in the abstract.

Structure Long or Mixed-Content Instructions

Once an instruction set mixes background information, the actual task, and reference material in one block, Anthropic's documentation recommends explicitly tagging each type of content, wrapping instructions, context, and input separately, so the model isn't left guessing which sentence is a rule and which is background color. This matters most exactly where teams are most tempted to skip it: long or complicated instruction sets, where an unstructured wall of text is precisely where a model is most likely to misweight one part against another.

What This Means for Teams Building Their Own Agent Workflows

None of this requires touching a model's settings, and none of it is Claude-specific in spirit, it applies to instructions for any AI agent a business puts to work. The pattern across Anthropic's own guidance is consistent: specificity beats brevity, motivation beats bare rules, one good example beats three extra sentences of description, and structure beats a single dense paragraph once instructions get complicated. A team that runs its own agent instructions through that same "would a new colleague get this right" test before shipping them will fix more agent-behavior problems than any amount of re-running the same vague prompt and hoping for a different result.

Frequently Asked Questions

What's the single most useful test for whether an AI agent's instructions are clear enough? Anthropic's own documentation recommends showing the instruction to a colleague with minimal context on the task: if they'd be confused by what to do, the model will be too.

Does explaining "why" actually change how well an AI agent follows an instruction? Anthropic's guidance states the model can generalize from an explained motivation in situations a bare rule doesn't cover, and gives a documented example: explaining that text will be read by a text-to-speech engine (so avoid ellipses) works better than stating the rule alone.

How many examples should be included when trying to steer an AI agent's output? Anthropic's documentation recommends 3 to 5 examples that are relevant to the real use case and diverse enough to cover edge cases, clearly separated from the rest of the instructions.

When does structuring instructions with tags or sections actually matter? Most for longer or mixed-content instruction sets, per Anthropic's guidance, where background information, the task itself, and reference material risk blurring together without a clear separation.