CLAUDE.md vs AGENTS.md: The Cross-Tool Standard for AI Coding Instructions (2026)

You finally wrote a clean set of project instructions for your AI coding agent. Then a teammate opens the same repo in Codex, another in Cursor, and your carefully tuned CLAUDE.md is invisible to both. Now you're maintaining three files that drift apart by Friday.

As of June 2026, two file names dominate this problem: CLAUDE.md and AGENTS.md. They look interchangeable. They are not.

CLAUDE.md is Claude Code's project-instructions file — a markdown file Anthropic's CLI reads at the start of every session, with its own features like @imports, CLAUDE.local.md, and a managed-policy hierarchy. AGENTS.md is an open, tool-agnostic standard — plain markdown that 20+ coding agents (Codex, Cursor, Aider, Gemini CLI, and more) read as their default instructions file. One is a product feature; the other is a cross-tool convention.

The practical question isn't "which is better." It's "which does my tool actually read, and how do I avoid maintaining the same rules twice." This guide answers both.

⚖️ CLAUDE.md vs AGENTS.md: the core differences

Both files do the same job — hand persistent project context to an AI agent so you stop re-explaining your build commands and conventions every session. The difference is scope of who reads them and what features they support.

The headline: AGENTS.md is the portable layer; CLAUDE.md is the Claude-specific layer. They're not competitors so much as different altitudes.

🔌 Which AI coding tools read which file?

This is the table people actually need. An instructions file is worthless if your agent doesn't load it.

The pattern is stark: Claude Code is the one major tool that reads its own file by default, while almost everything else converged on AGENTS.md. That single fact drives every setup decision below.

AGENTS.md grew out of a cross-vendor effort (OpenAI, Google, Cursor, Factory, Sourcegraph, and others) and is now stewarded by the Agentic AI Foundation under the Linux Foundation. That's why adoption is broad: it's nobody's proprietary format.

🤔 Does Claude Code read AGENTS.md?

No — and this trips up a lot of teams, so it's worth being precise.

As of June 2026, Claude Code reads CLAUDE.md, not AGENTS.md. Anthropic's own documentation states it plainly: "Claude Code reads CLAUDE.md, not AGENTS.md." If your repository contains only an AGENTS.md, Claude Code starts with zero project instructions — silently. No warning, no error, just an agent that doesn't know your conventions.

You may see the agents.md site list "Claude Code" among supported tools. That's true only through the import convention below, not native reading. Don't rely on Claude Code picking up a bare AGENTS.md.

The official fix is a one-line import:

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Claude Code loads the imported AGENTS.md at session start, then appends any Claude-specific instructions below it. One shared source of truth, one thin Claude layer.

🌳 One file or two? A decision tree

Don't add files for symmetry. Add the minimum that gets every tool your team uses to load the same rules.

• Only ever use Claude Code? → Just CLAUDE.md. Skip AGENTS.md entirely.
• Only use Codex / Cursor / Aider / Gemini CLI (no Claude Code)? → Just AGENTS.md. You're done.
• Use Claude Code and at least one other tool? → AGENTS.md as the source of truth + a CLAUDE.md that imports it.
• Big team, mixed tools, monorepo? → Root AGENTS.md + importing CLAUDE.md, plus per-package AGENTS.md files where subprojects differ.

The rule of thumb: AGENTS.md is your default unless Claude Code is the only tool in play. Because AGENTS.md is read by the widest set of agents, starting there means the fewest files to maintain as your toolchain changes.

🔗 How to keep one source of truth across agents

Two supported ways to make Claude Code and everything else read identical instructions.

Option A — Import (recommended). Put your real content in AGENTS.md and make CLAUDE.md a thin wrapper:

# CLAUDE.md
@AGENTS.md

## Claude-specific notes
- Prefer `rg` over `grep`.
- Run `make lint` before committing.

Every other tool reads AGENTS.md directly; Claude Code reads CLAUDE.md, which pulls in AGENTS.md plus its extras. Edit one file, both stay in sync.

Option B — Symlink. If you don't need any Claude-only lines:

ln -s AGENTS.md CLAUDE.md

Both names now point at the same bytes. The catch: you can't add Claude-specific content (it's literally the same file), and on Windows a symlink needs Administrator privileges or Developer Mode — so prefer the @AGENTS.md import there.

Migrating an existing repo? Claude Code's /init command reads an existing AGENTS.md (and .cursorrules, .devin/rules/, .windsurfrules) and folds the relevant parts into the CLAUDE.md it generates. Good for a one-time consolidation.

