AGENTS.md: One Instructions File for Every Agent

Open three different coding agents in the same repository and, until recently, you'd write the same context three times. Claude Code wanted a CLAUDE.md. Cursor read .cursor/rules. OpenAI's Codex looked for its own file. Copy-paste drift set in within a week: one file mentioned a build command the others didn't, another had gone stale after a refactor.

AGENTS.md is the fix the ecosystem converged on. It's not an Anthropic format, an OpenAI format, or a Cursor format — it's an open, tool-agnostic markdown file that over 20 coding agents now read directly, including some that used to require their own proprietary file. This post walks through what actually goes in one, how the three biggest agents resolve it when multiple instruction files are present, and how to set up a single file that works everywhere instead of three that quietly disagree.

What AGENTS.md is for

The pitch, straight from the format's own site (agents.md), is that a README is written for humans skimming a repo for the first time, while an agent needs different things: exact build and test commands, where the conventions are enforced, what not to touch, and how to open a pull request. Mixing both into one README either bloats it for humans or under-serves the agent. AGENTS.md is the second file, scoped entirely to agent context.

It's plain markdown with no required schema — no YAML front matter, no fixed section names. Projects that have adopted it tend to converge on similar sections anyway, because they're the questions every agent needs answered:

• Project overview and where things live
• Build, test and lint commands (verbatim, runnable)
• Code style and naming conventions
• Testing instructions, including what "done" means
• Security or data-handling rules
• Commit message and pull request conventions
• Deployment steps, if the agent is trusted to run them

Because it's just markdown, you can put an AGENTS.md in a repo today and every agent that supports it will pick it up on the next run — no config file, no install step.

A minimal starter file

Here's a realistic starting point for a small web app, short enough to actually get read and followed:

# AGENTS.md

## Setup
npm install

## Build & test
npm run build
npm test -- --watch=false

## Style
- TypeScript strict mode; no `any` without a comment explaining why
- Components in `src/components`, one per file, named exports only
- Run `npm run lint -- --fix` before committing

## Commits & PRs
- Conventional commits (feat:, fix:, chore:)
- Every PR touching `src/api` needs a note on backward compatibility

## Do not touch
- `src/generated/` is codegen output, never hand-edit it
- Don't add new dependencies without asking first

Nothing here is exotic. That's the point — an agent that ignores half of a 400-line CLAUDE.md will usually follow a dozen lines like these, because there's nothing to skim past.

Nesting for monorepos

Both the format's own spec and the individual agents support placing more than one AGENTS.md in a repository. The rule, worded almost identically across implementations, is that the closest file to whatever the agent is editing wins, and instructions from parent directories are still combined in for anything the closer file doesn't override. So a monorepo might have a root AGENTS.md with company-wide conventions, and a packages/billing/AGENTS.md with billing-specific test commands and a note that anything touching money needs an extra reviewer. An agent editing a file in packages/billing reads both, with the nested one taking precedence on anything they disagree about. Explicit instructions you type into chat still override both, in every agent that documents this.

How Codex and Cursor read it

