Instruction Files Are Code: Writing AGENTS.md Agents Actually Follow
A long AGENTS.md or CLAUDE.md gets skimmed by the agent the same way a long wiki gets skimmed by people. A checklist for structuring instruction files so agents follow them: a short root map, rules that load only for the paths they govern, skills for procedures, one set of files for Claude Code and Codex, and every rule that code can decide moved into a check.
A team's CLAUDE.md started as twenty useful lines. Eight months later it is
nine hundred lines long. It has the build commands, the testing philosophy, a
paragraph about a migration from last spring, three rules about the billing
module, a style guide, and, somewhere around line 640, "never edit files under
gen/; they are regenerated." An agent edits a file under gen/. Someone
adds "IMPORTANT:" to the front of the rule. Two weeks later another agent
does it again.
The rule was there. The agent read the file. The problem is that a file everyone appends to and nobody designs behaves like any other unmaintained code: it grows, its parts contradict each other, and the important line is buried under the merely true ones.
We treat instruction files as code: they have a load path, a cost on every run, owners, reviews and tests. This is the checklist we use, in the order we would apply it to one overgrown file. It reflects how we organise our own repositories, and works the same for Claude Code and Codex.
How instruction files actually load
Before the checklist, the mechanism. "The agent reads the instructions" hides four different loading behaviours, and most structural mistakes come from treating them as one.
| Layer | When it is in context | Who supports it | What belongs there |
|---|---|---|---|
Root guide (AGENTS.md, CLAUDE.md) | Every turn of every session | Both: Codex reads AGENTS.md, Claude Code reads CLAUDE.md | Orientation: what this is, where things live, how to build and test |
Nested guides (a module's own AGENTS.md) | When working in that directory | Both, with the nearest file taking precedence | The module's shortest working path |
Path-scoped rules (.claude/rules/*.md with paths:) | When the agent works with files matching the globs | Claude Code natively; other agents need a resolver | Conventions for one area of the code |
Skills (SKILL.md) | When the task matches the description, or on explicit invocation | Both, through the Agent Skills format | Procedures: how to do a multi-step task |
| Hooks and checks | Never; they run outside the model | Each agent's hook system, plus CI | Anything that must always happen or never happen |
The column that matters is the first. Everything in the root guide is paid for on every turn, competes with every other line for attention, and is read whether or not it is relevant. Everything lower down is paid for only when it applies. The craft is moving each instruction to the lowest layer that still loads when it is needed.
Why the obvious fixes fail
When an agent ignores a rule, teams reach for two fixes. Both make things worse at scale.
Adding emphasis. "IMPORTANT," "YOU MUST," capital letters. This was common advice in 2025. Anthropic's current Claude Code best practices now say the opposite: adding IMPORTANT probably won't fix an ignored rule, current models follow a plainly worded line, and piling on emphasis mostly makes the model over-apply the rule. Applied to forty rules, emphasis also stops carrying information: when everything is important, nothing is.
Adding more text. Explaining the rule in more detail, adding examples, restating it in a second section. Each addition makes the file longer, and instruction following degrades as instructions pile up. The IFScale benchmark measured exactly that: as the number of simultaneous instructions grows into the hundreds, even frontier models follow a shrinking fraction of them; the best models it tested reached only 68% accuracy at 500 instructions. A nine-hundred-line file is a few hundred instructions, most of them irrelevant to the task at hand.
The fix is structural: fewer instructions in context at once, each one relevant, and the mechanical ones taken out of the model's hands entirely.
Stage one: a short root guide that is a map
OpenAI's harness engineering
write-up describes why one giant instruction file failed for them (it
crowded out the task, buried the key rules, went stale and could not be
verified) and the alternative that worked: an AGENTS.md of about 100 lines
that acts as a table of contents into deeper documentation in the
repository. We summarise it as "a map, not a manual."
Our root guides follow one skeleton.
- One paragraph: what this repository is, and the one goal that decides close calls.
- Choose a module: one line per module, linking its own guide.
- Develop locally: the four or five commands that install, run, test and check, each linking its procedure.
- Gotchas: the short list of things that surprise everyone once.
- Owner control: how the person driving the session overrides defaults.
- Autonomy: what the agent may do without asking, and what it may never do to make progress.
- Where policy lives: a table of "before you do X, read Y."
- Response style: two or three sentences.
The checklist for this stage:
- It fits on about two screens. Claude Code's
memory docs suggest keeping each
CLAUDE.mdunder 200 lines, because longer files consume more context and reduce adherence. If a section needs more than a paragraph, it is a document the guide links to. - Every line is true for every task. "When editing the billing module..." is not a root-guide line. It belongs to that module or a path rule.
- It routes, it does not explain. The "where policy lives" table is the most useful part: one row per kind of change, pointing at the governing document. The agent reads the row, then the document, and nothing else.
- Commands are exact.
make testnot "run the tests." Claude Code's best-practices page calls the command that runs your checks the single most useful line in the file. - Delete lines that would not prevent a mistake. For each line, ask what the agent would get wrong without it. If the answer is "nothing," cut it.
Stage two: rules that load only when relevant
Most of a typical overgrown file is area conventions: how the database layer works, what the UI components must do, what CI files may contain. They matter enormously when touching that area and not at all otherwise.
Claude Code's memory documentation
supports exactly this: markdown files in .claude/rules/ with a paths:
list of globs in their frontmatter load only when the agent works with
matching files. A rule file without paths: applies everywhere, which is a
reason to give almost every rule one.
| Field | Value |
|---|---|
paths | **/migrations/**, **/*.sql, internal/store/**, the CI workflow that runs database tests |
| Kind | Judgment rule; the mechanical parts are enforced by checks listed at the end |
| Opening line | Applies to code that persists data or tests against a database, and to the migrations and pipelines that serve it |
The checklist for this stage:
- One file per area, named for the area.
databases.md,ci.md,desktop-ui.md. A reader should guess the filename from the change they are making. - Globs include the config that governs the area, not just its source. The CI rule should load when someone edits a Makefile or a test runner config, not only workflow files.
- The first line says what the rule covers. Agents and people both decide in one sentence whether they are in the right file.
- Agents that do not load rules natively get a resolver. Codex reads
AGENTS.mdbut not.claude/rules/. We keep a small script that takes the paths about to be edited and prints the rules that apply, and the Codex guide tells the agent to run it before planning. One set of rules, two loading paths.
Stage three: skills for procedures
A rule says what must be true. A procedure says how to do something: open a pull request, write tests for a module, run an end-to-end check, onboard a new service. Procedures are long, ordered and only needed when doing that task, which makes them a poor fit for any always-loaded file.
They belong in skills. A skill is a folder with a SKILL.md whose
frontmatter description is what the agent matches against; the body loads
only when the skill is used, and reference files inside the folder load only
when the body points at them. This is
progressive disclosure: a
one-line description costs almost nothing until it is needed.
- The description is the routing logic. Write it as "Use when..." with the concrete triggers, because that sentence is all the agent sees when deciding whether to load the skill.
- The root guide points at skills by task. "Open or update a pull request: read create-pr." The agent should never have to search for the procedure.
- Procedures link rules, they do not copy them. A skill that restates the testing rule will drift from it within a month.
Stage four: one set of files for every agent
Teams using several agents often grow parallel trees (CLAUDE.md,
AGENTS.md, .cursorrules), each slowly wrong. Keep one source, with
links.
| Concern | What we do | Why |
|---|---|---|
| Root guide | AGENTS.md is the file; CLAUDE.md is a symlink to it | One text, two names. AGENTS.md is the cross-agent format; CLAUDE.md is Claude Code's primary file (an @AGENTS.md import works too) |
| Module guides | AGENTS.md in each module directory | Both agents pick up the nearest one |
| Skills | Live in .claude/skills/; .agents/skills is a symlink to that folder | Codex reads skills from .agents/skills; both build on the same open SKILL.md format |
| Path rules | .claude/rules/, plus a resolver script for Codex | Claude Code loads them by path; Codex is told to resolve them |
| Personal preferences | Untracked CLAUDE.local.md or local settings | Never in a tracked file that everyone's agent loads |
| Agent-specific differences | One short guide per agent ("only what differs") | Keeps the shared files free of "if you are Codex..." branches |
A symlink is a promise that the files cannot drift. A copy, however carefully synced, is two files. The first time someone edits one and not the other, the agents start disagreeing about the rules, and nothing tells you.
Stage five: write each rule so it can be checked
This is where the code analogy pays off most. A rule is a statement an agent or a reviewer must be able to evaluate against a diff, with a yes or no answer. Vague rules cannot be followed or enforced, because nobody can tell whether they were.
| Weak rule | Checkable rule, with its reason |
|---|---|
| Write good tests | Every behaviour test uses a named table of inputs and expected outputs, so a reviewer can see which cases exist and which are missing |
| Be careful with the database | Migrations are append-only; never edit a migration that has merged, because other environments have already applied it |
| Keep the UI consistent | Use the design-system components; never set a colour or spacing value directly, because themes change them centrally |
| Don't leak secrets | Error messages never include file paths, tokens or request bodies, because they reach end users and logs |
| Avoid magic numbers | (Not a rule for prose at all: make it a lint check) |
The checklist for each rule:
- A statement, not an aspiration. "Never," "always," "every," with a scope.
- A reason, in one clause. The reason lets the agent handle the case the rule did not anticipate, and lets a future maintainer tell when the rule has outlived its purpose.
- Labelled by kind. Each rule file says whether it is a judgment rule (needs a reviewer) or lists the checks that enforce its mechanical parts. Our rule about rule files says it directly:
A requirement code can decide belongs in a deterministic check, not in rule text. Rule files hold judgment only. A change that adds a rule says which kind it is.
- No history. "We used to do X" is a decision record. Link it.
Stage six: owner instructions that persist
The person driving a session will sometimes override the defaults: "no tests until I say," "stop the end-to-end loop," "don't push yet." Agents are bad at holding these. The instruction is in one message, the session compacts its context an hour later, and the next subagent never hears it.
So the root guide states the precedence explicitly, and a small skill makes it mechanical:
- The owner's in-session instruction wins over the guide, rule-file workflow steps and skill procedures, for the rest of the session.
- It survives compaction. The agent restates active instructions as a short list whenever it summarises its context.
- It reaches every subagent. Each subagent brief restates the active instructions, because a subagent loads the repository guides fresh and would otherwise reopen a step the owner stopped.
- It does not turn off the gates. An owner can stop the agent running tests locally. CI and the merge checks still run. That line is what makes it safe to give owners the override at all.
Stage seven: side effects never start themselves
Most skills are safe to load whenever they look relevant. Some act on the world: claim tickets, post to a tracker, merge, deploy, message someone. Those must never start because a description matched a conversation.
Claude Code supports this directly. A skill with
disable-model-invocation: true in its frontmatter can only be started by a
person invoking it, never by the model deciding to
(skills documentation).
- Mark every skill with external side effects. Claiming work, posting, merging, deploying, sending.
- State the boundary in the root guide too: skills do not authorise external messages, deployments or changes to another repository on their own.
- Review the list when adding a skill. "Can this change anything outside the working tree?" is a one-question review that catches most cases.
Stage eight: move every rule that code can decide into a check
This is the stage that shrinks the files the most, and the one that most improves compliance. If a rule can be decided by reading the code (an import boundary, a naming convention, a banned call, a required test layout, a file that must not change) then a program should decide it, not a model.
There are three destinations:
- A static check (linter, Semgrep rule, a test that inspects the codebase, a script in CI) for anything visible in the code. The check runs every time, costs no tokens, and its error message can tell the agent exactly how to fix the violation.
- A hook for actions that must never happen. Claude Code's
hooks can run a command before a
tool call and block it. We use a
PreToolUsehook to refuse merges that do not meet the merge conditions, however the merge command is phrased. An instruction says "please don't"; a hook says "can't." - A judgment rule for everything else, checked by a reviewer agent and, where it matters, a person.
We keep an index of which checks enforce which rule sections, so a rule section with no check is visibly a judgment rule.
The taxonomy: where each instruction belongs
| The instruction is... | It belongs in | Loaded | Example |
|---|---|---|---|
| True for every task | Root guide | Always | "Format with make fmt, not a bare formatter" |
| True for one module | That module's AGENTS.md | In that directory | "This service's tests need the local database running" |
| True for some file types or areas | Path-scoped rule | On matching paths | "Migrations are append-only" |
| A multi-step procedure | Skill | When the task matches | "How to open a pull request" |
| Decidable from the code | Lint, Semgrep, test, CI script | Never; it runs | "No package may import the gateway internals" |
| An action that must never run | Hook | Never; it blocks | "No merge without a recorded review of this exact commit" |
| A personal preference | Untracked local file | Only for that person | "I prefer terse summaries" |
| History or rationale | Decision record, linked | When someone follows the link | "Why we moved off the old queue" |
A worked example
Here is what happens when the nine-hundred-line file from the opening goes through the checklist.
| Before | After | Why |
|---|---|---|
One 900-line CLAUDE.md | Root AGENTS.md of about 120 lines, CLAUDE.md symlinked to it | Always-loaded text cut to orientation and routing |
| Billing, database, UI and CI conventions inline | Four path-scoped rule files | Each loads only when its files are touched |
| "How to release" section, 80 lines | A release skill marked disable-model-invocation: true | Procedure loads on demand, and cannot start itself |
"Never edit files under gen/" at line 640 | A CI check that fails if generated files differ from the generator's output, plus a hook that refuses writes there | The rule that kept being broken now cannot be |
| "Avoid magic numbers," "no unused exports" | Lint rules | Mechanical rules out of prose entirely |
| Migration history paragraph | Decision record, linked from the database rule | History stops costing every session |
| "IMPORTANT" on eleven rules | No emphasis; the remaining rules each state a reason | Emphasis was compensating for length |
Separate .cursorrules and CLAUDE.md with different test commands | One root file; a short per-agent guide for differences | The agents agree because there is one source |
The fixes compose. The gen/ rule stopped being broken because it left the
file: CI catches it, the hook stops the write, and the shorter guide means
the remaining rules get read.
How to test instruction files
If they are code, they should have tests. Three cheap ones:
- A size budget in CI. Fail if the root guide grows past a line limit
you choose. Codex enforces a ceiling of its own: it stops adding project
instruction files once they reach
project_doc_max_bytes, 32 KiB by default (Codex docs). Anything past that is not loaded. - Link and path checks. Every link in a guide resolves; every
paths:glob matches at least one file. A rule whose globs match nothing has silently stopped applying. - A fresh-session probe. Start a new session, give it a realistic task ("add a column to the orders table"), and check which files it read before acting. If it never opened the database rule, the routing failed.
Over time, track violations per rule found in review. A rule reviewers keep flagging is unclear, in the wrong layer, or a candidate for a check.
What this does not fix
Structure makes the right instruction present at the right time. It does not make the agent obey it. Judgment rules will still be broken sometimes, which is why they need a reviewer and the important ones need a check.
Path-scoped loading depends on the agent touching the files. A change that should have edited a migration but did not will never load the migration rule. The routing table in the root guide is the backstop, and it is only as good as its rows.
And the symlink approach covers the agents that follow the shared formats. A tool with its own proprietary instruction file still needs a copy, and a copy can drift.
What it costs
A structured tree is more files and links to maintain. Every check that replaces a rule is code someone owns, and some are harder to write than the rule was to state. Resolver scripts are one more tool to keep working. You are swapping a file anyone can append to for a system someone has to design.
The checklist
- Root
AGENTS.mdfits on about two screens and is a map, not a manual - Every root-guide line is true for every task; the rest moved down
- Build, test and check commands are exact and copyable
- A "before you do X, read Y" table routes each kind of change
- Each module has its own short
AGENTS.mdwith its working path - Area conventions live in path-scoped rule files with accurate
paths: - Agents that do not load rules natively have a resolver and are told to run it
- Procedures live in skills whose descriptions say "use when..."
-
CLAUDE.mdis a symlink toAGENTS.md;.agents/skillslinks to the same skills - Personal preferences are in untracked local files only
- Every rule is a checkable statement with a one-clause reason
- Every rule file says whether it is judgment or names the checks that enforce it
- History lives in decision records, linked, not inline
- Owner instructions win for the session, survive compaction and reach subagents
- Owner instructions never turn off CI or merge checks
- Every skill with external side effects has
disable-model-invocation: true - Every rule code can decide is a lint rule, Semgrep rule, test or script
- Actions that must never run are blocked by a hook, not asked nicely
- CI checks the root guide's size, every link, and every
paths:glob - Rule violations found in review are counted per rule, and acted on
An instruction file is the one piece of code every agent run executes. Write it like the hot path it is.
Written by CatalEx Engineering. We build the AI operating layer for AI-native companies: one platform to build, deploy, and run AI agents in production. More at catalex.co.