AGENTS.md Explained: The Open Spec for AI Coding Agent Instructions

AGENTS.md is a plain markdown file, checked into the root of a repo, that gives AI coding agents the project context a README normally skips: build commands, test commands, code style, architecture notes, and anything else you'd tell a new hire before they touch the codebase. It's not owned by one vendor. The format is maintained by the Agentic AI Foundation under the Linux Foundation, and Codex, Cursor, Aider, opencode, Jules, Devin, Amp, Factory, and a long list of other agents read it natively. Claude Code joined them on September 18, 2026: from version 2.1.277 it falls back to AGENTS.md when a folder has no CLAUDE.md.

Why AGENTS.md exists

Every AI coding agent needs the same handful of facts about a project: how to install dependencies, how to run the test suite, which linter to respect, where the real architecture decisions live. Before AGENTS.md, that context ended up either buried in a README meant for human contributors, or duplicated across a pile of tool-specific files: .cursorrules for Cursor, .clinerules for Cline, .windsurfrules for Windsurf, a CLAUDE.md for Claude Code. Maintain a multi-agent team and you were maintaining the same instructions five times, with five chances for them to drift out of sync.

The project's own explanation for the split from README.md is direct: READMEs are for humans (quick starts, descriptions, contribution guidelines), while AGENTS.md holds the denser, agent-specific detail that would just clutter a README. Keeping them separate means a human skimming your repo isn't wading through test-runner flags, and an agent parsing AGENTS.md isn't guessing which parts of a human-oriented doc actually matter to it.

The format launched out of a shared need. OpenAI's Codex team, Amp, Google's Jules, Cursor, and Factory each converged on something close to the same idea independently, then coordinated on one name and format instead of shipping five incompatible ones. As of writing, the project's own site claims over 60,000 open-source repos use it, and OpenAI's own monorepo reportedly ships 88 separate AGENTS.md files across its subprojects.

What the format actually requires

Nothing. AGENTS.md has no required schema, no mandatory frontmatter, no fixed section list. It's Markdown, full stop. The project's own FAQ answers this directly: "Are there required fields? No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide."

That said, the sections that show up in most real-world files, and that the spec's own examples lean on, cover:

• Setup and dev environment. The exact commands to install dependencies and start a dev server, not "run npm install" in the abstract.
• Testing instructions. How to run the full suite, how to run a single test, and whether the agent should fix failures before finishing a task (most setups expect yes).
• Code style. Language version, formatting conventions, patterns to prefer or avoid.
• PR and commit conventions. Title formats, required checks before a commit is considered done.
• Security or architecture notes. Anything a careless agent could break without understanding why it exists.

For monorepos, the spec supports nested AGENTS.md files: drop one in each package, and agents that follow the convention read the nearest file in the directory tree and treat it as taking precedence over parent files further up. A change under packages/billing/ picks up packages/billing/AGENTS.md first, then falls back to whatever's defined higher up the tree. Conflicting instructions resolve the same way: the closest file wins, and an explicit instruction typed into the chat by a human overrides everything.

Migrating an existing convention over is meant to be trivial. The spec's own guidance for teams coming from an older AGENT.md naming: rename the file and leave a symlink behind for anything still looking for the old name.

How different tools actually read it

This is where a lot of secondhand explanations get sloppy, so here's what each tool does, verified against its own documentation rather than assumed from the file's popularity.

Codex, Cursor, opencode, Aider (partially), Jules, Devin, Amp, Factory, and most of the field read AGENTS.md natively, no configuration required, because most of them either co-designed the spec or adopted it as their primary rules file from the start. Cursor's own docs describe it as "a simple markdown file for defining agent instructions... an alternative to .cursor/rules for straightforward use cases," supported in the project root and in subdirectories, with no frontmatter needed the way its own .mdc rule files require.

Aider needs one line of config, not zero. It doesn't scan for AGENTS.md automatically the way Cursor or Codex do. You point it there explicitly in .aider.conf.yml:

read: AGENTS.md

Gemini CLI works the same way, one explicit setting rather than automatic discovery:

{
  "context": { "fileName": "AGENTS.md" }
}

opencode reads AGENTS.md as its native rules file, checked first in the project root and then in a user-level ~/.config/opencode/AGENTS.md for instructions that should apply everywhere. If no AGENTS.md exists in a project, opencode falls back to reading Claude Code's own CLAUDE.md and skills directory instead, a compatibility choice aimed at teams running both tools against the same repo. That fallback can be turned off with OPENCODE_DISABLE_CLAUDE_CODE if you don't want opencode picking up Claude-specific instructions.

Claude Code now reads AGENTS.md too, with one precedence rule. Until September 18, 2026, Anthropic's documentation said Claude Code reads CLAUDE.md, not AGENTS.md, and the standard workaround was a CLAUDE.md that imported the file. That day Claude Code engineer Thariq Shihipar announced support, as reported by The Register: from version 2.1.277, when a folder has no CLAUDE.md, Claude checks for and uses AGENTS.md. Users can toggle the behavior with /config.

Updated September 19, 2026: this section previously said Claude Code did not read AGENTS.md by default. That changed on September 18 and the text below reflects Anthropic's current documentation.

The rule that decides which file wins, from Anthropic's memory documentation: a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it counts as project instructions, and Claude reads it instead of AGENTS.md. Your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files don't count, so they keep loading alongside AGENTS.md. To load both files in one repo, set Project instructions to claude-md-and-agents-md in /config.

