AGENTS.md: the instruction file coding agents share, and where each one looks for it
AGENTS.md is a README for coding agents: one Markdown file that Codex, Copilot, Cursor and, under one condition, Claude Code read before they touch your code. The format is simple. The differences are in where each tool looks.
Updated 14 November 2026. Every behaviour below comes from each tool's official documentation, read that day. The sources are linked in each section.
AGENTS.md is a plain Markdown file, usually at the root of a repository, that tells AI coding agents how to work on the project: how to build and test, which conventions to follow, what never to touch. There are no required fields. The format is described on agents.md, which says it is used by over 60,000 open-source projects and is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Which tools read AGENTS.md, and from where
The file is shared; the loading rules are not. This is what each tool's documentation says, checked on 14 November 2026.
- OpenAI Codex: reads AGENTS.md before doing any work. First a global file in ~/.codex (AGENTS.override.md if it exists), then one file per directory from the project root down to the current directory. Closer files come later and override earlier guidance. The combined size stops at 32 KiB by default (project_doc_max_bytes).
- Claude Code: reads AGENTS.md as project instructions from version 2.1.277, but by default only when there is no CLAUDE.md in the working directory or above it. If both exist, it reads CLAUDE.md.
- GitHub Copilot: one or more AGENTS.md files anywhere in the repository; the nearest one in the directory tree takes precedence. A single CLAUDE.md or GEMINI.md at the root also works. The cloud agent, code review, Copilot CLI and VS Code Chat list it; Visual Studio, JetBrains and Xcode chat do not.
- Cursor: AGENTS.md at the project root and in subdirectories. Nested files are combined with their parents and the more specific one takes precedence. It is a plain alternative to .cursor/rules, without metadata.
- VS Code: with the Copilot agent, AGENTS.md is found at the repository root, in the working directory and in the directories between them. The older Local mode uses the chat.useAgentsMdFile setting (on by default) and chat.useNestedAgentsMdFiles (off by default).
The agents.md site also lists Jules, Aider, Zed, Warp, Windsurf, Devin, Junie and Gemini CLI among the agents that support the format. Sources: Codex, Claude Code, GitHub Copilot, Cursor, VS Code.
AGENTS.md and CLAUDE.md in the same repository
This is where most guides contradict each other. Anthropic's documentation is precise: by default, Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or above it. As soon as a CLAUDE.md exists there, Claude reads that file instead.
To keep one source that every tool reads, Anthropic recommends a CLAUDE.md next to it that imports it with a single line, @AGENTS.md, followed by anything only Claude needs. A symlink (ln -s AGENTS.md CLAUDE.md) also works when you need nothing Claude-specific, but Claude's Edit and Write tools refuse to write through a symlink, and on Windows the documentation points to the import instead.
@AGENTS.md
## Claude Code
- Use plan mode for changes under src/billing/.Two more details from the same page. Claude Code does not read AGENTS.override.md (which Codex uses), AGENTS.local.md or anything under a .agents/ folder. And the Project instructions setting in /config can load both files at once (claude-md-and-agents-md) without reading the same AGENTS.md twice.
Nested files: which one wins
In a monorepo you can put an AGENTS.md in each package. The agents.md FAQ gives the general rule: the closest AGENTS.md to the edited file wins, and an explicit instruction in the chat overrides everything. The tools then differ in the details. Codex joins the files from the root down to your current directory and does not read below it. Cursor combines nested files with their parents. Copilot gives precedence to the nearest file. Claude Code loads a subdirectory's AGENTS.md when it reads a file there, if that folder has no CLAUDE.md.
What to put in AGENTS.md
- Commands an agent cannot guess: install, build, lint, run all tests, run one test.
- Conventions that differ from the defaults: “amounts are integers in cents”, “one file per API route”.
- Things never to do: “never edit src/generated/”, “no new dependency without asking”.
- Where things are: the few folders that matter and what lives in them.
- How to hand work back: commit message format, what to check before opening a pull request.
Write instructions that can be checked, “run pnpm test before committing” rather than “make sure it works”, and keep the file short. Every line is loaded at the start of every session, by every agent that reads it, and Codex stops adding instruction files at 32 KiB by default.
# Invoicing API
## Commands
- Install: `pnpm install`
- Test all: `pnpm test` · one file: `pnpm test src/invoices/total.test.ts`
- Lint before committing: `pnpm lint`
## Conventions
- TypeScript strict, named exports only
- API handlers in `src/api/handlers/`, one file per route
- Amounts are integers in cents, never floats
## Never
- Edit files in `src/generated/` (run `pnpm codegen` instead)
- Add a dependency without asking
## Before a pull request
- `pnpm lint && pnpm test` pass
- Commit messages: `area: what changed`What to keep out of it
- Secrets: API keys and passwords have nothing to do in a file committed to the repository and loaded into every session.
- Settings for one tool only: they belong in CLAUDE.md, .cursor/rules or that tool's own configuration.
- Long documentation: link to it instead of pasting it.
- A history of decisions: why you chose Postgres, what the client asked last week, the bug you already chased for two days.
That last one is the trap. AGENTS.md is read in full at every start, by every agent. It is the right place for rules that rarely change, and the wrong place for knowledge that keeps growing. That knowledge belongs in a memory the agent searches only when it needs it, and that every agent you use can read.
Pryzm for desktop is one: a free app, with no account, that keeps this memory in a SQLite file on your computer and connects Claude Code, Claude Desktop, Cursor and VS Code in one click, so they all read the same decisions. One line in AGENTS.md is enough to make agents use it: “Before starting, search the Pryzm memory for past decisions on this project, and save new ones there.” For the Claude side, see the CLAUDE.md guide.
Frequently asked questions
What is AGENTS.md?
A plain Markdown file, usually at the root of a repository, with instructions for AI coding agents: build and test commands, conventions, things to avoid. It has no required fields. The format is stewarded by the Agentic AI Foundation under the Linux Foundation.
Does Claude Code read AGENTS.md?
Yes, from version 2.1.277, but by default only when there is no CLAUDE.md in the working directory or above it. To use both, put a CLAUDE.md containing the line @AGENTS.md next to it.
Where does Codex look for AGENTS.md?
In ~/.codex for global instructions, then in each directory from the project root down to the current directory, one file per directory, with AGENTS.override.md taking priority. The combined size is capped at 32 KiB by default.
Should I use AGENTS.md or CLAUDE.md?
If you use several coding agents, write the shared rules in AGENTS.md and keep a short CLAUDE.md that imports it and adds what only Claude needs. If you only use Claude Code, CLAUDE.md is enough.
Can AGENTS.md replace a memory?
No. It is loaded in full at every session, so it should hold stable rules. Decisions and context that keep growing are better kept in a memory server the agent searches when it needs to.