What is AGENTS.md? A guide for coding agents

AGENTS.md is described as an open, simple format for guiding coding agents. The agents.md site calls it a 'README for agents' that holds build steps, tests and conventions that would clutter a human-oriented README.

AGENTS.md has no required fields. It is standard Markdown and any headings can be used; the agent just parses the text.

The agents.md site says AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation. It credits OpenAI Codex, Amp, Jules from Google, Cursor and Factory as contributors to its development, and it claims use by over 60k open-source projects.

The site lists tools that support it, including OpenAI Codex, Google Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, GitHub Copilot coding agent, Windsurf and Augment Code.

The agents.md example file has sections for setup commands, code style, dev environment tips, testing instructions and PR instructions.

The agents.md FAQ says listed test commands are likely to be run by the agent.

The FAQ suggests migrating a differently named file by renaming it to AGENTS.md and leaving a symlink under the old name. Aider needs read: AGENTS.md in .aider.conf.yml, and Gemini CLI needs a context.fileName setting.

For nested files, agents read the nearest AGENTS.md in the directory tree, and the closest one takes precedence. Explicit user chat prompts override everything. For monorepos the agents.md page suggests a separate AGENTS.md inside each package.

In Codex, project scope starts at the project root (typically the Git root) and walks down to the current working directory. In each directory Codex checks AGENTS.override.md, then AGENTS.md, then any project_doc_fallback_filenames, including at most one file per directory. Files are concatenated from the root downward, separated by blank lines. Files closer to the working directory come later and override earlier guidance.

Cursor supports AGENTS.md in the project root and in subdirectories. A nested file applies when working in that directory or its children and is combined with parent directories, with more specific instructions taking precedence.

Claude Code loads CLAUDE.md files from the working directory and every directory above it, concatenated from the filesystem root down, so instructions closest to the launch directory are read last. It loads a subdirectory's AGENTS.md when Claude reads a file there and that subdirectory has no CLAUDE.md of its own. The docs say CLAUDE.md content is treated as context, not enforced configuration; to block an action regardless, use a PreToolUse hook.

Codex builds its instruction chain once per run (once per TUI session), so edits take effect after restart. Globally it reads AGENTS.override.md if present, otherwise AGENTS.md, from ~/.codex (or CODEX_HOME), using only the first non-empty file. It stops adding files once combined size reaches project_doc_max_bytes (32 KiB by default). This and the fallback filenames are set in ~/.codex/config.toml.

Cursor presents AGENTS.md as an alternative to .cursor/rules for straightforward use cases. It describes it as a plain markdown file without metadata or complex configuration, unlike Project Rules, which have Always Apply, Apply Intelligently, Apply to Specific Files and Apply Manually modes.

Claude Code can read AGENTS.md as project instructions; the page says this requires Claude Code v2.1.277 or later. By default it reads AGENTS.md only if there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. If both exist, it reads the CLAUDE.md files only. The 'Project instructions' setting has values including claude-md-or-agents-md (the default) and claude-md-and-agents-md, which loads both.

To share one file across tools, the Claude Code docs suggest a CLAUDE.md containing an @AGENTS.md import plus any Claude-specific notes, or ln -s AGENTS.md CLAUDE.md. The page warns that symlinks are awkward on Windows.