At session start Claude loads every AGENTS.md and .claude/AGENTS.md in the working directory and the directories above it. It also picks up a subdirectory's AGENTS.md when it opens a file there and that subdirectory has no CLAUDE.md of its own. @path imports inside AGENTS.md are expanded.

If a repo already has an AGENTS.md and also needs Claude-specific instructions, the documented pattern is still a short CLAUDE.md that imports it:

CLAUDE.md
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Old workarounds mostly need no action. A CLAUDE.md containing @AGENTS.md can stay: the docs say the import never makes Claude read the file twice, and it still covers sessions that can't load AGENTS.md directly. A symlink from CLAUDE.md to AGENTS.md also works, but Claude's Edit and Write tools refuse to write through a symlink, and on Windows creating one needs Administrator privileges or Developer Mode, so the @AGENTS.md import is the safer default there. A SessionStart hook that prints AGENTS.md should go, because it now adds a second copy to the context.

AGENTS.md loading is not available everywhere. Per the docs, it does not work on versions before 2.1.277, in sessions that don't fetch feature flags from Anthropic (for example on Amazon Bedrock or another third-party provider, or with telemetry disabled), in the first session after you install or upgrade, or when the built-in agents-md plugin or hooks are disabled. In an interactive session you should see a line such as no CLAUDE.md found; AGENTS.md loaded: /path/AGENTS.md. /context will not list an AGENTS.md that Claude reads directly, only one that a CLAUDE.md imports.

There's also a narrower, opt-in path: setting the environment variable CLAUDE_CODE_NEW_INIT=1 makes Claude Code's /init command read AGENTS.md (along with .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules) and fold the relevant parts into the CLAUDE.md it generates. Separately, /import can pull a one-time copy of another tool's instruction files, including AGENTS.md, into the matching CLAUDE.md, along with MCP servers, commands, subagents, and skills. That command requires Claude Code v2.1.213 or later.

The short version: AGENTS.md is now the one file the major coding agents share, Claude Code included, as long as no CLAUDE.md sits above it in the directory tree. Keep a CLAUDE.md only for instructions that are specific to Claude, and have it import AGENTS.md. For a side-by-side of the two files, a decision table by repo type and a cleanup checklist, see our CLAUDE.md vs AGENTS.md guide.

How to write one that's actually useful

Vague instructions get vague results. An agent reading "follow best practices" has no more to work with than a human would.

Write commands, not descriptions. "Run tests with pnpm turbo run test --filter <project_name>" is something an agent can execute. "Make sure your changes pass the test suite" is something it has to guess how to satisfy.

Say what "done" looks like. If a PR needs a specific title format or a passing lint run before it counts as finished, state that explicitly. Agents will treat unstated requirements as optional, because from their side, they are.

Scope large repos with nested files. Don't try to cram every package's quirks into one root-level file. A nested AGENTS.md in each subproject, covering only what's true for that subproject, keeps instructions precise and lets the agent load only what's relevant to the part of the codebase it's touching.

Include the "why" for anything non-obvious. "Don't touch legacy/" invites an agent to ask why, or worse, to not ask and touch it anyway. "legacy/ is frozen pending a migration tracked in ticket X" gives it a reason to actually respect the boundary.

Treat it as living documentation. Update AGENTS.md the way you'd update onboarding docs when the build process changes. A stale AGENTS.md that tells an agent to run a test command that no longer exists is worse than no file at all, because the agent will try it, fail, and burn a turn figuring out why.

Don't duplicate what a linter or CI config already enforces mechanically. If ESLint already blocks a pattern, you don't need a paragraph about it in AGENTS.md. Reserve the file for judgment calls a static tool can't make: which of two valid approaches this codebase prefers, which directories are off-limits and why, what the deploy sequence actually is.

FAQ

Do I need both an AGENTS.md and a CLAUDE.md? Not in most repos any more. From Claude Code 2.1.277, a repo with only an AGENTS.md works: Claude reads it when no CLAUDE.md exists. Add a short CLAUDE.md that imports it with @AGENTS.md when you have Claude-specific instructions, or when some of your sessions can't load AGENTS.md directly, such as older versions, third-party providers, or telemetry-disabled setups.

Does Claude Code ever read AGENTS.md automatically? Yes, since version 2.1.277 on September 18, 2026. If no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above, Claude reads AGENTS.md at session start. If one of those files exists, Claude reads it instead, unless Project instructions is set to claude-md-and-agents-md in /config. Older versions, some third-party-provider sessions, and sessions with telemetry disabled don't load AGENTS.md.

Is there a required format or schema? No. The spec's own FAQ says so directly: it's standard markdown, any headings you want, parsed as plain text.

What happens if instructions conflict, across nested files or between AGENTS.md and a chat prompt? The closest AGENTS.md to the file being edited wins over any AGENTS.md further up the directory tree. An explicit instruction typed directly into a chat session overrides both.

Will an agent actually run the test commands I list? According to the spec's FAQ, yes: if you list them, most agents that follow the convention attempt to execute the relevant checks and fix failures before considering the task done.

Who governs the spec, and can it change under me? AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation, after emerging from coordination between OpenAI Codex, Amp, Jules (Google), Cursor, and Factory. It's an open format rather than a single vendor's product.

Does AY Automate help teams set this up across a multi-agent stack? Yes. Getting AGENTS.md, CLAUDE.md, and the rest of a repo's agent configuration to actually agree with each other is part of the setup work we do on Claude Code and multi-tool engagements. If you're standardizing a codebase for more than one coding agent, start with our Claude Code agency services.