✍️ Best practices for writing instruction files

The file format barely matters; what you put in it does. These apply to both CLAUDE.md and AGENTS.md.

• Keep it under ~200 lines. Claude Code's docs are explicit: longer files consume more context and reduce adherence. Every line competes with your actual task for the model's attention.
• Be concrete enough to verify. "Use 2-space indentation" beats "format code properly." "Run npm test before committing" beats "test your changes."
• Lead with commands and layout. Build, test, and run commands; where things live (API handlers in src/api/handlers/); naming conventions. That's the high-value core.
• Don't contradict yourself. If two rules conflict, the agent picks one arbitrarily. Review periodically and delete stale entries.
• Push procedures elsewhere. A multi-step workflow or a rule that only matters for one folder belongs in a path-scoped rule or a skill, not the always-loaded root file. fundesk's context engineering guide covers this budget tradeoff in depth.
• Remember it's guidance, not enforcement. Instruction files shape behavior; they don't guarantee it. For hard guarantees (block a command, enforce a check), use a tool-level hook, not a markdown rule.

For a deeper treatment of the Claude-specific side — CLAUDE.local.md, managed policy, and the load hierarchy — see fundesk's CLAUDE.md standard guide.

🛡️ Security: your instructions file is a prompt-injection surface

Here's the part most comparisons skip. An AGENTS.md or CLAUDE.md is instructions an agent will follow with your permissions. That makes it a target.

If you accept a pull request that edits AGENTS.md, you may be merging new directives into every teammate's agent — "always run this setup script," "fetch config from this URL." A malicious or careless change becomes an instruction your tools execute. The risk compounds in monorepos where a nested AGENTS.md closer to the edited file wins over the root.

Practical guardrails:

• Review instruction-file changes like code. A diff to AGENTS.md deserves the same scrutiny as a diff to a deploy script — more, arguably, because it's invisible at runtime.
• Never put secrets in either file. They load into context and get sent to the model every session.
• Watch nested files in monorepos. The closest file wins; an attacker only needs to drop one near the code you're editing.
• Keep enforcement out of markdown. Anything that must hold (deny a command, require a check) belongs in a hook or managed setting, which runs regardless of what the agent decides.

The mental model: a CLAUDE.md instruction is delivered as a message to the model, not as enforced configuration. It's persuasive, not binding — for both you and an attacker.

❓ Frequently Asked Questions

Does Claude Code read AGENTS.md?
No. As of June 2026, Claude Code reads CLAUDE.md, not AGENTS.md. A repo with only AGENTS.md gives Claude Code zero project instructions. Add a CLAUDE.md containing @AGENTS.md to bridge them.

What is the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is Claude Code's file and supports Claude-only features (@imports, CLAUDE.local.md, managed policy). AGENTS.md is an open standard read by 20+ agents. CLAUDE.md serves one tool; AGENTS.md is the shared baseline across many.

Should I use both CLAUDE.md and AGENTS.md?
Only if your team uses more than one AI coding tool. Then keep AGENTS.md as the source of truth and add a thin CLAUDE.md that imports it. A single-tool repo needs only the one file that tool reads.

Which AI coding tools support AGENTS.md?
Over 20, including OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Google Jules, Aider, Zed, VS Code, Warp, Devin, Windsurf, and Factory. More than 60,000 open-source repos ship one.

Which file wins when both exist?
For AGENTS.md, the file closest to the edited file wins, and an explicit chat prompt overrides everything. For CLAUDE.md, files concatenate from repo root down to your working directory, so the nearest file is read last and effectively takes precedence.

🚀 What's Next

• 🔗 Set up the import pattern today — move your real rules into AGENTS.md, add a one-line @AGENTS.md CLAUDE.md, and delete the duplicate.
• 📏 Trim to 200 lines — audit your current file; move folder-specific rules into path-scoped rules.
• 🧪 Test what loads — open the repo in each tool you use and confirm the agent actually knows your build command.
• 🔒 Add instruction files to code review — treat AGENTS.md diffs as security-relevant.
• 📚 Go deeper on context — read fundesk's context engineering techniques to spend your context budget well.

Related reading: The CLAUDE.md Standard · Claude Code vs Codex vs Gemini CLI vs OpenCode · How to Write Specs for AI Coding Agents

Juggling several AI coding tools and want them to behave consistently? The patterns above are the foundation. For the full workflow — prompt patterns, regression safeguards, and the habits that keep AI-assisted code clean — grab fundesk's AI-Assisted Engineering Playbook.