What Is AGENTS.md?
AGENTS.md is a Markdown file placed in a code repository to give AI coding agents project-specific instructions: how to build and test the project, its conventions, and anything an agent should know before changing code. It has no required sections and no schema, and agents read the file closest to the code they are editing.
What goes in it, and where it lives#
The file sits at the root of the repository, and large codebases add more of them further down: a monorepo can ship one per package, and the project's own site notes that OpenAI's main repository had 88 of them at the time of writing. There are no required fields. The site's answer to that question is that the file "is just standard Markdown", so headings are a convention rather than a contract. What most teams put in one is the same handful of things: build and test commands, code style, testing instructions, security constraints and pull request conventions.
Precedence is where the convention and the implementations come apart. The site's rule is that the nearest file to the edited code wins and an explicit instruction in chat overrides everything. Codex does something different in practice, concatenating files from the root down so that closer files win by appearing later in the prompt, and GitHub Copilot turns support for files outside the workspace root off by default in the IDE. Nesting works, and it does not work identically everywhere.
Which tools read it#
| Tool | Reads it | What to know |
|---|---|---|
| OpenAI Codex | Yes, natively | Where the file originated. Reads global and project scopes, concatenated root-down |
| Cursor | Yes, natively | Root and subdirectories; nested instructions combine, with the more specific winning |
| GitHub Copilot | Yes | Coding agent since August 2025. In the IDE, files outside the workspace root are off by default |
| Gemini CLI | Only if configured | Defaults to GEMINI.md; AGENTS.md has to be added to the context filename setting |
| Claude Code | No | Reads CLAUDE.md. Anthropic documents importing AGENTS.md from it, which is the usual fix |
Verified against each vendor's own documentation, 16 September 2026. The project site lists 23 compatible tools, which counts native support and manual opt-in together; Aider and Gemini CLI both need a configuration change.
Where it came from, and what it does not fix#
OpenAI released the format in August 2025 and gave it away four months later. It was one of three anchor contributions to the Agentic AI Foundation at the Linux Foundation in December 2025, alongside Anthropic's Model Context Protocol and Block's goose, and its technical charter was adopted on 8 December 2025. Governance sits with individual maintainers rather than reserved company seats.
The site says "over 60k open-source projects", and that string has not changed since 8 December 2025, which is the same day the Linux Foundation used the same number in its announcement. Treat it as a floor observed nine months ago rather than a current count.
A good file is also not a guarantee of good output. Josh Mock argues that the file's presence now reads to some engineers as a signal that "the agents have been here", before concluding it is still the best defence a maintainer has. Tessl's Simon Maple makes the sharper point: research showing context files do not reliably help is evidence that "unvalidated context is useless, and often harmful", rather than evidence against the format. Nobody tests whether the instructions in these files earn their place, and until a team does, an AGENTS.md is a hypothesis.
Frequently asked questions#
Does Claude Code read AGENTS.md?
No. Claude Code reads CLAUDE.md, and Anthropic's documentation says so directly. The fix it recommends is a CLAUDE.md that imports the other file with a line reading @AGENTS.md, so both tools work from the same instructions without a second copy, and any Claude-specific guidance goes underneath. A symlink does the same job when nothing Claude-specific is needed, though it needs Developer Mode on Windows. Run /context afterwards and check that CLAUDE.md appears under memory files.
Is AGENTS.md the same as CLAUDE.md?
They do the same job for different tools, and CLAUDE.md does considerably more. AGENTS.md is a filename and a nearest-file-wins convention. CLAUDE.md has a defined hierarchy of managed policy, user, project and local scopes, an import syntax, path-scoped rules and organisation-wide deployment. The interoperation runs both ways: GitHub Copilot's coding agent reads CLAUDE.md and GEMINI.md as well as AGENTS.md, so CLAUDE.md is itself a cross-vendor file in practice.
Where do you put an AGENTS.md file, and should it be committed?
At the root of the repository, committed like any other project documentation, because its whole purpose is that every contributor and every agent gets the same instructions. Monorepos add one per package, and the file closest to the code being edited is the one that applies. Personal preferences belong in a local or user-scoped file instead, which is what the tools provide for exactly this reason.
What should go in an AGENTS.md file?
The commands an agent cannot guess and the rules it would otherwise break: how to build, how to run tests, how to lint, which directories are off limits, and the conventions your reviewers enforce. Keep it short and specific. Every instruction is loaded into context on every turn, so a long file costs tokens continuously and buries the lines that matter.