CLAUDE.md vs AGENTS.md: One Memory for Every Coding Agent

Use more than one AI coding agent and you end up writing the same instructions three times. A CLAUDE.md for Claude Code, a rules file for Cursor, an AGENTS.md for Codex. Three files saying "run composer test before you commit", slowly drifting apart until each agent follows a slightly different version of your project.

It doesn't have to be like that. The short answer:

• Write one AGENTS.md. It's the shared format most coding agents read, and Claude Code reads it too: since v2.1.277 it loads AGENTS.md whenever your repository has no CLAUDE.md.
• Need Claude-specific rules? Keep a small CLAUDE.md that starts with @AGENTS.md and adds only what's Claude-only.
• Keep it short. Anthropic recommends under 200 lines per file, and a 2026 study found context files often lower agent success rates when they're stuffed with things the agent could read from the code itself.
• Don't confuse instructions with memory. What you write and what agents learn are two different layers, and the second one is where things really fragment across tools.

Let's go through it properly.

Which file does each coding agent read?

Tool	Reads	Notes
Claude Code	CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, .claude/rules/	Reads AGENTS.md when there's no CLAUDE.md in the project (v2.1.277+)
Cursor	.cursor/rules/*.mdc, AGENTS.md	Legacy .cursorrules still works but is deprecated
Codex	AGENTS.md	Where the format started
Others (Gemini CLI, Copilot, Zed, Aider…)	AGENTS.md, often via a setting	Support levels vary, so check the tool

AGENTS.md started at OpenAI and is now stewarded by the Agentic AI Foundation under the Linux Foundation, next to MCP. Nested files are allowed: put an AGENTS.md in a subfolder and it applies to that part of the codebase.

One detail trips people up with Claude Code: any CLAUDE.md or CLAUDE.local.md in your project stops it from reading AGENTS.md by default. Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md therefore silently hides your shared instructions. You can change that with the Project instructions setting in /config (claude-md-and-agents-md reads both), or just import the file.

The setup I'd recommend: one AGENTS.md, one thin CLAUDE.md

Put everything every agent should know in AGENTS.md:

# My App

## Commands
- Install: `composer install && npm ci`
- Test: `composer test` (run before every commit)
- Dev server: `symfony serve --port=$PORT`

## Conventions
- Controllers stay thin; logic lives in services under `src/Service/`
- Database changes always get a Doctrine migration, never a manual schema edit
- Money is stored in cents as integers

## Gotchas
- `bin/console cache:clear` after changing anything in `config/packages/`

Then, only if you need it, a CLAUDE.md next to it:

@AGENTS.md

## Claude Code
Use plan mode for anything under `src/Billing/`.

The @AGENTS.md import pulls the shared file in, so Claude Code never reads it twice and you keep a single source of truth. If you don't need anything Claude-specific, ln -s AGENTS.md CLAUDE.md works too. Skip the symlink if anyone on the project uses Windows, where symlinks need extra setup. Run /context in your next session to check that the file shows up under memory files.

What actually belongs in it (the research is blunt)

In February 2026 researchers from ETH Zurich and LogicStar.ai published Evaluating AGENTS.md. They tested coding agents on 138 real tasks with no context file, an LLM-generated one and a human-written one. Their finding: context files tended to reduce task success compared to no file at all, while raising inference cost by over 20%. Agents did follow the instructions, but that meant more exploring and more requirements to satisfy. The authors' advice is to describe only minimal requirements.

That lines up with what Anthropic says in its memory docs. Aim for under 200 lines per file, and write instructions concrete enough to check:

• "Use 2-space indentation" instead of "format code properly"
• "Run npm test before committing" instead of "test your changes"
• "API handlers live in src/api/handlers/" instead of "keep files organized"

So what earns a line? The things an agent can't work out by reading your code:

• Commands with the exact flags your project needs
• Conventions that differ from the defaults, like "money in cents" or "no ORM in this module"
• Gotchas, the things that bit someone once
• Why behind a rule, when the rule looks odd without it

And what doesn't? Directory trees, dependency lists and architecture overviews. The agent reads those from the code in seconds, and every extra line costs context in every session. A good trigger for adding a line comes straight from Anthropic's docs: add it when the agent makes the same mistake twice.

Rules that only matter for part of the codebase don't belong in the main file at all. Use path-scoped rules in .claude/rules/ for Claude Code and rules with globs in .cursor/rules/ for Cursor, so they only load when an agent works on matching files. Splitting a long file into @imports keeps it tidy, but it doesn't save context, because imported files load at startup too.

Instructions are not memory

Everything above is the layer you write. There's a second layer: what agents learn while they work.

Claude Code has auto memory for this. It writes notes about your preferences, your corrections and project context into ~/.claude/projects/<project>/memory/, with a MEMORY.md index of which the first 200 lines are loaded into every session. It's shared across all worktrees of a repository, but it's machine-local, and it's Claude's alone. Other engines keep their own memories in their own places, like the "Gemini Added Memories" in ~/.gemini/GEMINI.md.

That's the real fragmentation. Your instructions can be one shared file. Your agents' learnings end up in silos: what a Claude Code session learned on Monday is invisible to a Cursor agent on Tuesday.

How I gave every engine the same memory

This is one of the problems I built into Agent Office, the 3D office I run my coding agents from. Instead of each engine keeping its own notes, the office keeps one memory for the whole team, in plain Markdown using the Open Knowledge Format:

Notebook	Read by
Office knowledge	Every engineer: how I like things in every project
Room notebook	Everyone working on that project
Own notes	That engineer only

Entries are typed (decision, convention, gotcha, how-to and a few more), and agents don't write to the shared notebooks directly. They propose what they learned, and a librarian agent called Marrit files it. She merges proposals into existing entries, turns down noise like progress reports or secrets, and checks claims about the code with a quick read before they stick.

To keep it one memory, the engines' own memories are taken over in one direction. Claude Code's auto memory is switched off in the office's sessions, and what Claude, Cursor or Gemini remember on their own elsewhere is pulled into the right notebook as a proposal. Every engineer starts with the index of everything the office knows, regardless of which engine they run on.

Frequently asked questions

Does Claude Code read AGENTS.md?

Yes, since v2.1.277, as long as your project has no CLAUDE.md or CLAUDE.local.md. With a CLAUDE.md, import the shared file with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config to read both.

Should I commit CLAUDE.md and AGENTS.md to git?

Yes, they're team instructions and belong in version control. Personal preferences go in CLAUDE.local.md, which you add to your .gitignore.

How long should CLAUDE.md or AGENTS.md be?

Short. Anthropic recommends under 200 lines per CLAUDE.md, and Claude Code warns you at startup when a file goes over the recommended length. If it's growing, move part-specific rules into path-scoped rules instead.

Do instructions survive /compact?

The project-root CLAUDE.md does: Claude Code re-reads it from disk after compaction. Instructions you only gave in the chat don't, which is the best argument for writing them down.

What's the difference between CLAUDE.md and auto memory?

You write CLAUDE.md: rules and conventions. Claude writes auto memory: learnings from your corrections and preferences. Both load at the start of every session.

Conclusion: Write the Rules Once

The instruction file war is mostly over. AGENTS.md is the shared format, Claude Code reads it, and a two-line CLAUDE.md covers the rest.

The harder part is discipline. Keep the rules short enough that an agent, or a human, actually reads them. Write down only what the code can't tell you. And treat what your agents learn as something to curate, not something to collect. More context isn't better context. Better context is.