AGENTS.md Explained: Why Repositories Are Getting README Files for Coding Agents

A team scaffolds an AGENTS.md with /init, the agent improves for a week, and then the file quietly becomes a 14k-token policy document that nobody reads and that contradicts the CI config. The failure is not the file. The failure is the mental model: treating AGENTS.md as documentation to be written rather than as a context-loading mechanism with a scope, a precedence order, and a token budget.

That reframe is the whole article. AGENTS.md is a README for agents, which means it is commonly loaded into context, resolved by directory tree, and paid for on every task. Once you accept those three facts, most of the design questions answer themselves.

What AGENTS.md Actually Is at Runtime

AGENTS.md is plain Markdown. There are no required fields, no schema, no validator. The agent parses the text you provide, so any structure you see in the wild is a human convention rather than a contract. That flexibility is the point and also the trap: nothing stops you from writing a file that is technically valid and operationally useless.

Here is the boundary that matters. The format is portable; the runtime is not. AGENTS.md defines no universal parser, no universal discovery rule, and no universal precedence algorithm. What the format gives you is a predictable filename and a predictable location. What each coding agent does with that file — whether it loads it automatically, how it walks the directory tree, how it resolves conflicts, and how much of it enters the context window — is an implementation behavior that varies by harness.

The common pattern across compatible agents is this: the file is discovered by walking up the directory tree from the file being edited, applicable content is injected into context automatically, and more deeply nested files take precedence over shallower ones. That is the behavior most teams design around, and it is the behavior the rest of this article assumes. But treat it as the common implementation, not as a guarantee. Before you rely on automatic loading or conflict resolution, verify it against your specific harness — read its documentation, or run the precedence drill later in this article and watch what actually happens.

The single fact that drives every later decision is that the file is supplied to the agent rather than retrieved on demand. It is not summarized, not filtered by relevance, and not surfaced only when a query matches. If it sits in the directory tree above the file being edited, it is in the window. That is different from a design doc you can link and forget, and it is different from a retrieval index that only surfaces when a query matches.

Scope follows the directory tree rooted at the folder containing the file. A file in a home-directory config path, a repo root, and a subpackage can all apply to one edit. When instructions conflict, more deeply nested files win. Direct system, developer, and user instructions outrank AGENTS.md entirely, so the file is guidance, not law.

It complements README.md rather than replacing it. The README serves human onboarding: what the project is, how to install it, who maintains it. AGENTS.md carries the agent-specific operational detail that would clutter a human-facing document — exact commands, directory landmarks, conventions the code does not enforce.

The Scope and Precedence Model in Practice

The resolution rules are a design constraint, not trivia. They tell you to stop writing one giant root file and start writing layered ones.

Walk a monorepo trace. The root file sets company-wide conventions: package manager, commit format, the fact that all services live under services/. A file in services/billing/ sets that package's test runner and notes that the billing service uses a different migration tool than the rest of the repo. When the agent edits a file under services/billing/, both files apply, and the billing file wins wherever they disagree.

The most common structural mistake is inverting that layout. Teams put package-specific rules in the root file and generic conventions in leaf files. The result is a root file that grows with every new package and leaf files that duplicate what the root already says.

Conflicting instructions are not merged intelligently. Assume the closer file overrides. Never rely on a root rule to correct a nested one, because the nested file will win and your correction will silently disappear.

A global personal file is for your defaults, not your team's standards. If you keep a personal AGENTS.md with your preferred commit style, that preference applies to your sessions and not your colleagues'. Mixing personal defaults into the repo file makes agent behavior non-reproducible across contributors, which is exactly the property you were trying to fix.

A before-and-after layout makes the point concrete:

# Before: one root file doing everything
repo/
  AGENTS.md          # 400 lines, mentions billing, frontend, infra
  services/
    billing/
    frontend/

# After: layered by scope
repo/
  AGENTS.md          # 40 lines, repo-wide only
  services/
    billing/
      AGENTS.md      # billing test runner, migration tool
    frontend/
      AGENTS.md      # frontend build, storybook commands

The root file shrinks because it stops carrying rules that only apply to one subtree. The leaf files stay short because they only override what is genuinely local.

What Belongs in the File — and What Does Not

The inclusion test I use has two layers, because the first version of this rule was too blunt. The naive test — "if a tool enforces it, delete it" — is right about duplication and wrong about safety. Some constraints need to be enforced and explained.

Layer one: executable systems enforce. Formatters, linters, type checkers, CI jobs, sandbox configuration, approval policies, and data-access controls are the authority. They run whether or not the agent reads a sentence. Anything a tool already enforces should not be restated as a rule, because two sources of truth drift the moment someone changes the config and forgets the file.

Layer two: AGENTS.md explains the workflow constraint, points to the authoritative control, and states what the agent must verify. A production-data prohibition is enforced by sandbox and approval configuration — but the agent still benefits from knowing that this repository touches production data, that the control exists, and that it must confirm the sandbox is active before running a migration. The prose does not enforce anything. It tells the agent what to check and where the real gate lives.

Belongs:

• Repository layout and where things live, especially the non-obvious parts.
• Exact build, test, and lint commands, in code blocks.
• Conventions the code does not enforce — naming patterns, module boundaries, review expectations.
• PR and commit expectations.
• Explicit do-not rules: files not to touch, patterns not to introduce.
• A definition of done with a verification step.
• Pointers to the authoritative control for any safety-critical constraint, plus the verification the agent must perform.

Does not belong:

• Anything the toolchain already enforces, restated as prose. Keep the executable contract in the tool.
• Permission, approval, or data-handling policy as the only statement of the rule. If the constraint matters, it needs an enforcement mechanism, not just a sentence. The file can describe the constraint and point to the control; it cannot be the control.

