TL;DR
Claude Code reads AGENTS.md now, but only if your project has no CLAUDE.md or CLAUDE.local.md.
In my test, 2 of 4 common setups lost AGENTS.md with no warning.
The fix is one line: put
@AGENTS.mdat the top of your CLAUDE.md.
Claude Code skipped my rules file in 2 of 4 common setups I tested on 21 November. It gave no warning. The file was AGENTS.md, the one file most coding agents now share.
I keep one set of rules for 8 AI coding agents. My open-source project obsidian-second-brain ships the same vault rules to Claude Code, Codex, Gemini CLI and 5 others. So which file each agent reads is a daily question for me. A wrong guess means an agent works without the rules.
Since version 2.1.277, Claude Code can read AGENTS.md. Most posts stop there. The catch sits in one table in Anthropic’s docs, and I tested it to be sure.
What AGENTS.md is
AGENTS.md is a plain text file of instructions for AI coding agents. Think of it as a README written for the agent instead of for people. It sits at the top of your project.
The format has no required fields. You write normal Markdown with any headings you like. It started at OpenAI and is now run by the Agentic AI Foundation, part of the Linux Foundation. Its site says over 60,000 open-source projects use it.
Most coding agents read it as is:
Codex, Cursor, the GitHub Copilot coding agent, Jules, Aider, Zed, Windsurf and Devin.
Gemini CLI reads GEMINI.md by default. Add AGENTS.md to its
context.fileNamesetting and it reads that too.Claude Code reads it since version 2.1.277, with one rule that changes everything.
In a big project you can put one AGENTS.md in each folder. The agent reads the nearest one, so each part of the project gets its own rules. OpenAI’s own main repo has 88 of them.
AGENTS.md vs CLAUDE.md: the rule in the docs
Claude Code has its own file, CLAUDE.md. When both files exist, it does not merge them. It picks one.
Here is the default rule from Anthropic’s memory docs, in plain words:
Only AGENTS.md in the project: Claude reads AGENTS.md.
AGENTS.md plus a CLAUDE.md: Claude reads CLAUDE.md only. AGENTS.md is skipped.
A CLAUDE.md that imports AGENTS.md: Claude reads both, through the import.
Two details make this easy to miss. First, CLAUDE.local.md counts as a CLAUDE.md. That’s the private file you keep out of git for your own notes.
Second, your global ~/.claude/CLAUDE.md does not count. So your personal file is never the reason your project rules vanished. It’s always a CLAUDE.md inside the project, or in a folder above it.
When Claude Code loads AGENTS.md in a normal session, it prints a line saying so. When it skips the file, my test runs showed no warning at all.
I tested 7 setups
I wanted proof, not a reading of the docs. So I built a tiny test on 21 November with Claude Code 2.1.325.
Each folder held the same AGENTS.md with one line: “The project code word is MANGO.” Then I asked Claude Code, in a fresh session, for the project code word. If it read AGENTS.md, it says MANGO. If not, it says NONE.
The results:
AGENTS.md only: MANGO. Read.
AGENTS.md plus a normal CLAUDE.md: NONE. Skipped, twice in a row.
AGENTS.md plus a CLAUDE.local.md with my own notes: NONE. Skipped.
CLAUDE.md with
@AGENTS.mdat the top: MANGO. Read.CLAUDE.md as a link to AGENTS.md: MANGO. Read.
AGENTS.md plus CLAUDE.md, with the “read both” setting: MANGO. Read.
AGENTS.md plus CLAUDE.local.md, with the “read both” setting: MANGO. Read.
So the file works. It loses to any CLAUDE.md in the same folder or above it.
Why this hits people who use more than one agent
If you only use Claude Code, none of this matters. Keep your CLAUDE.md.
It hits when a project serves several agents. Here is how it goes wrong. A team writes AGENTS.md so Codex, Cursor and Claude Code all follow the same rules.
Months later, someone adds a CLAUDE.md for one Claude tip. From that day, Claude Code stops reading the shared rules. Codex and Cursor still follow them. Now your agents disagree, and nobody touched the rules file.
The CLAUDE.local.md case is worse, because it only hits one person. You add a private notes file on your laptop, and your Claude Code loses the project rules. Your teammates see nothing wrong.
Three more gaps from the docs:
Claude Code never reads AGENTS.override.md or AGENTS.local.md. Codex uses the override file. Claude does not.
Nothing inside a
.agents/folder loads as rules.Hooks are small scripts Claude Code runs at set moments. The InstructionsLoaded hook does not fire for an AGENTS.md read this way. It does fire when CLAUDE.md imports or links to the file.
How to make Claude Code read AGENTS.md: 3 ways
Pick one. I use the first for any project other people touch.
1. Import it from CLAUDE.md. Put this line at the top of CLAUDE.md:
@AGENTS.md
## Claude Code only
- Claude-specific notes go here, below the import.Claude reads AGENTS.md first, then the rest of CLAUDE.md. It also works in sessions where Claude Code can’t read AGENTS.md on its own, like older versions. It lives in the repo, so every teammate gets it.
2. Make CLAUDE.md a symlink. A symlink is a shortcut file that points to another file. Run this in the project folder:
ln -s AGENTS.md CLAUDE.mdNow both names open the same text. My tool agents-md sets this up for you. One warning: on Windows, Git can check out a symlink as a plain text file. Use the import there.
3. Change the setting. Type /config in Claude Code and set Project instructions to claude-md-and-agents-md. Claude then reads both files, CLAUDE.md first.
This setting lives in your own ~/.claude/settings.json. Claude Code ignores it in project settings. So it fixes your laptop, not your team.
What to put in AGENTS.md
Keep it short. Anthropic suggests under 200 lines for CLAUDE.md, because longer files cost context and get followed less. Codex stops adding instruction files once they reach 32 KiB in total.
GitHub studied over 2,500 AGENTS.md files. The good ones cover 6 areas: commands, testing, project structure, code style, git workflow and boundaries. “Never commit secrets” was the most common helpful rule.
Here is what earns a place:
Commands: install, test, lint and build. Exact commands, ready to copy.
Layout: where the main code lives, and what not to touch.
Style: the few rules a linter doesn’t catch.
Boundaries: what to always do, what to ask about first, what never to do.
Pull requests: title format, and checks to run before a commit.
Leave out anything only Claude Code uses, like skills and hooks. Put those below the @AGENTS.md line in CLAUDE.md.
A small template to start:
# AGENTS.md
## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint
## Layout
- src/ holds the app. scripts/ holds one-off tools.
## Boundaries
- Always: run tests before you say a task is done.
- Ask first: new dependencies, database changes.
- Never: commit .env files or secrets.Don’t want to write it by hand? Run npx @eugeniughelbur/agents-md in your project. It reads your repo, fills in what it finds and leaves clear blanks for the rest. It also links CLAUDE.md for you, and re-running it never wipes what you wrote.
Check that your agent read the file
In obsidian-second-brain, the rules live in one source. A build step writes the file each agent expects: CLAUDE.md for Claude Code, AGENTS.md for Codex and OpenCode, GEMINI.md for Gemini CLI. I explained that setup in I run my second brain on four AI CLIs.
The lesson from this test: never assume an agent read your rules. Ask it. Put one odd fact in the file, then ask for it in a fresh session:
What is the project code word from your project instructions? Reply with the word only, or NONE.It takes 10 seconds. I now run it after any change to these files. For what to keep and what to cut inside CLAUDE.md itself, read the CLAUDE.md behind a tool 3,000 developers use.
Want the ready-made version? The Vault has AI tools for paid members, each set up in 10 minutes or less.
Frequently asked questions
What is AGENTS.md?
A plain Markdown file of instructions for AI coding agents. It sits at the top of your project, like a README for the agent. Codex, Cursor, GitHub Copilot and many more read it.
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277. By default it reads AGENTS.md only when your project has no CLAUDE.md or CLAUDE.local.md.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is the shared format many agents read. CLAUDE.md is Claude Code’s own file. When both exist, Claude Code reads CLAUDE.md and skips AGENTS.md.
Should I use AGENTS.md or CLAUDE.md?
If you use more than one coding agent, write AGENTS.md and import it from CLAUDE.md with @AGENTS.md. If you only use Claude Code, CLAUDE.md alone is fine.
How do I make Claude Code read both files?
Add @AGENTS.md at the top of CLAUDE.md. Or set Project instructions to claude-md-and-agents-md in /config, which only changes your own machine.
Can I symlink CLAUDE.md to AGENTS.md?
Yes. Run ln -s AGENTS.md CLAUDE.md in the project folder. On Windows, use the import instead, since Git may check out the link as plain text.
Key takeaways
Claude Code reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md sits in the folder or above it.
In a 7-setup test, a normal CLAUDE.md or a private CLAUDE.local.md made Claude Code skip AGENTS.md with no warning.
One line,
@AGENTS.mdat the top of CLAUDE.md, makes every Claude Code session read the shared rules.The “read both” setting only works from your personal settings file, so it can’t fix a whole team.
A good AGENTS.md is short: commands, layout, style, boundaries and pull request rules.
After any change to rules files, ask the agent a question only the file can answer.
Further reading
About the author
I’m Eugeniu Ghelbur. I build AI agent systems and the tooling around them, and I write The AI Operator. I maintain obsidian-second-brain, an open-source Claude Code skill that runs an Obsidian vault as a living second brain. It’s MIT-licensed and starred by over 5,400 people on GitHub. I also maintain agents-md, the AGENTS.md generator from this post.







