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 is the one notable holdout: it reads its own CLAUDE.md by default, with AGENTS.md support layered on as an explicit compatibility step rather than automatic.

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 is the exception worth being precise about. Its documentation states this plainly: "Claude Code reads CLAUDE.md, not AGENTS.md." There's no silent fallback in the other direction, the way opencode falls back to CLAUDE.md. If a repo already has an AGENTS.md for other tools, Claude Code's documented path is to create a CLAUDE.md that imports it:

CLAUDE.md
@AGENTS.md

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

Claude loads the imported AGENTS.md at session start, then appends whatever Claude-specific instructions follow. A plain symlink works too if there's nothing Claude-specific to add (ln -s AGENTS.md CLAUDE.md), though Windows requires Administrator privileges or Developer Mode to create one, so the @AGENTS.md import is the safer default on that platform.

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: if you're standardizing a repo for multiple agents, AGENTS.md is the file every other major tool reads by default. Claude Code isn't ignoring the ecosystem, it's just keeping CLAUDE.md as its own memory format and treating AGENTS.md interoperability as something you turn on, not something that happens for you.

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? Only if you use Claude Code alongside tools that read AGENTS.md natively, and want both configured without duplicating instructions. The documented pattern is one AGENTS.md for the shared, tool-agnostic instructions, plus a short CLAUDE.md that imports it with @AGENTS.md and appends anything Claude-specific below.

Does Claude Code ever read AGENTS.md automatically? Not by default. It reads CLAUDE.md. AGENTS.md gets pulled in only through an explicit import or symlink in CLAUDE.md, through /init when CLAUDE_CODE_NEW_INIT=1 is set, or through a one-time /import (Claude Code v2.1.213+).

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, which is also why it isn't going to quietly become Claude Code's native file or anyone else's.

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.