What an AGENTS.md file is, what to put in it, and whether it helps

An AGENTS.md file is a plain Markdown file at the root of a repository that tells coding agents how to work on it: the command that builds the app, the test that must pass, and the paths a wrong edit breaks. OpenAI Codex, Cursor and GitHub Copilot read it, and recent Claude Code versions read it when no CLAUDE.md exists.

What an AGENTS.md file is, and what it is for

AGENTS.md is a plain Markdown file, committed to the repository, that coding agents read as standing instructions. It carries what the code cannot show: the commands that build and test the app, the conventions to keep, and the paths where a plausible wrong edit costs money or leaks data.

The format exists because each tool grew its own instruction file, such as Claude Code’s CLAUDE.md and Cursor’s project rules, so a team on several tools kept near-duplicate guidance in several places. AGENTS.md is the shared layer: the format’s own site describes “a simple, open format for guiding coding agents”, with no required headings, now stewarded by the Agentic AI Foundation under the Linux Foundation. The site’s own line is “Think of AGENTS.md as a README for agents”, and it keeps the README for people: quick starts, project descriptions and contribution guidelines. The two overlap only on setup commands, and what a README should hold is a separate question.

The closest thing to an official specification is that site, and its demands are light: “AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.” GitHub’s documentation files AGENTS.md under agent instructions, and nothing in the specification requires more of the instructions file than plain text. So the purpose of an agent md file is narrow: it gives the agent the facts it cannot infer from the code. People type it as “agents md” or “agent md”, and the meaning is the same file, named AGENTS.md in capitals.

AGENTS.md, CLAUDE.md, README and Skills: which file does which job

Which of these one repository needs is decided tool by tool in AGENTS.md vs CLAUDE.md, tool by tool, including where Skills fit.

AGENTS.md examples: what goes in the file, section by section

AGENTS.md examples share one shape, because the format requires no headings. The format’s own site names the usual sections: a project overview, build and test commands, code style guidelines, testing instructions and security considerations. A fragile-areas list, naming each risky path and the test that guards it, is the section an agent can least work out alone.

Here is a complete file for one stack: a Next.js app with Supabase and Stripe on pnpm. It is our illustration, not a vendor template, and every command in it is a placeholder for the ones your repository actually runs.

# AGENTS.md

## Project

Booking app for small studios. Next.js front end, Supabase for auth
and data, Stripe for payments.

## Setup

- `pnpm install`
- Copy `.env.example` to `.env.local` and fill it from the team's
  password manager. Never commit `.env.local`.
- `pnpm dev` starts the app locally.

## Build and test

- Build: `pnpm build`
- Full test suite: `pnpm test`
- Types and lint: `pnpm typecheck && pnpm lint`

Run `pnpm test` and `pnpm typecheck` before you call a change done.
If a test fails, fix the code, not the test.

## Code style

- TypeScript everywhere. No `any`.
- Server code reads secrets from `process.env` only.
- Database access goes through `src/db/`, never a raw client in a route.

## Fragile areas

- Never edit `app/api/webhooks/stripe/route.ts` unless
  `pnpm test webhooks` passes afterwards. The test checks that the
  handler verifies the Stripe signature against the raw body.
- Never edit `supabase/migrations/*` without a test that signs in as a
  second account and confirms it cannot read the first account's rows.
- `src/lib/pricing.ts` is the only place prices are defined. Do not
  write an amount anywhere else.

## Security

- Read keys from `process.env`. Never paste a literal key into any
  committed file, this one included.
- Any new route that costs money to call needs rate limiting before
  it merges.

Two things make this file work. Every command can be run, so the agent can check its own work instead of guessing. Every fragile-area line names a path and a test, so the instruction was either followed or visibly not.

To use AGENTS.md in your own project, put the file at the repository root and change the four parts that differ by stack: the install command, the run command, the test command and the fragile paths. The format fixes no file structure for AGENTS.md; the headings above are one convention among many, and a five-line file is as valid as a long one. What you should put in your agent md file, beyond those four, is anything a new engineer would need to be told on day one because the code does not say it.

