Based on OpenAI’s official docs, checked October 25, 2026

What is AGENTS.md? The open instruction file for coding agents

AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work on the project: how to install, build and test it, which conventions to follow, and what to avoid. The agents.md site calls it a README for agents and says more than 60,000 open-source projects use it. It has no required fields, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. This guide covers what goes in the file, how nested files and overrides work, and how Codex, Cursor and Claude Code load it, from each project's official docs checked October 25, 2026.

1. 1. Create AGENTS.md at the repository root

   Add a file named AGENTS.md next to your README. It is standard Markdown with no frontmatter or required headings; agents read the text you write. agents.md notes that most coding agents can draft one for you if you ask.

2. 2. Cover the commands an agent needs

   Start with what a new teammate would need on day one: how to install dependencies, start the dev server and run the tests. agents.md says agents will try to run the checks you list and fix failures before finishing a task.

   # AGENTS.md
   
   ## Setup commands
   - Install deps: `pnpm install`
   - Start dev server: `pnpm dev`
   - Run tests: `pnpm test`
   
   ## Code style
   - TypeScript strict mode
   - Single quotes, no semicolons

3. 3. Add conventions, PR rules and gotchas

   The agents.md site suggests a project overview, build and test commands, code style, testing instructions and security considerations, plus anything else you would tell a new teammate: commit message or pull request format, large datasets to avoid, deployment steps.

4. 4. Use nested files in a monorepo

   Put another AGENTS.md inside each package. Agents read the nearest file in the directory tree, so the closest one wins for files in that package, and explicit instructions in the chat override everything.

5. 5. Check what your agent actually loaded

   In Codex, ask it to list its instruction sources; it reports the global file first, then the repository root, then nested files. In Claude Code, an interactive session shows a line such as "no CLAUDE.md found; AGENTS.md loaded" when it picks the file up.

   codex --ask-for-approval never "List the instruction sources you loaded."

Why a separate file from README.md

README.md is written for people: a quick start, a project description and contribution notes. AGENTS.md holds the extra, often detailed context an agent needs, such as exact build steps, test commands and conventions, that would clutter a README or does not matter to human contributors. The agents.md project chose a vendor-neutral name so one file can work across tools instead of each agent inventing its own.

How Codex reads AGENTS.md

Codex builds an instruction chain once per run. It first reads a global file from your Codex home (~/.codex by default): AGENTS.override.md if present, otherwise AGENTS.md. It then walks from the project root (usually the Git root) down to your current directory, taking at most one file per directory, checking AGENTS.override.md, then AGENTS.md, then any names listed in project_doc_fallback_filenames.

Files are joined from the root down, so files closer to your working directory appear later and take precedence. Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. If you hit that cap, raise the limit or split instructions into nested directories.

How Cursor reads AGENTS.md

Cursor treats AGENTS.md as a plain Markdown alternative to .cursor/rules for straightforward projects, with no metadata. It supports AGENTS.md in the project root and in subdirectories. Use .mdc rules in .cursor/rules when you need globs or apply-intelligently behaviour; a plain .md file in .cursor/rules is ignored.

How Claude Code reads AGENTS.md

Since v2.1.277, Claude Code can read AGENTS.md as your project instructions with no import or setting. By default it does so only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it; if one exists, it reads your CLAUDE.md files only. Your personal ~/.claude/CLAUDE.md and .claude/rules/ files do not block it and keep loading alongside.

To keep both, put @AGENTS.md in CLAUDE.md so the shared file is imported, or change the Project instructions setting so Claude always reads both. Anthropic notes that in some sessions Claude cannot read AGENTS.md directly, and the import works there.

Migrating an existing instruction file

agents.md suggests renaming an existing file to AGENTS.md and leaving a symbolic link under the old name, so tools that still look for it keep working. Some tools need a setting instead: Gemini CLI can be pointed at AGENTS.md with context.fileName in .gemini/settings.json, and Aider with read: AGENTS.md in .aider.conf.yml.

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Tips

• Write commands exactly as they should run, in backticks, so the agent can copy them.
• Keep it short and specific; Codex stops loading instruction files at 32 KiB by default.
• Treat AGENTS.md as living documentation and update it in the same pull request that changes a command.
• Never put secrets or tokens in AGENTS.md; it is committed with the repository.

Next steps

Sources

• https://agents.md/ · checked 2026-10-25
• https://developers.openai.com/codex/guides/agents-md · checked 2026-10-25
• https://code.claude.com/docs/en/memory · checked 2026-10-25
• https://cursor.com/docs/rules · checked 2026-10-25