OpenAI's Codex was one of the formats' original backers, and treats AGENTS.md as its native instructions file — no import, no setting to flip. The {{tool:codex}} CLI installs with a one-line script (curl -fsSL https://chatgpt.com/codex/install.sh | sh on macOS/Linux, or npm install -g @openai/codex) and picks up an AGENTS.md in the working directory automatically from the first run.

{{tool:cursor}} supports it as an alternative to its own .cursor/rules files. Cursor's documentation is explicit that AGENTS.md is the simpler of the two — plain markdown with no front matter — while Project Rules add a .mdc extension and metadata for things like auto-attaching a rule to specific file globs. Cursor also honors nested AGENTS.md files the same way: "instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence." If a repository already has an AGENTS.md from working with Codex or another agent, Cursor reads it with nothing extra to configure.

Claude Code just added this — here's exactly how it decides

This is the part worth knowing if you last checked and it wasn't true yet: as of Claude Code v2.1.277, {{tool:claude-code}} reads AGENTS.md directly. Before that release, and in this directory's own listing for the app, the honest answer was "no — import it from CLAUDE.md." That's no longer the full picture, and the exact rule matters because it's not "reads both, always."

By default, Claude Code's Project instructions setting is claude-md-or-agents-md, which behaves like this:

In other words, adding a CLAUDE.local.md for your own uncommitted notes — a common habit — silently stops Claude from reading the team's AGENTS.md, because a local file still counts as "having a CLAUDE.md." If you want both files loaded together regardless, there's a setting for it. Either run /config in a session and set Project instructions to claude-md-and-agents-md, or set it in ~/.claude/settings.json:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

With that value, Claude Code loads each directory's CLAUDE.md first and its AGENTS.md after, and it's smart enough not to double-load an AGENTS.md that a CLAUDE.md already imports.

There are edge cases worth knowing before you rely on this. Native AGENTS.md reading needs v2.1.277 or newer, and it silently falls back to CLAUDE.md-only behavior — with no error — on Amazon Bedrock, with telemetry disabled, or in your very first session right after upgrading. In any of those, the old workaround still works: put @AGENTS.md at the top of a CLAUDE.md and Claude imports it explicitly. If you already have that import in place from before native support landed, leave it — Claude Code recognizes the file has already been loaded and doesn't double it up.

Three agents, three defaults

Put side by side, the default behavior of the three biggest agents in this directory looks like this for a repo that has both an AGENTS.md and a tool-specific file:

The practical difference is that Codex and Cursor treat "having a tool-specific file too" as additive or irrelevant, while Claude Code's default treats a CLAUDE.md as opting out of AGENTS.md entirely. If your team runs a mix of these three and wants everyone reading the same words, that middle row and bottom row are the two to get right — Codex needs nothing from you either way.

Why this beats one file per agent

Before AGENTS.md was widely read, teams using more than one coding agent had three options, none good: maintain duplicate instruction files and let them drift, pick one agent and force everyone onto it, or write instructions so generic they stopped being useful. A shared AGENTS.md means the build command, the "don't touch generated code" rule, and the PR checklist live in exactly one place, and whichever agent a teammate happens to be running that day reads the same thing.

It also travels with the repo in a way a personal tool config doesn't. A CLAUDE.md or .cursor/rules file commits fine too, but they only help teammates who use that specific tool. AGENTS.md helps whoever opens the repo next, regardless of which agent is in their terminal — including reviewers running an agent-based code review tool that never touches the interactive coding workflow at all.

Setting this up without breaking anyone's existing tool

If you're introducing AGENTS.md to a repo that already has tool-specific files, the low-risk order is:

1. Write the AGENTS.md first, covering only what's true regardless of which agent reads it (build, test, style, do-not-touch).
2. Leave existing CLAUDE.md or .cursor/rules files in place for anything genuinely tool-specific — a Claude Code hook reference or a Cursor rule glob doesn't belong in the shared file.
3. If you use Claude Code and want it reading both, set claude-md-and-agents-md as shown above rather than relying on the default, since the default silently prefers CLAUDE.md the moment one exists.
4. Commit AGENTS.md at the repo root, and add nested copies only where a subdirectory's rules genuinely differ — extra nesting just for organization adds files agents have to reconcile for no benefit.

None of this requires picking a single app for the whole team. That's arguably the actual point of the format: it lets a repo stay useful to whichever agent someone reaches for, whether that's a terminal tool, an IDE extension, or a cloud-run task, without anyone maintaining three versions of the same paragraph. For a broader map of what else is out there once your instructions file is sorted, the ecosystem page tracks the current landscape of apps, and the glossary is a fast way to look up terms like this one when they show up in someone else's docs.

The takeaway

If your repo has more than one contributor and more than one of them uses a different coding agent, write an AGENTS.md at the root today — it costs one markdown file and pays off the first time someone opens the project in a tool you didn't test against. If you're specifically on {{tool:claude-code}}, don't assume the default setting reads it: check whether you have a stray CLAUDE.local.md shadowing it, and if you want both files loaded on purpose, set Project instructions to claude-md-and-agents-md explicitly rather than hoping the default does what you want.