The fragile-areas list is the part no agent can work out alone. If agents already change an app with paying users and nobody on the team can name those paths, a free audit is where we go over them with you. In the Production Hardening Sprint, our engineers provide CLAUDE.md, AGENTS.md, Cursor rules or equivalents describing conventions and protected patterns, and add CI checks for the rules that can be enforced.

The same file in other stacks: Python, TypeScript, Java and .NET

There is no Python or Java version of the format. The file above is the shape in every stack, and only four things change: the install command, the run command, the test command and the paths a wrong edit breaks. The commands below come from each tool’s own docs; the fragile lines are our examples of what tends to be specific to each stack.

The format’s site also links example files from four real repositories: openai/codex, apache/airflow, temporalio/sdk-java and PlutoLang/Pluto. Reading one of them shows how short a working file can be.

Nested AGENTS.md in a monorepo: precedence and best practices

Nested AGENTS.md files scope instructions to a folder. The root file holds repository-wide rules, and a file inside a package adds that package’s commands and fragile paths. The format says the file closest to the edited code wins, and an instruction typed in the chat overrides every file.

The format’s site tells monorepos to place another AGENTS.md inside each package, and notes that the main OpenAI repository had 88 of them when the page was written. The layout, as text:

repo/
├── AGENTS.md                  (rules for the whole repository)
└── apps/
    └── billing-service/
        └── AGENTS.md          (billing rules; closest file, so it wins here)

For a monorepo, the best practices on structure are short: the root AGENTS.md keeps the sections from the examples above, and subdirectories add files with only the sections that differ. The root holds what is true everywhere: how to install, how to run the full test suite, how secrets are read, and the two or three paths anyone can break. A package file holds only that package’s test command and fragile paths. A rule that is true in one package does not belong at the root, where every agent working in every other package reads it.

OpenAI’s Codex docs on AGENTS.md show where AGENTS.md is read from before the repository: a global file in the Codex home directory (~/.codex by default), where an AGENTS.override.md is read in place of AGENTS.md if it exists. Codex then walks from the project root down to the working directory, taking at most one file per directory, and files closer to the working directory override earlier guidance because they come later in the combined prompt. The best global AGENTS.md is a short one, in our view, because a personal rule written months ago sits in the same context as the team’s.

Tool support for nested files differs, and the support table below has a column for it. Cursor applies nested files and combines them with their parent directories, while VS Code’s nested-file setting is off by default and marked experimental. Verify nesting in the tool and version your team runs before you rely on it. Cursor’s own .mdc rules use frontmatter to scope themselves instead, which is how Cursor scopes rules with globs.

AGENTS.md support: which coding tools read it, and what each needs

AGENTS.md support is wide but not uniform. OpenAI Codex, Cursor, GitHub Copilot, Cline and Lovable read the file, Gemini CLI and Aider read it once configured, and Claude Code by default reads it only when the project has no CLAUDE.md. Check the tool and version your team actually runs.

Sources for each row: Cursor’s rules docs, GitHub’s docs on repository instructions and GitHub’s support matrix, VS Code’s custom-instructions docs, Gemini CLI’s context-file docs, the format’s own FAQ for the Aider line (Aider’s conventions page shows the same read: setting for a conventions file), Cline’s rules docs and Lovable’s knowledge docs. Cline also keeps Cline’s own rules folder, and its Rules panel lists every detected file, AGENTS.md included, with a toggle for each.

The format’s home page names 23 tools as compatible, including several not in the table, such as Jules, Zed, Warp, JetBrains Junie and Windsurf. “Listed as compatible” is the format’s own claim about each tool, so confirm it in the version your team runs.

Using AGENTS.md with Claude Code: an import or a symlink

Anthropic’s Claude Code memory docs now say Claude Code “can read AGENTS.md as your project instructions” from v2.1.277, so a repository with no CLAUDE.md needs nothing extra. Claude Code does not follow AGENTS.md by default once a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working directory or above it: it then reads the CLAUDE.md files only. In that case the same page gives two ways for Claude to use AGENTS.md as the one shared file:

