Topic · A1
AGENTS.md: The Cross-Tool Standard Explained
What AGENTS.md is, which tools read it, how it compares to CLAUDE.md, and the symlink trick to make both work in the same project. Adopted by Codex CLI, Cursor, Gemini CLI, Aider, Windsurf, and more.
# AGENTS.md: The Cross-Tool Standard Explained
The biggest annoyance with AI coding agents in 2025 was that every tool wanted its own config file. Cursor read .cursorrules. Claude Code read CLAUDE.md. Aider read CONVENTIONS.md. Codex CLI read AGENTS.md. A team using two tools wrote the same conventions twice.
AGENTS.md is the convergence. As of mid-2026, it's the file the major agents agreed to read in common — Codex CLI, Cursor, Gemini CLI, Aider, Windsurf, Zed, Warp, and RooCode are documented adopters. Claude Code is the conspicuous holdout. The symlink trick fixes that.
This is the explainer: what AGENTS.md is, how it differs from CLAUDE.md, which tools actually read it, and how to use both without duplicating your conventions.
What it is, technically
AGENTS.md is a Markdown file at a project's root that AI coding agents read at session start. There's no schema, no required headers, no validation. Whatever you write, the agent reads as project-wide instruction. Common sections (community consensus, not spec):- Stack — language, framework, package manager, key libraries
- Commands — how to dev, build, test, lint
- Conventions — code style, directory layout, naming
- Constraints — what NOT to do, deny rules
CLAUDE.md. The format is interchangeable; the filename is the routing rule.
The reason it exists as a separate standard is purely social: Claude Code launched first, named its file CLAUDE.md, and as more agents arrived, nobody wanted to call their own config "the Claude file." AGENTS.md is the neutral name. The agentsmd.io reference site documents the conventions in current use.
Which tools actually read it
Verified adopters as of May 2026: | Tool | Reads AGENTS.md? | Reads CLAUDE.md? | Notes | |---|---|---|---| | Codex CLI | Yes (native) | No | The originalAGENTS.md adopter. |
| Cursor | Yes (since 2025 update) | No | Replaces .cursorrules for new projects. |
| Gemini CLI | Yes (native) | No | |
| Aider | Yes | No | Reads CONVENTIONS.md legacy; AGENTS.md takes precedence if both exist. |
| Windsurf | Yes | No | |
| Zed | Yes (assistant) | No | |
| Warp | Yes (Agent mode) | No | |
| RooCode | Yes | No | |
| Claude Code | No (issue #34235 open) | Yes | Use symlink workaround. |
Two important footnotes:
- "Reads natively" means the tool looks for the file by default. Several of these tools also let you configure a different filename — so a team running Cursor can be configured to read CLAUDE.md if you really want to. But the path of least resistance is AGENTS.md.
- Some tools merge
AGENTS.mdwith their own legacy formats (Aider'sCONVENTIONS.md, Cursor's.cursorrules). The merge order is undocumented in most cases. If you're migrating, pick one and stick to it.
The symlink workaround for Claude Code
Because Claude Code doesn't read AGENTS.md natively, the working pattern is a symlink: ``bash
# In your project root
ln -s AGENTS.md CLAUDE.md
`
Claude Code follows the symlink and reads AGENTS.md as if it were CLAUDE.md. Every other agent reads AGENTS.md directly. One file, all tools.
On Windows without symlink support, use a hardlink:
`powershell
New-Item -ItemType HardLink -Path CLAUDE.md -Target AGENTS.md
`
Or — the brute-force option — a shell script that copies AGENTS.md to CLAUDE.md as a pre-commit hook. Ugly, but it works on any filesystem.
The first request for native AGENTS.md support in Claude Code is issue #6235; the active one is issue #34235. Both are open. Anthropic has not committed to a timeline.
How AGENTS.md differs from CLAUDE.md (in practice)
Mechanically, they don't. The file format is identical. The differences are downstream:
- CLAUDE.md is Claude Code-specific. If you list "use Server Components by default" in CLAUDE.md, that rule fires in Claude Code only. Codex CLI never sees it. AGENTS.md applies the same rule across all reading tools.
- CLAUDE.md has more documented hierarchical behavior. Anthropic's memory docs specify how subdirectory CLAUDE.md files merge with the project root. AGENTS.md hierarchy is implementation-defined per tool.
- CLAUDE.md is older and has more tooling. HumanLayer's "writing-a-good-claude-md" post, the 60-line standard, and the published templates all target CLAUDE.md. AGENTS.md has fewer authored references because the standard is younger.
- CLAUDE.md is unlikely to change. AGENTS.md is still evolving — there are conversations about whether to formalize a schema, add typed sections, or define merge precedence. CLAUDE.md is whatever Anthropic says it is.
For most projects, "write AGENTS.md, symlink to CLAUDE.md" is the answer. You get cross-tool portability and Claude Code compatibility from one source of truth.
When to keep both as separate files
Three cases where the symlink is wrong:
- Tool-specific rules. If you have a rule that genuinely only applies in Claude Code ("invoke the
code-review skill when the user says X"), put it in CLAUDE.md as a non-symlinked addition. Use the symlink for the shared stack/convention layer and a separate Claude-specific file for the rest.
- Sensitive overrides. Anthropic's official skills sometimes change behavior based on CLAUDE.md contents. If you want a CLAUDE.md-only opt-in, keep them separate.
- Different audiences. If AGENTS.md is your team's public-facing convention doc (visible in the GitHub repo, read by contributors) and CLAUDE.md contains internal-only notes, separation is intentional.
In every other case: symlink.
Where this fails
1. The standard is under-specified. There is no AGENTS.md spec document with normative requirements. Different tools interpret the file differently — what works in Cursor may not work identically in Aider. Track tool changelogs.
2. Stewardship is unclear. Adoption is broad, but no single organization has clearly taken governance. We've heard talk of formal foundation stewardship; we have not verified a binding announcement. Treat any claim that "X foundation now owns AGENTS.md" as needing primary-source verification — including this paragraph if you're auditing us.
3. The Linux Foundation Agentic AI Foundation (LFAAF) angle. The Linux Foundation has hosted several agentic-AI-adjacent projects since 2025. Whether AGENTS.md formally falls under any foundation umbrella as of May 2026 is something we have not been able to confirm from a primary source. If you need this for compliance or due-diligence reasons, contact the maintainers of the major adopting tools directly. We'll update this page if we get a clear answer.
4. Symlinks break on shallow git clones in some CI configurations. If your CI does git clone --depth 1` and your symlink resolution depends on git's symlink handling, the symlink may arrive as a text file containing the target path. Fix: either avoid the symlink in CI, or use the hardlink option.
What to read next
- /topic/claude-md — the Claude Code-specific file format (interchangeable content)
- /topic/best-claude-code-skills — skills that work alongside the AGENTS.md/CLAUDE.md context layer
- /topic/skill-not-triggering — when your AGENTS.md is fine but a skill still doesn't fire
- /topic/claude-code-hooks-cookbook — the deterministic enforcement layer above text-based config
- /for/claude-code — install Claude Code
- /for/obra-superpowers — Obra's repo ships templates that work in both formats
Sources
- agentsmd.io. Community reference for AGENTS.md conventions.
- Anthropic. Claude Code issue #34235. Active feature request for native AGENTS.md support.
- Anthropic. Claude Code issue #6235. Original feature request, still open.
- Hacker News. "Can't we standardize on AGENTS.md instead of all these specific CLAUDE.md...". Community frustration with format fragmentation.
- Hacker News. "I got tired of syncing Claude/Gemini/AGENTS.md and .cursorrules". Documented sync-pain that motivates AGENTS.md adoption.
- HumanLayer. "Writing a Good CLAUDE.md". The reference for what to put in either file — content is the same; filename is the routing rule.
- Anthropic. "Memory and CLAUDE.md". The four-scope hierarchy that AGENTS.md tools imitate (with varying fidelity).
Related GitHub projects
Frequently asked
- What is AGENTS.md?
- AGENTS.md is a Markdown file at a project's root that AI coding agents read to learn the project's conventions — stack, build commands, what to avoid. It's the cross-tool successor to fragmented predecessors like `.cursorrules`, `CLAUDE.md`, and `CONVENTIONS.md`. The standard emerged in 2025 as a deliberate convergence across multiple agent tools, and is now read by Codex CLI, Cursor, Gemini CLI, Aider, Windsurf, Zed, Warp, and RooCode. ([source: agentsmd.io](https://agentsmd.io))
- Does Claude Code read AGENTS.md?
- Not natively, as of May 2026. Claude Code reads `CLAUDE.md` only. There's an [open feature request (issue #34235)](https://github.com/anthropics/claude-code/issues/34235) for native support, plus an older [issue #6235](https://github.com/anthropics/claude-code/issues/6235). The current workaround is a symlink: `ln -s AGENTS.md CLAUDE.md`. That gives every tool the same source of truth without duplication.
- Should I use AGENTS.md or CLAUDE.md?
- AGENTS.md if your team uses more than one agent tool. CLAUDE.md if you're Claude Code-only. If you're starting fresh, AGENTS.md + symlink is the safer bet — it doesn't lock you into a single vendor. If you have an existing CLAUDE.md and your team is Claude Code-only, leave it; the file format is identical, only the filename differs.
- How does AGENTS.md differ from CLAUDE.md in content?
- Format and content are the same — both are plain Markdown with sections for stack, commands, conventions, and constraints. The only difference is the filename and which tools read it. There's no schema, no required headers, no validation. Adoption of AGENTS.md is governed by community consensus, not a spec document. See the [agentsmd.io reference](https://agentsmd.io) for the conventions in current use.
- Who maintains the AGENTS.md standard?
- Originally a grassroots convention; as of 2026, the conversation about formal stewardship is active across the major adopting tools. The maintainers of the most widely-read tools (Codex CLI, Cursor, Aider, Gemini CLI) cross-reference the format in their docs, but there is no single binding spec. We're tracking the [agentsmd.io](https://agentsmd.io) site as the closest thing to a reference. If a formal foundation takes stewardship, we'll update this page.
- Can AGENTS.md be in subdirectories like CLAUDE.md?
- Yes, in tools that mirror Claude Code's hierarchical loading (notably Codex CLI and Aider). Each tool handles the merge order slightly differently. The safe assumption: top-level AGENTS.md is universally read; subdirectory AGENTS.md files are read by some tools but not all. Don't put a critical rule only in a subdirectory file if your team uses multiple agents.