Your repository has a CLAUDE.md that Claude Code's /init wrote months ago. Then someone on the team starts using Codex or Cursor and asks for an AGENTS.md, and most guides you find say Claude Code ignores that file. On AGENTS.md vs CLAUDE.md, that advice went out of date on 18 September 2026, when Claude Code started reading AGENTS.md by itself in projects without a CLAUDE.md. Most of the pages ranking for this question still say otherwise. So the useful question has moved on from which file is the standard to what each tool does when a repository has both.
If you're setting this up so colleagues who don't code can ask for changes too, the final section is about that case.
The short answer
If everyone on the project uses Claude Code, keep CLAUDE.md. If the team mixes tools, write AGENTS.md and either drop CLAUDE.md or cut it down to one line that imports AGENTS.md. Both files are plain Markdown with no required fields, so moving the content across is a copy and paste.
What AGENTS.md is
The AGENTS.md site calls it "a README for agents": the commands and house rules a coding agent needs before it touches anything. It grew out of work between OpenAI's Codex, Amp, Google's Jules, Cursor and Factory, and OpenAI donated it to the Agentic AI Foundation at the Linux Foundation on 9 December 2025, next to Anthropic's MCP and Block's goose. Anthropic is a platinum member of that foundation, which makes the nine months its own agent took to read the file a little awkward.
The site has claimed more than 60,000 open-source projects since that announcement. The list of tools that read the file is long: Codex, Cursor, GitHub Copilot's cloud agent, Jules, Amp, Devin, Windsurf, Zed, Warp, Junie and opencode among them. Gemini CLI reads GEMINI.md by default and only picks up AGENTS.md if you name it in the context.fileName setting.
What CLAUDE.md is
CLAUDE.md is Claude Code's instruction file, and it has more machinery. Claude Code reads a managed policy file first, then your personal ~/.claude/CLAUDE.md, then the project's CLAUDE.md or .claude/CLAUDE.md, then a git-ignored CLAUDE.local.md. The files are joined together, not swapped for one another, and files in subfolders load only when Claude starts working in that folder (Anthropic's memory docs).
Two features have no AGENTS.md equivalent. A line like @docs/testing.md imports another file, up to four hops deep, and .claude/rules/ holds one rule per file, optionally limited to certain paths. Anthropic suggests keeping each CLAUDE.md under 200 lines, and it's candid that the file arrives as a message after the system prompt with "no guarantee of strict compliance". Anything that must happen every time belongs in a hook.
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277, published on 18 September 2026. The request had been the most-reacted issue in Claude Code's GitHub repository, with more than 6,600 reactions, and Anthropic closed it on 17 August pointing people at an import or a symlink. A month later the changelog read "in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead", and version 2.1.281 on 23 September extended that to Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways and sessions with telemetry off. A couple of the guides that did update still say those setups are missing out. They aren't.
The rule is strict. If there's a CLAUDE.md, a .claude/CLAUDE.md or a CLAUDE.local.md in the working folder or above it, Claude Code reads only those and skips AGENTS.md. You can change that under "Project instructions" in /config, where claude-md-and-agents-md loads both.
Watch for one trap. Adding a personal CLAUDE.local.md to a repository that only has AGENTS.md quietly switches AGENTS.md off for you. And Codex's AGENTS.override.md does nothing in Claude Code, which doesn't read it at all.
When a repository has both files
| Tool | Reads AGENTS.md | Reads CLAUDE.md | With both in the repo |
|---|---|---|---|
| Claude Code | Only when there's no CLAUDE.md | Yes | CLAUDE.md only, unless set to load both |
| Codex | Yes, from the repo root down to your folder | Not by default | AGENTS.md |
| Cursor | Yes, root and subfolders | Yes, applied to every conversation | Both, so shared rules can arrive twice |
| GitHub Copilot cloud agent | Yes, the nearest file wins | A root CLAUDE.md, as an alternative | Either can apply |
| Gemini CLI | Only if named in its settings | No | GEMINI.md, unless configured |
From each vendor's documentation, read on 5 October 2026.
The Cursor row is the one almost nobody mentions. Plenty of articles describe CLAUDE.md as Claude-only, yet Cursor, Copilot's command-line tool and several other agents read it too. A CLAUDE.md that repeats your AGENTS.md word for word costs you twice in those tools.
A setup that works for a mixed team
Put the real instructions in AGENTS.md at the repository root. Then pick one of these for Claude Code:
- No CLAUDE.md at all. Simplest, and fine as long as everyone runs version 2.1.277 or later.
- A CLAUDE.md whose first line is
@AGENTS.md, with any Claude-only notes underneath. It works on every version, and Anthropic's docs say it never makes Claude read AGENTS.md twice. - A symlink,
ln -s AGENTS.md CLAUDE.md. It works, but on Windows symlinks need admin rights or Developer Mode and Git can check them out as plain text, so use the import there.
While you're at it, clear out old workarounds. A CLAUDE.md that says "read AGENTS.md" in words is unreliable, because Claude may never open the file. A SessionStart hook that prints AGENTS.md into the session now loads it a second time.
What belongs in the file
Two studies point in different directions, and together they're useful. Researchers at ETH Zurich found that context files "do not generally improve task success rates" while adding more than 20% to the cost, with files written by a model doing worst; hand-written ones did better and helped every agent they tested except Claude Code (the paper, revised 29 September 2026). A smaller study that tested only Codex found AGENTS.md cut median run time by 28.6% and output tokens by 16.6% (the paper).
What both support is a short file a person wrote, holding only what an agent can't work out from the code. So don't commit an unedited /init file. A good one looks more like this:
# AGENTS.md
## Commands
- Install: pnpm install
- Run the app: pnpm dev (serves on port 3000)
- Before you finish: pnpm typecheck and pnpm test:changed
## Rules
- Use pnpm. Never npm or yarn.
- Don't edit anything in src/generated; run pnpm codegen instead.
- Database changes go in a new file under supabase/migrations. Never edit an old one.
- Secrets live in .env.local, which isn't committed. Never print or commit them.
Leave out the tour of the folders, style rules a linter already enforces and anything the README covers. Size limits differ more than people expect: Codex stops reading once all its AGENTS.md files together reach 32 KiB, Devin takes the first 16 KiB of each file, and Cursor suggests keeping a rule under 500 lines.
When teammates never open a terminal
Every file above helps an agent that someone technical is driving. The product manager who wants a pricing table changed, or the marketer with a new headline, won't be editing AGENTS.md or reading a diff.
Refinar is made for those people. It opens the app from its GitHub repository, the same repository these files live in, and runs it in a cloud preview. They say what should change, or point at it on the page, then watch an AI agent make it and publish the result or send it for review. Changes that reach sign-in, payments or customer data go to a developer before they ship (how it works).
If your repository is ready for agents and half your team isn't ready for a terminal, give Refinar a try on it.