# Option 1: the first line of CLAUDE.md, with Claude-only rules below it
@AGENTS.md

# Option 2: a symlink, when there is nothing Claude-specific to add
ln -s AGENTS.md CLAUDE.md

The docs add a Windows caution: if anyone who clones the repository works on Windows, use the import instead, because a symlink there needs Administrator privileges or Developer Mode, and Git checks a committed symlink out as a plain text file unless core.symlinks is enabled. A third route is the Project instructions setting in /config: claude-md-and-agents-md has Claude Code read both files together. Our reading of the choice: with nothing Claude-specific to say and no Windows clones, symlink CLAUDE.md to AGENTS.md; with anything Claude-specific, use the import so the extra rules stay in one place. The full decision for each tool is whether to symlink or import, tool by tool.

Does AGENTS.md actually help? Evaluating AGENTS.md against three 2026 studies

AGENTS.md files change what coding agents do more reliably than whether they succeed. In a 2026 ETH Zurich study, developer-written files raised average success by 2.4 percent, a gain the authors’ own test did not find significant, while generated files raised cost by 20 percent or more.

The ETH Zurich study is the one behind the CTXbench name, and its behavioral finding matters most: agents followed the instructions in context files, which led to more exploration, testing and reasoning, and that is where the extra cost came from. Its authors found repository overviews unhelpful and advise that human-written files “should only include instructions required for coding agents that are not already present in the README (e.g., specific conventions or non-functional requirements)”. An ICSE workshop study of 124 pull requests measured runtime and output tokens and found task completion comparable, so it complicates the cost result without cancelling it, and a July 2026 preprint says its own sample was too small to rule out modest effects.

Whether AGENTS.md files are worth it, then, depends on what each line costs against what it prevents. As we read them, the studies give every line a price in attention and tokens, which is the best reason to cut folder tours and vague style advice and keep the rules a reader could check. The Hacker News thread on the ETH paper split the same way: one commenter called a 4 percent gain “massive” and “a must-have”, another called it “barely worth the token cost”. An instruction file is one of the engineering standards an AI-assisted team keeps, and on this evidence it earns its place through the specific rules it holds.

How long should an AGENTS.md be?

AGENTS.md has no length limit on the format’s own site, but two vendors set ceilings. OpenAI Codex stops loading instruction files once their combined size reaches 32 KiB by default, and Anthropic advises keeping CLAUDE.md under 200 lines because longer files reduce adherence. A file of checkable rules rarely needs to come close to either.

Codex sets the cap with project_doc_max_bytes, and its docs say it “stops adding files once the combined size reaches the limit”, with truncation fixed by raising the value or splitting large files across nested directories. The docs mention no warning, so a file past the cap can simply be missing from the agent’s context. Anthropic’s line target is written for CLAUDE.md, and our reading is that it fits any instruction file an agent loads in full: “Longer files consume more context and reduce adherence.”

How big an AGENTS.md should be is also a question of how many instructions a model can hold at once. The IFScale benchmark gave 20 models up to 500 instructions and found that “even the best frontier models only achieve 68% accuracy at the max density of 500 instructions”, with a bias toward earlier instructions. A rule near the bottom of a long file is the one most likely to be skipped.

So count the rules you would defend, not the lines. We’d aim for an agent md file under about 100 lines of real rules, and how long it runs beyond that matters less than whether each line can be checked.

AGENTS.md best practices: write rules an agent can be checked against

An AGENTS.md rule is worth keeping when someone can check afterwards whether the agent followed it. A line saying write clean code cannot be checked. A line saying run the webhook test before editing the Stripe webhook route can, because the test either passed or it did not.

Written as rules, the pair reads like this. “Write clean, maintainable code” leaves nothing to look at afterwards. “Never touch app/api/webhooks/stripe/route.ts without pnpm test webhooks passing” leaves a test run in the agent’s own tool output, which settles the question.

A rule that tells the agent to run the tests assumes there are tests. Of the 21 third-party apps we audited in June and July 2026, at least 18 had no working test anywhere: 17 had none at all, and a retail point-of-sale app’s checkout “test suite” never executed the actual checkout code.

