In practice
The agents.md site describes it as a README for agents: a predictable place to put the context and instructions an agent needs. It is standard Markdown with no required fields. Suggested sections are a project overview, build and test commands, code style, testing instructions and security considerations.
In a large repository you can add a separate AGENTS.md in each subproject. The site says agents read the nearest file in the directory tree, so the closest one takes precedence, and what you type in chat overrides everything.
Stewardship of the format sits with the Agentic AI Foundation, under the Linux Foundation. It is a convention, not a product. It isn't a plan for one job, and it doesn't enforce anything: an agent treats it as instructions to follow.
How to start
- Create AGENTS.md at the repo root.
- Add the commands to build, test and run, and the code style.
- List what not to touch.
- If you use Claude Code, you are done: it reads AGENTS.md directly when there is no CLAUDE.md. Add a CLAUDE.md with the line @AGENTS.md only for Claude-specific lines.
- Treat it as living documentation: update it when a rule changes.
Common mistakes
- Copying the same rules into a second file by hand. Import or link instead.
- Writing a long essay. Short, checkable lines are easier for an agent to follow.
- Putting this week's priorities in it. They change too often for a rules file.
Why it matters for product builders
If you run more than one agent, each can have its own rules file, and the copies drift. One shared AGENTS.md means you explain how you work once.
Cursor, Codex and Grok document that they read AGENTS.md. Claude Code reads it when a repository has no CLAUDE.md, and a CLAUDE.md can import it. See [CLAUDE.md vs AGENTS.md](/guides/claude-md-vs-agents-md).
What changes in AI-first products
This is a response to a new problem: several agents in one repository, each looking for its own file. The format gives them one name to agree on.
A shared rules file holds how you build. It does not say what to build next. Annsa holds that, as ranked priorities and specs with the evidence and Done When lines, which Claude Code, Cursor, Codex and Grok read over MCP.
See how Annsa does it: The spec →