Prefer exact commands over descriptions. "Run pnpm test" beats "make sure tests pass," because the first is checkable and the second is a vibe. The agent can run a command and read the exit code. It cannot run a sentiment.

Context Cost and the Growth Problem

Every line is paid for on every task. A long file competes with the actual code and the task context for the same window, which means a bloated AGENTS.md makes the agent worse at the thing you hired it to do.

The failure mode is accretion. Each incident adds a rule. Nothing is ever removed. The file becomes a policy landfill, and the rules that matter get diluted by the rules that were added in a panic and never revisited.

The counter-pattern is to keep the root file short and accurate, then point to task-specific markdown files for planning, review, or architecture. But be precise about what a pointer buys you. A reference is conditional navigation, not guaranteed lazy loading. Writing "see code_review.md" does not by itself keep that file out of context — the agent has to actually follow the pointer, and whether it does depends on the harness and the task.

So make the pointer explicit and observable. Reference the file and state when to load it:

## Review
- For code review tasks, read `docs/code_review.md` before reviewing.
- For architecture changes, read `docs/architecture.md` first.

Then watch the trace. After a review task, check whether the agent actually read docs/code_review.md and whether that content entered the context. If it did not load, the file cost you nothing — but neither did it help. If it loaded, you have confirmed the mechanism instead of assuming it. Do not treat a referenced document as free until you have seen it stay out of the window.

Add a rule only after you observe the same mistake twice. Guidance should be earned by real friction, not anticipated. If you cannot point to the incident that produced a rule, you probably do not need the rule.

One honest caveat: the effect of context files on task success is not settled. Research on repository-level context files reports that agents with context files run more tests, search more files, and use more repository-specific tooling. That is more exploration and verification, not uniformly higher solve rates. Treat the file as a way to steer behavior, not as a guaranteed performance upgrade.

A Minimal Working AGENTS.md

Here is a root file under 40 lines. Brevity is the design, not a compromise.

# AGENTS.md

## Layout
- `apps/` — deployable services
- `packages/` — shared libraries, no service-specific code
- `infra/` — Terraform, do not edit without review

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`

## Conventions
- TypeScript strict mode; no `any` without a comment explaining why
- Prefer named exports
- New shared code goes in `packages/`, not `apps/`

## Do not
- Do not modify `infra/` or `*.generated.ts`
- Do not add dependencies without checking `packages/` first

## Safety
- This repo touches production data. Migrations require the sandbox profile
  and an approved change. Confirm the sandbox is active before running any
  migration command.

## Done means
- `pnpm lint && pnpm typecheck && pnpm test` all pass
- Run these even for documentation-only changes

And one nested file that overrides only the test command:

# services/billing/AGENTS.md

## Commands
- Test: `pnpm test:billing` (not the root `pnpm test`)
- Migrations: `pnpm db:migrate:local`

The verification step is explicit and applies even to documentation edits. That is not pedantry. It closes the loop where an agent decides a change is too simple to check and ships a broken build.

The drill that proves the mechanism: add a deliberately wrong command to the root file, ask the agent to run tests, and watch which file's instruction it follows. Then move the rule into the nested file and repeat. You will see the precedence rule operate in front of you, and you will stop guessing about which file wins. Run this drill before you trust any of the runtime claims above on your own harness.

Common Mistakes and When Not to Use It

Generating the file with the agent and shipping it unedited is the most common mistake. The scaffold reflects generic advice, not how your team actually builds and reviews. Edit the result or you have outsourced your conventions to a default.

Encoding agent roles and multi-page prompt scaffolding in the file is the second. Role definitions burn context for consistency you would get from existing repo conventions. If your codebase already communicates how it is structured, a role block adds tokens without adding signal.

Using AGENTS.md as the enforcement mechanism for permissions is the third. That is configuration and sandbox policy. Prose is not a control, and a rule the agent can ignore is not a gate. The file can describe the constraint and point to the control; the control has to live somewhere that actually blocks the action.

When not to use it: a small, conventional repository where the toolchain and code already communicate the rules. Or a task where the needed context is task-specific and belongs in the prompt rather than in a durable file.

When to reach for something else: external systems and live data belong to tool or MCP configuration, and repeated stable workflows belong in a reusable skill rather than a longer instruction file.

Keeping It Alive

Treat repeated agent mistakes as the trigger for an edit. When the same error appears twice, ask for a retrospective and update the file. That keeps guidance tied to observed friction rather than to speculation.

Review the file when build, test, or review process changes. A stale command is worse than a missing one because it is confidently wrong. The agent will run it, fail, and burn a cycle discovering that your instructions lie.

Assign ownership. An unowned instruction file decays the same way an unowned runbook does: slowly, then all at once, until someone notices the agent has been following a rule that stopped being true six months ago.

Then close the loop with a small before/after check instead of a vague sense that things improved. Pick one recurring task — a billing test run, a review pass, a migration — and record what the agent actually did before your edit: which commands it ran, which tests it executed, which directories it touched, and which instructions it violated. Make one guidance change. Rerun a comparable task. Compare the same signals. If the agent now runs the right test and stops touching the wrong directory, the rule earned its place. If the behavior does not change, the rule is noise — remove it. This is how you separate a real improvement from random task variation, and it is how you catch over-guidance that makes the agent worse.

Do not measure whether the file looks comprehensive. Comprehensiveness is the failure mode, not the goal.

Write the shortest file that removes the friction you have actually observed. Keep executable contracts in the tools that enforce them. Keep permissions in configuration, and let the file point to them.

Your next action: open your current AGENTS.md, delete every line a formatter, linter, or CI job already enforces, and move any permission-shaped rule into config — leaving behind only the constraint description and the verification step the agent must perform. Then run the precedence drill once to confirm your harness behaves the way this article assumes. What is left is the file you actually needed.