← BACK TO INSIGHTS
AI ENGINEERING2026-07-10•8 min read

Standing Orders for Your Coding Agent: AGENTS.md Done Right

I run two coding agents side by side and kept re-typing the same corrections. So I read the standards, mined 2,500+ of my own prompts, and rebuilt my setup around one rule: put every instruction where it actually loads. Here is what the evidence says — and what I changed.


Standing Orders for Your Coding Agent: AGENTS.md Done Right


On a starship, a standing order is different from a log entry, which is different from a safety interlock. A standing order is always in effect — the crew acts on it every shift without being told. A log entry is reference material you pull up when a situation calls for it. And a safety interlock is not advice at all: the computer simply will not let you vent the wrong compartment, no matter what anyone types.


Modern coding agents have exactly these three registers, and most people pour everything into the first one. That is the single biggest reason agents ignore instructions. I learned this the slow way — by re-typing the same corrections across roughly 220 sessions of Claude Code and OpenCode on my own hardware — and then the fast way, by reading what the standards actually say.


The File Is Context, Not Configuration


Here is the fact that reframes everything. An agent's instructions file — CLAUDE.md for Claude Code, AGENTS.md for almost everyone else — is not configuration the way a .env file is. It is injected into the model's context as a message, and in Claude Code's case it arrives wrapped in a note that literally says it "may or may not be relevant" (see the official Claude Code memory docs). Adherence is therefore probabilistic. The file shapes behaviour; it does not guarantee it.


That one insight tells you where every rule belongs.


Five Places a Rule Can Live


Anthropic's own guidance and the OpenCode docs converge on the same decision table. There are five mechanisms, and putting a rule in the wrong one is the root cause of most non-adherence:


  • The instructions file (AGENTS.md / CLAUDE.md) — loaded in full on every request. For always-true facts: stack, directory layout, build and test commands, hard conventions.
  • Path-scoped rules — loaded only when the agent touches a matching file. For language- or folder-specific constraints.
  • Skills — a SKILL.md whose name and description are always visible, but whose body loads only when triggered. For multi-step workflows and reference material you need *sometimes*.
  • Subagents — a separate, isolated context window that returns only a summary. For large or parallel tasks.
  • Hooks — deterministic code that runs every time, no exceptions. For the safety interlocks: block a secret from leaving the machine, run the formatter after every edit.

    • The governing heuristic from Anthropic is clean: guidance relevant on more than 30% of turns belongs in the instructions file; a section that has quietly grown into a procedure belongs in a skill; and anything that must never fail is a hook, not a sentence. "Never commit the .env file" in AGENTS.md is a polite request. The same rule as a pre-commit hook is a guarantee.


    Rules That Actually Hold Up


    The research is unusually consistent on what makes an instructions file work. The through-line is ruthlessness.


  • Keep it short. The official target is under 200 lines; strong teams keep the root file under 60. Frontier models reliably follow only ~150–200 total instructions, and the agent's own system prompt already spends a chunk of that budget. Anthropic's warning is blunt: bloated files cause the agent to ignore your actual instructions.
  • Be concrete enough to verify. "Use 2-space indentation" beats "format properly". "API handlers live in src/api/handlers/" beats "keep files organized".
  • Give each rule a reason. The *why* is not filler — it is how the agent decides the edge cases your rule does not literally cover.
  • Add reactively, prune like code. Add a line the second time the agent makes a mistake, not in anticipation. Then prune quarterly and delete any rule you cannot tie to a recent, real failure.
  • Spend emphasis carefully. IMPORTANT and YOU MUST measurably improve adherence — but only if rare. Mark everything critical and you have marked nothing.

    • The Numbers Are Real


    This is not a matter of taste. In Vercel's Q1-2026 evaluations, a compressed 8 KB documentation index scored 100% on their framework API tests versus 53% with no docs at all. Augment Code's evals showed that a single *bad* AGENTS.md can drop task completeness by around 30%. And for skills, rewriting a vague description into a concrete one — stating what it does, when to use it, and the words a user would actually say — lifted triggering accuracy from roughly 30% to 95% in community measurements. A skill's description is the only thing the model sees when it decides whether to fire; it is the trigger, not documentation.


    The Interoperability Trap


    Here is the one that quietly bites people who, like me, run more than one agent. AGENTS.md is now an open standard, read natively by OpenCode, Codex, Cursor, Copilot, Zed and around twenty other tools. But as of mid-2026, Claude Code does not read AGENTS.md — it reads CLAUDE.md, and only that. A repository that ships only an AGENTS.md loads *zero* project instructions into Claude Code, with no error and no warning. Just quietly worse output.


    The fix is one line. Make AGENTS.md the real file and symlink CLAUDE.md to it (ln -s AGENTS.md CLAUDE.md), or point a stub CLAUDE.md at it with an @AGENTS.md import. One file to maintain, both agents obey, and you are aligned with where the ecosystem is heading.


    What I Actually Changed


    I did not stop at theory. I mined every prompt I had ever sent both agents and let the corrections I kept repeating tell me what to fix.


  • One source of truth. I collapsed my scattered rules into a single file under 150 lines and symlinked it so Claude Code and OpenCode read the same thing. It covers the handful of things I was forever re-explaining: which machine the agent is actually running on, my brand rules, how to route inference to my local models, and where secrets and client data may never go.
  • I moved the guarantees into hooks. Blocking secrets from ever leaving the machine, and normalizing German output, are things that must never fail — so they are no longer sentences in a file, they are code.
  • I packaged the repeats as skills. My most-repeated workflows — building a branded deck from a report, running a visual-QA pass, health-checking my local tool servers — became skills with concrete, slightly pushy descriptions. And I fixed one stale description that contradicted a correction I had already made months ago.

    • Every line in that file traces to a mistake I corrected more than once. That is the real test. If you cannot point to the failure a rule prevents, it is not earning its place in the context window — and the context window is the one budget you cannot buy more of.


    Conclusion


    The best instructions file is not the most complete one. It is the shortest one that still puts every rule where it loads: always-true facts in AGENTS.md, procedures in skills, and the things that must never fail in hooks. Configure it once, with discipline, and you stop correcting the same mistake for the hundredth time. Standing orders, log entries, and safety interlocks — tell them apart, and the crew runs itself.


    If you would like help auditing your own agent setup, that is exactly the kind of work I do at AI & SAP Consulting Paul Oesterwitz.


    Paul Oesterwitz

    Paul Oesterwitz

    AI & SAP Consultant · PhD Researcher

    More Insights

    AI ENGINEERING

    The Homelab Grand Prix: Racing 14 Quantized LLMs on Two DGX Sparks

    2026-07-26 • 7 min read

    AI ENGINEERING

    Soofi S: A Sovereign AI Model from Germany, and Why the Details Matter

    2026-07-14 • 10 min read