Those 21 apps were chosen for audit, so the count describes a selected set, not a random sample of AI-built apps. Still, the order of work follows from it: write the test first, then the rule that names it, or the rule is decoration.

Here is a fragile-areas excerpt built that way, again as our illustration rather than a template:

## Fragile areas

- Never edit `app/api/chat/route.ts` unless `pnpm test abuse` passes:
  it checks that the paid model call rejects anonymous callers.
- Never edit `supabase/migrations/*` without `pnpm test rls`, which
  signs in as a second account and reads the first account's rows.

## Secrets

- Keys come from `process.env`. No literal key in any committed file.

What not to put in an AGENTS.md

Edit the file in the same change that moves a path or renames a test command, so the file and the code never drift apart.

Security lines, and an AGENTS.md you did not write

The format’s site lists security considerations as one of the usual sections, and the ordinary version is the one in the example above: where secrets come from, and which routes cost money when someone calls them.

The less obvious risk is an inherited file. An AGENTS.md is instructions running inside your agent, so a forked repository, a starter template or a vendored package can bring its own file, and a line in it can tell the agent to skip a test or push straight to the main branch. Read an inherited AGENTS.md before the agent does, as you would read a shell script before you run it.

How to check that an agent reads your AGENTS.md

An AGENTS.md is in force only when the agent can say what it contains. Before it edits anything, ask the agent to list the instructions it is working from; OpenAI Codex documents a one-line command that prints the guidance it loaded. If your rules are missing from the answer, none of them binds.

An AGENT.md file with the singular name is the first thing to rule out. The format’s site gives a one-line migration that renames it and leaves the old name as a link to the new one: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

1. 01 Before the agent edits anything, ask it to list the instructions it is working from, and compare the answer with your file.
2. 02 With Codex, run the summary command from its docs (shown below the list) and check that the answer quotes your rules; with Claude Code, run /memory and look for the AGENTS.md path in the list.
3. 03 Confirm that every path the file names still exists in the repository.
4. 04 In a branch, break one fragile-area rule on purpose and see whether anything stops the change.

The Codex command from its docs is codex --ask-for-approval never "Summarize the current instructions.". For one package in a monorepo, the same docs add --cd with that package’s folder and a prompt that asks which instruction files came in.

Step four is the one that matters, because a file is context and a CI check is a gate. In the same audits, at least 17 of the 21 third-party apps had no deploy gate: every push ships straight to production with nothing checking it first. The layers that enforce a rule, such as hooks, protected patterns and CI checks, are covered in guardrails that enforce a rules file. Even with both in place, a rules file and a CI check are no guarantee that an agent never breaks the app; they make a break more likely to show up before it ships.

In the sprint, deliverable 10.8, AI repository guardrails, is verified this way: we review the guidance and demonstrate CI catching a representative forbidden regression. The handover includes guidance and automated checks for future AI-assisted changes.

Common questions about AGENTS.md

Where should agent md be placed?

At the root of the repository, named AGENTS.md: the format’s own site says to create the file there. In a monorepo you can also place another AGENTS.md inside each package, and the file closest to the code being edited takes precedence.

Is agent md a standard?

Not in the formal sense: the format’s own site calls AGENTS.md “a simple, open format for guiding coding agents” and never calls it a standard. It is stewarded by the Agentic AI Foundation under the Linux Foundation, and the site says it is used by over 60k open-source projects.

How do I generate an agents.md file?

Run /init in the Codex CLI, which generates an AGENTS.md scaffold in the current directory; Claude Code’s /init writes a CLAUDE.md instead. Treat the result as a first draft: in the ETH Zurich study, LLM-generated context files raised cost and had no significant effect on success, so cut the draft down to commands, conventions and fragile paths.

When should a team get outside help with its AGENTS.md?

When agents already change an app with paying users and nobody can say which paths must not break, or when the same fix keeps coming undone after agent sessions. AxonBuild goes over those paths with you in a free audit, starting with the fix your agents keep undoing.