CLAUDE.md vs AGENTS.md vs .cursorrules: What Goes in Each

TL;DR: AGENTS.md is the open, cross-tool standard for agent instructions; CLAUDE.md is Claude Code's own file (and falls back to AGENTS.md); .cursorrules is Cursor's legacy format, now superseded by .cursor/rules plus AGENTS.md.

AI coding agents converged on one idea - a Markdown file in the repo root that tells the agent how your project works - and then disagreed on the filename. The result is three names for nearly the same thing, and a recurring question: which file do you actually write, and what goes in it? Here is what each is, how they differ, and the setup that keeps every agent happy in 2026.

What is AGENTS.md?

AGENTS.md is the open standard. Its creators describe it as "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." It is a plain Markdown file, no frontmatter or schema, that lives in your repository root. Per the AGENTS.md specification, the format is stewarded by the Agentic AI Foundation under the Linux Foundation and grew out of collaboration between OpenAI Codex, Amp, Google's Jules, Cursor, and Factory.

The reason it matters is reach: AGENTS.md is read natively by a long list of tools - Codex, Jules, Factory, Aider, Goose, Zed, Warp, VS Code, Devin, JetBrains Junie, GitHub Copilot's coding agent, plus Cursor, Gemini CLI, and Windsurf. Write one AGENTS.md and most agents pick it up without per-tool duplication.

What is CLAUDE.md?

CLAUDE.md is Claude Code's instructions file. Claude Code reads it from three locations and merges them in order: ~/.claude/CLAUDE.md for your personal global rules that apply to every project, ./CLAUDE.md in the repo root for team-shared project rules committed to git, and CLAUDE.md files inside subdirectories for instructions scoped to one part of the codebase. That layering is the feature - global preferences, project conventions, and folder-specific notes coexist without stepping on each other.

Crucially, Claude Code also reads AGENTS.md as a fallback when no CLAUDE.md is present in a directory. So a repo that ships only AGENTS.md still works with Claude Code; CLAUDE.md is for teams that want Claude-specific layering or that already maintain one. You can also extend Claude Code with MCP servers, and the CLAUDE.md is where you document how the agent should use them.

What is .cursorrules?

.cursorrules is Cursor's original rules file - a single Markdown-style file at the repo root. It still works, but it is legacy. Cursor moved to a .cursor/rules/ directory of MDC files, which add YAML frontmatter for glob-based scoping so a rule can attach only to the files it matches. Cursor now also reads AGENTS.md. If your rules quietly stop applying after the migration, our guide to Cursor rules not loading covers the usual causes.

For new projects, the Cursor-recommended pattern is to keep an AGENTS.md at the root for cross-tool instructions and use .cursor/rules/ only for scoped, Cursor-specific overrides where its auto-attach behaviour earns its keep.

How do CLAUDE.md, AGENTS.md, and .cursorrules differ?

The mental model that resolves the confusion: README.md is for humans, AGENTS.md is for coding agents, and tool-specific files like CLAUDE.md or a .cursor/rules/ directory are compatibility or power-user layers on top. A CLAUDE.md that simply points to AGENTS.md is a common bridge when you want both.

Which file should you use in 2026?

If you adopt one file, adopt AGENTS.md - it is the lowest-effort way to be understood by the most agents, including Cursor versus Claude Code and everything in between. Add a CLAUDE.md only if your team wants Claude Code's global-plus-project-plus-subfolder layering, and add .cursor/rules/ only for scoped overrides Cursor handles better than a flat file. Maintaining three near-identical files by hand is how they drift out of sync; pick AGENTS.md as the source of truth and let the others reference it.

What goes in a good agent instructions file?

• Build and run commands, so the agent does not guess how to compile or start the project.
• Test commands and the expectation that changes pass them before completion.
• Project structure and where key code lives, so the agent edits the right files.
• Conventions - naming, formatting, libraries to prefer or avoid - stated as rules, not prose.
• Explicit do-nots, such as files never to touch or commands never to run.

Keep it specific and current. A stale instructions file that describes an old build step is worse than none, because the agent will trust it. Treat the file like code: review it when behaviour changes.

How do you set this up in three steps?

1. Create an AGENTS.md in the repo root with build, test, structure, conventions, and do-nots.
2. Add a CLAUDE.md only if you want Claude Code's three-level layering, or symlink it to AGENTS.md.
3. Add .cursor/rules/ files only for scoped, Cursor-specific overrides, and retire any old .cursorrules.

FAQ

Do I need all three files?

No. AGENTS.md alone covers most agents, including Claude Code via its fallback. Add CLAUDE.md or .cursor/rules only for tool-specific layering you actually need.

Does Claude Code read AGENTS.md?

Yes. Claude Code reads AGENTS.md as a fallback when a directory has no CLAUDE.md, so a repo shipping only AGENTS.md still works with it.

Is .cursorrules deprecated?

It still works but is legacy. Cursor recommends .cursor/rules/ MDC files for scoped rules and AGENTS.md for cross-tool instructions. New projects should skip .cursorrules.

What is the difference between AGENTS.md and README.md?

README.md targets human contributors; AGENTS.md targets coding agents with build steps, tests, and conventions that would clutter a README. They complement each other.

Can I symlink CLAUDE.md to AGENTS.md?

Yes, and it is a common pattern. A symlink keeps a single source of truth while satisfying tools that look for a specific filename.