Definition
AGENTS.md
AGENTS.md is a project-level configuration file recognised by Codex, and increasingly by other tools, that defines how AI agents should behave in a repository. It is placed at the project root or in subdirectories, and specifies coding standards, test commands, deployment patterns and tool preferences. Its purpose matches CLAUDE.md; the convention differs.
Why it matters
It is the closest thing the space has to a vendor-neutral convention. A repository that carries one gives any agent recognising the file the same standards, test commands and deployment patterns, without per-tool configuration.
How each tool handles it
- Cursor
- Uses
.cursor/rulesand.cursorignoreinstead. - Claude Code
- Uses CLAUDE.md, to the same purpose.
- Codex
- The native format, read hierarchically.
Frequently asked questions
Which tools read AGENTS.md?
Codex recognises it natively, and other tools increasingly do. Claude Code reads CLAUDE.md and Cursor reads .cursor/rules, so a repository worked on by several agents commonly carries more than one of these files.
What should go in AGENTS.md?
Coding standards, the commands that run tests, deployment patterns and tool preferences — the things an agent would otherwise have to infer from the codebase, and would sometimes infer wrongly.
Can a repository have both AGENTS.md and CLAUDE.md?
Yes, and repositories worked on by more than one agent commonly do. Each tool reads its own convention and ignores the others, so the cost of carrying both is duplication in the files, not conflict between them.