What is AGENTS.md?
AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to build, test and work in the project.
AGENTS.md is a plain Markdown file that gives AI coding agents the project-specific instructions they need: how to build, how to test, what conventions to follow. The official site puts it as “a README for agents.” It has no required fields, so agents read whatever text you write.
It exists because a human README is the wrong place for detail like exact test commands or lint rules, and because each coding tool used to want its own file. AGENTS.md is one file that many tools read. It is a small piece of an agent harness and a simple form of context engineering for agentic coding.
What goes in it
The format has no schema, so contents are up to you. The site’s examples cover setup commands (install, dev server, tests), code style, testing steps such as running lint before merging, and pull request title format. The same page says that if you list test commands, agents will try to run the relevant checks and fix failures before they finish. The site links public examples such as openai/codex, apache/airflow and temporalio/sdk-java.
Because it is context and not enforcement, a rule in AGENTS.md is a request. Anthropic’s docs say Claude treats these files as context, not enforced configuration, and recommend a hook when an action must be blocked.
Which file wins
| Situation | What happens |
|---|---|
| Several AGENTS.md files in a repo | The spec says the closest one to the edited file wins |
| A user prompt contradicts the file | Explicit chat prompts override everything |
| Codex, global and project files | Codex concatenates files from the repository root down; files closer to the working directory come later and take precedence |
Codex, AGENTS.override.md |
Codex checks it before AGENTS.md in each directory and in ~/.codex, and uses at most one file per directory |
| Claude Code, AGENTS.md only | Claude reads it by default, on v2.1.277 or later |
| Claude Code, AGENTS.md and CLAUDE.md | Claude reads only the CLAUDE.md files by default, unless the CLAUDE.md imports AGENTS.md |
Size limits
Keep it short. Codex’s project_doc_max_bytes defaults to 32 KiB, and once combined content reaches that, Codex stops adding files. Anthropic recommends under 200 lines per CLAUDE.md file because longer files use more context and reduce adherence. Both limits are about the same problem as context rot: more instructions are not always better ones.
Addy Osmani writes that every line in a good AGENTS.md should trace back to something that went wrong, which is a useful test for what to keep.
Using it with other tools
The official FAQ gives a migration path for an existing file: rename it and leave a symlink under the old name, for example mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md. For Aider, add read: AGENTS.md to .aider.conf.yml. For Gemini CLI, set the context file name to AGENTS.md in .gemini/settings.json.
For Claude Code, Anthropic recommends a CLAUDE.md that starts with @AGENTS.md, followed by any Claude-specific instructions. A symlink also works if you have nothing Claude-specific to add.
The official site lists many tools that read AGENTS.md, among them Codex, Cursor, GitHub Copilot’s coding agent, Gemini CLI, Aider, Jules, Zed, Windsurf, JetBrains Junie and goose. Check each tool’s docs for exact behavior, since as the table above shows, loading rules differ.
Who maintains it
OpenAI released AGENTS.md in August 2025. On December 9, 2025 the Linux Foundation announced the Agentic AI Foundation, with AGENTS.md, Anthropic’s Model Context Protocol and Block’s goose as its three founding contributions. The release says more than 60,000 open source projects and agent frameworks had adopted it.
Tracing what the agent actually follows
An instruction file only helps if the agent follows it. If you run your own coding agents, traces show which files and commands a session used, and error analysis of failed runs tells you which line to add to AGENTS.md next. HoneyHive’s docs cover how to trace agent sessions.
FAQ
What is AGENTS.md?
It is a plain Markdown file that gives coding agents project-specific instructions. The official site calls it a README for agents.
Where does AGENTS.md go?
Usually the repository root. In a monorepo you can add one per subproject, and the spec says the closest file to the edited file wins.
Does Claude Code read AGENTS.md?
Yes, from v2.1.277, but by default only when there is no CLAUDE.md. Anthropic's docs suggest putting @AGENTS.md in a CLAUDE.md to share one file.
How long should AGENTS.md be?
The spec sets no limit, but tools do. Codex stops reading at 32 KiB of combined instructions by default, and Claude Code's docs target under 200 lines per CLAUDE.md file.
Who maintains AGENTS.md?
The Agentic AI Foundation, part of the Linux Foundation. OpenAI contributed it at the foundation's launch in December 2025.