How to Write AI Agent Instructions That Actually Work (2026)
Most AI agent instructions fail not because the model is weak, but because the instructions are vague, bloated, or contradictory. I write agent instructions daily for Claude Code and the Anthropic API — here is the exact structure that works, with copy-paste templates you can use today.
❌ Why Most AI Agent Instructions Fail
Here is the pattern I see over and over: someone sets up an AI agent — Claude Code, OpenAI Codex, a custom agent built on the Anthropic API — pastes in three paragraphs of vague hopes ('be helpful, be accurate, write clean code'), and then wonders why the agent ignores half of it.
Agent instructions fail for three predictable reasons. First, they describe personality instead of behavior. 'Be thorough' means nothing to a model; 'run the test suite before reporting a task as done' is a behavior it can actually follow. Second, they bury the important rules. If your critical constraint is in paragraph nine of a wall of text, it competes with everything above it. Third, they contradict themselves — 'be concise' in one line and 'always explain your reasoning in detail' in another. The model doesn't error out on contradictions; it just picks one, and you never know which.
There is also a scale problem people underestimate. An agent is not a chatbot. A chatbot answers one message; an agent takes dozens of actions across many steps, and every ambiguity in your instructions compounds at each step. A slightly vague instruction that costs you nothing in a chat conversation can send a 50-step agent run completely off the rails by step 12.
The fix is not writing more. It is writing instructions the way you would write a runbook for a capable new hire on their first day: specific behaviors, clear priorities, explicit boundaries, and examples of what good output looks like.
The 'capable new hire' test
Before shipping any instruction, ask: would a smart contractor with no context about my project know exactly what to do after reading this? If they would have to guess your file structure, your definition of 'done,' or what they are allowed to touch, so will the agent. Models like Claude Opus 4.8 are strong reasoners, but they cannot read your mind — they can only read your instructions.
🏗️ The 5-Part Structure Every Agent Instruction Needs
After writing instructions for Claude Code projects, API-based agents, and MCP server integrations, I have converged on a five-part structure. Every effective agent instruction file I have seen — including Anthropic's own published system prompts — follows some version of it.
**1. Role and scope.** One or two sentences: what the agent is and what it is responsible for. 'You are a code review agent for a Python repository. You review pull requests for correctness and security; you do not merge or deploy.' The negative scope ('you do not...') matters as much as the positive.
**2. Environment and context.** What the agent needs to know that it cannot discover on its own: tech stack, folder conventions, which commands run tests, which APIs it has access to. In Claude Code, this is exactly what a CLAUDE.md file is for.
**3. Behavioral rules, in priority order.** Concrete, observable behaviors — not adjectives. Put the most important rules first, because position signals priority. Five rules the agent follows beat thirty it skims.
**4. Output format.** If you need JSON, show the exact schema. If you need a report, show the section headings. Agents are dramatically more consistent when you show the shape of a good answer instead of describing it.
**5. Boundaries and escalation.** What the agent must never do (delete data, push to main, contact external services) and what it should do when uncertain (stop and ask, versus make a documented assumption and continue).
Priority order is not decoration
Language models weight instruction position. Rules at the top of a prompt and rules repeated near the task both get followed more reliably than rules buried in the middle. If a rule is genuinely critical — 'never run destructive commands without confirmation' — put it first, state it plainly, and do not surround it with ten less important rules.
🎯 Show, Don't Tell: Examples Beat Adjectives Every Time
The single highest-leverage upgrade to any agent instruction is replacing adjectives with examples. This is the difference between 'write good commit messages' and showing one actual commit message in the exact format you want.
Compare these two instructions. Version A: 'Summaries should be concise and professional.' Version B: 'Summaries follow this format — one bold headline sentence stating the outcome, then 2-3 bullet points with specifics. Example: **Deploy succeeded after fixing the config typo.** • Root cause: staging URL had a trailing slash • Fixed in config/deploy.yml • All 42 tests passing.' Version B gets you consistent output on the first try; Version A gets you a different interpretation every run.
This works because models are pattern-completers at heart. A concrete example constrains the output space far more tightly than any pile of adjectives. One good example is worth roughly a paragraph of description; two or three examples covering different cases (a normal case, an edge case, a failure case) are worth a page.
The same principle applies to negative examples. If your agent keeps making a specific mistake — say, wrapping every answer in unnecessary preamble — show the bad version next to the good version and label them. 'Bad: Certainly! I'd be happy to help you with that. The answer is 42. Good: The answer is 42.' Agents correct faster from contrast pairs than from abstract prohibitions.
MINI-TEMPLATE — Contrast pair for fixing a recurring agent mistake: ## Output style Bad (do not do this): "Great question! Let me analyze the logs. After careful review, it appears that..." Good (do this): "The 502 errors started at 14:03 UTC, right after the config deploy. Rolling back fixes it." Rule: Lead with the finding. No preamble, no restating the question.
📂 Where Instructions Live: CLAUDE.md, System Prompts, and MCP
Knowing how to write instructions is half the job. The other half is putting them in the right place, because different layers have different persistence and different authority.
If you use **Claude Code** (currently running Claude Sonnet 4.6 and Opus 4.8), the primary home for project instructions is the **CLAUDE.md** file in your repository root. It loads automatically at the start of every session, which makes it the right place for durable facts: build commands, test commands, code conventions, directory structure, and 'never touch' zones. Keep it under a few hundred lines — it is context the agent carries everywhere, so every line should earn its place.
If you build agents on the **Anthropic API** directly, instructions go in the **system prompt** parameter, separate from user messages. The system prompt is the highest-authority layer: role, rules, and boundaries belong there, while the task itself arrives as a user message. OpenAI's Codex CLI follows the same pattern with an AGENTS.md file — the convention of 'a markdown file the agent reads first' has effectively become an industry standard.
**MCP servers** (Model Context Protocol) add a third layer: tool descriptions. When you connect an agent to external tools — a database, a browser, ElevenLabs for voice generation, an image pipeline using gpt-image-2 — each tool's description is itself an instruction. A vague tool description ('queries the database') produces vague tool use; a precise one ('read-only SQL queries against the analytics replica; never use for writes') produces precise tool use. Most people polish their system prompt and completely forget that tool descriptions are prompts too.
The layering rule
A simple rule for deciding where an instruction goes: durable project facts go in CLAUDE.md or the system prompt, task-specific detail goes in the individual request, and tool usage rules go in the tool description itself. When the same instruction appears in multiple layers, keep it in the highest one and delete the duplicates — duplication is how contradictions are born, because you will update one copy and forget the other.
| Layer | Tool / Example | Best for | Persistence |
|---|---|---|---|
| Project file | CLAUDE.md (Claude Code), AGENTS.md (OpenAI Codex) | Build commands, conventions, repo rules | Every session, automatic |
| System prompt | Anthropic API `system` parameter | Role, priorities, hard boundaries | Every request you send |
| Task message | The individual prompt/request | This task's goal and acceptance criteria | One task only |
| Tool description | MCP server tool definitions | When and how to use each tool | Whenever the tool is available |
📋 A Real Template You Can Copy Today
Here is the skeleton I actually use when setting up a new agent, whether it is a Claude Code project or an API-based agent. It is deliberately short — the goal is a starting point you fill in over one week of real use, not a 2,000-word document you write on day one and never test.
Start with this template, run the agent on real tasks for a few days, and add a rule only when the agent actually gets something wrong. Instructions written in response to observed failures are almost always better than rules invented in advance, because they target real behavior instead of imagined problems.
One note on the 'Definition of done' section: this is the part most people skip and most agents need. Without it, an agent decides for itself when a task is finished — usually too early. 'Done means: code compiles, tests pass, and you have stated which files you changed' turns a fuzzy judgment call into a checklist the agent can verify.
# Agent Instructions — [Project Name] ## Role You are a [role] for [project]. You handle [scope]. You do NOT [out of scope]. ## Environment - Stack: [languages, frameworks, versions] - Run tests: `[command]` - Build: `[command]` - Key directories: [src/ = app code, tests/ = tests, docs/ = never edit] ## Rules (in priority order) 1. [Most critical rule — usually a safety boundary] 2. Always run tests before declaring a task complete. 3. Ask before [irreversible action]; proceed without asking for [reversible actions]. 4. [Project-specific convention] ## Output format [Show one concrete example of a good response/report/commit message] ## Definition of done A task is complete only when: [ ] code runs, [ ] tests pass, [ ] changes are summarized with file paths. ## When uncertain If requirements are ambiguous: [state your assumption and continue / stop and ask].
🔧 Debugging Instructions: What to Do When the Agent Ignores You
You wrote careful instructions and the agent still did the wrong thing. Before rewriting everything, diagnose. In my experience the failure is almost always one of four things, and each has a different fix.
**Contradiction.** Two rules conflict and the agent picked the one you didn't want. Search your instructions for pairs like 'be brief' vs 'explain everything,' or 'always ask first' vs 'work autonomously.' Fix: resolve the conflict explicitly — 'be brief in summaries, detailed in error reports.'
**Burial.** The rule exists but sits in the middle of a long document surrounded by lower-priority text. Fix: move it to the top of its section, or into a short 'Critical rules' block near the start. If it is genuinely important, it should be findable in three seconds by a human skimming the file — that is a decent proxy for model attention too.
**Vagueness.** The rule describes a quality, not a behavior. 'Be careful with the database' gives the agent nothing to check itself against. Fix: convert to an observable behavior — 'run SELECT queries freely; never run UPDATE, DELETE, or DROP without showing me the statement first.'
**Staleness.** The instruction was right six months ago and the project changed. Your CLAUDE.md says tests live in test/ but you moved them to tests/unit/. The agent follows the map you gave it, straight into a wall. Fix: treat instruction files like code — review them when the project changes, and delete rules that no longer apply. A wrong instruction is worse than no instruction, because the agent trusts it.
The one-change rule
When iterating, change one thing at a time and re-run the same task. If you rewrite five rules at once and behavior improves, you have learned nothing about which rule mattered — and you may have added a new contradiction. Treat instruction tuning like debugging: isolate the variable.
✅ Pre-Flight Checklist Before You Ship Your Instructions
Before you hand your instructions to an agent and walk away, run through this checklist. It takes five minutes and catches the failure modes that otherwise cost you an afternoon of confusing agent behavior.
Every item maps to a failure mode covered above: vague adjectives, buried priorities, missing boundaries, no definition of done, and untested assumptions. If you can honestly check all ten boxes, your instructions are better than the vast majority of agent setups running today.
The last item is the one people resist: actually running a test task. Instructions are code that executes on a language model, and like all code, they do not work until proven. Give the agent one small, low-stakes real task before you trust it with a big one — the ten minutes you spend watching that first run will teach you more than another hour of writing.
- ✔Role stated in 1-2 sentences, including what the agent does NOT do
- ✔Every rule describes an observable behavior, not a personality trait
- ✔Most critical rule appears first, not buried mid-document
- ✔At least one concrete example of good output (and ideally one bad example for contrast)
- ✔Output format shown, not described
- ✔Hard boundaries listed explicitly (files, commands, actions that are off-limits)
- ✔Definition of done is checkable, not a judgment call
- ✔Uncertainty behavior defined: ask first, or assume-and-document
- ✔No two rules contradict each other (read the whole file in one sitting to check)
- ✔Tested on at least one real, low-stakes task before high-stakes use
❓ Frequently Asked Questions
What is the difference between a prompt and agent instructions?
A prompt is typically a one-shot request for a single answer. Agent instructions are persistent rules that govern many actions across a long-running task — they cover tool use, boundaries, output formats, and what to do when uncertain. Think of a prompt as a question and agent instructions as an employee handbook: the handbook has to hold up across hundreds of decisions, not just one.
How long should AI agent instructions be?
As short as possible while still being unambiguous — for most projects that means one to a few hundred lines, not thousands. Long instruction files dilute attention: every low-value line competes with your critical rules. Start with the 5-part skeleton (role, environment, rules, output format, boundaries) and add rules only in response to observed mistakes.
What is a CLAUDE.md file and do I need one?
CLAUDE.md is a markdown file in your repository root that Claude Code reads automatically at the start of every session. It is the standard place for durable project instructions: build and test commands, code conventions, and off-limits areas. If you use Claude Code on any real project, yes — even a 20-line CLAUDE.md noticeably improves consistency. OpenAI's Codex CLI uses the same concept under the name AGENTS.md.
Why does my AI agent ignore my instructions?
Usually one of four reasons: the rule contradicts another rule, it is buried in the middle of a long document, it describes a vague quality ('be careful') instead of a checkable behavior, or it is outdated and conflicts with what the agent observes in the actual project. Diagnose which one applies before rewriting — moving one critical rule to the top of the file often fixes more than a full rewrite.
Do agent instructions work the same across Claude, ChatGPT, and other models?
The principles transfer almost entirely: concrete behaviors over adjectives, examples over descriptions, priority ordering, and explicit boundaries work on Claude Opus 4.8, OpenAI's models, and Gemini alike. What differs is the mechanism — CLAUDE.md for Claude Code, AGENTS.md for Codex, system parameters in each API. Write your instructions once in the 5-part structure and porting them between tools is mostly a copy-paste job.
🏁 Final Thoughts
Three things to remember. First, agents fail on vague instructions, not weak models — 'run the tests before saying done' will always beat 'be thorough.' Second, structure wins: role, environment, prioritized rules, an example of good output, and hard boundaries cover almost everything an agent needs. Third, instructions are code — they need testing, debugging, and maintenance, and a stale rule is worse than no rule. Your next action: copy the template from this post into a CLAUDE.md (or AGENTS.md, or your system prompt), fill in the five sections for one real project, and give your agent one small task today. Watch what it gets wrong, add one rule, repeat. If this guide saved you a debugging session, subscribe for more hands-on agent guides — and drop a comment with the weirdest way an agent has misread your instructions. I read every one.
Last updated: July 15, 2026 · Keyword: AI agent instructions · Agents at Work
Comments
Post a Comment