AGENTS.md is a plain Markdown file at the root of a repository that tells coding agents how to work in it: build and test commands, code style, and other things that would clutter a README. The agents.md site calls it “a README for agents”. It has no required fields, so any headings work, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation.

What to put in it

The agents.md site suggests a project overview, build and test commands, code style, testing instructions and security considerations. For commands, the site says an agent will run the test commands you list and try to fix failures before it finishes.

How the big tools read it

Claude Code, Cursor and Codex all read the file. They differ on which file wins and how files combine.

ToolWhere it looksSeveral files
Claude CodeEvery AGENTS.md and .claude/AGENTS.md in the working directory and above, read as project instructions only when there is no CLAUDE.md thereSubdirectory files load when Claude opens a file there with the Read tool, if that directory has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md of its own
CursorProject root and subdirectoriesNested files are combined with parent directories, and the more specific one takes precedence
Codex~/.codex first, then walks from the project root toward the working directory, at most one file per directory (AGENTS.override.md wins over AGENTS.md)Files are joined root first, so the closest one comes last and overrides earlier guidance; it stops at 32 KiB combined by default

On the format side, the agents.md site says that in a monorepo the closest file takes precedence, and that explicit user chat prompts override every AGENTS.md.

Claude Code and CLAUDE.md

Claude Code reads AGENTS.md directly in v2.1.277 and later; earlier versions read CLAUDE.md files only, which is why older guides say it ignores the file. A repository set up for other agents now works without adding a CLAUDE.md, an import, or a setting. By default:

AGENTS.md or Cursor rules

Cursor describes AGENTS.md as a plain Markdown file without metadata, an alternative to .cursor/rules for simple cases. Rules in .cursor/rules use frontmatter fields such as description, globs and alwaysApply, so choose them when you need a rule to apply only to certain files. For ready-made rule files, see Awesome Cursor Rules MDC, a collection of Cursor rules in MDC format.

Tools with a setting

The agents.md site lists read: AGENTS.md in .aider.conf.yml for Aider and "context": { "fileName": "AGENTS.md" } in .gemini/settings.json for Gemini CLI. To migrate an existing file, it suggests renaming it to AGENTS.md and leaving a symlink under the old name.