What is AGENTS.md?
AGENTS.md is a Markdown file you commit to a repository to tell AI coding agents how to work in it: setup and test commands, code style, conventions, things to avoid. It has no required format. Codex, Cursor, Zed, Copilot's coding agent, Claude Code and many others read it, so one file serves every agent on the team.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Create AGENTS.md at the repository root. It is ordinary Markdown: headings and bullets, no required fields.
Write what a new teammate would need: how to install and run, how to test, code style, commit and PR conventions, what not to touch.
In a monorepo, add nested AGENTS.md files in subprojects. The agent uses the one closest to the file it is editing.
Each agent loads the file when a session starts. Codex, for example, concatenates the chain from the root down to your working directory.
Your chat instructions still win over anything in the file, so put stable rules in AGENTS.md and one-off asks in the prompt.
Source: AGENTS.md
AGENTS.md versus a README
A README is written for people: what the project is, why it exists, how to get started, with screenshots and a badge or two. An AGENTS.md is written for the thing that will edit the code. It skips the pitch and lists what an agent trips over: the exact test command, the lint rule the team argues about, the folder you must not touch, the PR title format. The agents.md site calls it a README for agents, and the split keeps each file honest. Build details that would clutter the README have a home, and the README stays readable.
The format is deliberately nothing. Plain Markdown, any headings you like, no required fields. The name came out of OpenAI's Codex, Amp, Google's Jules, Cursor and Factory agreeing on one, and the site says it is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Example: a monorepo
Say a repo holds a web app and an API. The root AGENTS.md carries the rules that apply everywhere: package manager, commit style, how to run the full test suite. apps/api/AGENTS.md adds the API's own conventions. When an agent edits a file under apps/api, the nearest file applies. The agents.md site reports that OpenAI's main repository had 88 of them at the time of writing.
Codex, which has published the most detailed rules, builds a chain once per session. It starts at the project root, walks down to your current directory, takes at most one file per directory, and concatenates them from the root downward, separated by blank lines. Files nearer your working directory come later in the prompt and so carry more weight. A file named AGENTS.override.md replaces the regular one at its level. Codex stops adding files once the combined size reaches 32 KiB by default, and it stops searching when it reaches your current directory.
Why it matters
Before a shared name, every tool had its own file and teams maintained several near-copies that drifted apart. One file every agent reads means the rules are written once, and the person using Cursor and the person using Codex get the same ones. Claude Code reads AGENTS.md directly when a repository has no CLAUDE.md, so even the tool with its own convention falls in line.
The same idea applies beyond repositories. An Intraface board has a collab.md: house rules and design language that every agent reads when it pulls the board, whatever tool it is running in. The file travels with the thing being edited, not with the agent.
Common mistakes
- Writing the manual. Long files get cut off by size limits and diluted in the model's attention. Keep the always-true rules and link out for the rest.
- Restating the README. If the agent needs the architecture, it can read the code. Tell it what it cannot derive: taste, history, hazards.
- Contradictions between nested files. The nearest file is meant to refine the root, not reverse it. When they disagree, you get whichever the model noticed last.
- Expecting enforcement. The file is context. If a rule must hold, put it in CI or a hook, and let AGENTS.md explain why it is there.
FAQ
- Does Claude Code read AGENTS.md?
- Yes, from v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If there is one, Claude reads that instead unless you change the Project instructions setting or add an @AGENTS.md import.
- How long should an AGENTS.md file be?
- Short enough to be read whole. Codex stops adding files once the combined chain reaches 32 KiB by default, and every tool spends context on each line. Put the rules that are always true at the root and the rest in nested files.
- Can I rename an existing rules file to AGENTS.md?
- Yes. The agents.md site suggests renaming the old file and leaving a symlink under the old name so tools that still look for it keep working.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.