Cursor Rules vs CLAUDE.md vs AGENTS.md: I Ran One Config Through All Three (2026)

Cursor Rules vs CLAUDE.md vs AGENTS.md: I Ran One Config Through All Three (2026)

The cursor rules vs claude md question has a trap built into it: they aren't two options you pick between. They're two files, read by two different tools, that happen to do the same job. Drop a CLAUDE.md into a Cursor project and Cursor ignores it. Drop an AGENTS.md into Claude Code and nothing happens either. That surprised us too. AGENTS.md now sits in 60,000+ repos as the open standard, stewarded by the Agentic AI Foundation under the Linux Foundation, yet Claude Code still won't read it on its own. Here's the compatibility map, tested on our repo.

Key Takeaways

• Cursor reads .cursor/rules/*.mdc and AGENTS.md, not CLAUDE.md.
• Claude Code reads CLAUDE.md only, not AGENTS.md natively.
• To share one file: symlink AGENTS.md to CLAUDE.md, or import it with @AGENTS.md.
• Standardize on AGENTS.md (open standard, 60k+ repos), then add tool-specific overrides.

Which Config Format Should You Use? The 30-Second Decision

Pick your format by team shape, not by hype. If you run one tool, use its native file. If you run two or more, adopt AGENTS.md as the source of truth and add per-tool overrides only where a tool needs something the others don't. That single rule settles most of the confusion.

Still deciding which assistant to run before you worry about its config? Start with our guide to choosing which AI coding agent to run, then come back for the file setup.

The decision axis that matters is portability. A .cursor/rules file is powerful inside Cursor and useless everywhere else. An AGENTS.md travels. So unless you're locked to one tool forever, the tool-agnostic file is the safer bet.

What Each Format Actually Is (in 30 Seconds Each)

These three files all do one thing: hand an AI coding tool your project's rules, conventions, and gotchas before it writes a line. The difference is who reads them and how they scope. Here's the short version. The deep how-to for each lives in its own guide.

Cursor Rules are .mdc files inside .cursor/rules/. Cursor supports four rule types (always-on, agent-requested, glob-scoped, and manual @-mention), so you can attach a rule to just your *.tsx files or just your migrations. For the frontmatter, globs, and token budget, read our guide on how to actually write .cursor/rules files.

CLAUDE.md is Claude Code's memory file. Claude walks up the directory tree from your working folder and concatenates every CLAUDE.md it finds. It's plain Markdown, no frontmatter required. For structure and the rules that keep Claude from ignoring it, see what makes a CLAUDE.md Claude won't ignore.

AGENTS.md is the open standard. One plain-Markdown file at your repo root, read natively by Cursor, Codex, Copilot, Windsurf, Zed, Aider, and dozens more. It's stewarded by the Agentic AI Foundation and already lives in 60,000+ projects.

Here's the reframe worth remembering: AGENTS.md, CLAUDE.md, and .cursor/rules aren't competitors, they're the same instruction, addressed to different readers.

Cursor Rules vs CLAUDE.md vs AGENTS.md: The Master Comparison

The fastest way to see the difference is side by side. The decisive column is portability: which tools read the file without extra setup. AGENTS.md wins on reach, Cursor Rules win on scoping precision, and CLAUDE.md wins for anyone all-in on Claude Code.

Notice the .cursorrules row. That single root file still works in Cursor, but it dropped out of the docs, so treat it as legacy. New projects should use .cursor/rules/*.mdc or AGENTS.md instead.

Which Tool Reads Which File? (Bust the AGENTS.md Myth)

Here's the fact half the internet gets wrong: Claude Code does not read AGENTS.md natively, and Cursor does not read CLAUDE.md. Cursor reads .cursor/rules/*.mdc plus AGENTS.md. Claude Code reads CLAUDE.md and nothing else. There's no automatic fallback in either direction, which trips up teams who assume one standard file covers everything.

This gets asked constantly, so let's be blunt. Dropping an AGENTS.md into a Claude Code project does nothing on its own. Claude Code reads CLAUDE.md and only CLAUDE.md. Anthropic's Claude Code memory docs describe the file-loading behavior with no mention of AGENTS.md, the AGENTS.md spec lists Cursor and Codex among native readers but not Claude Code, Cursor's own rules docs confirm the split, and the Claude Code GitHub issues are full of developers hitting exactly this wall.

So does Cursor read claude.md? No. Does Claude Code read agents.md? Not without help. That "help" is the whole reason this post exists, and it's two short commands you'll see next.

How Precedence & Nesting Work, Side by Side

Each tool resolves conflicts differently, and getting this wrong is the top source of "why is my rule being ignored?" confusion. Cursor merges rules by source priority. Claude Code concatenates by directory depth. AGENTS.md picks the nearest file in the tree. Good claude md management starts with knowing which mental model you're in.

In our setup, the practical upshot is simple: put broad rules high (repo root) and specific rules low (inside a package folder). For both Claude Code and AGENTS.md, the file closest to where you're working takes priority, so a packages/api/AGENTS.md overrides the root one for anything inside that folder. Cursor is the odd one out, resolving by source tier rather than by folder depth.

The file format only controls where instructions live. Our prompt engineering for coding guide covers what to put in those instructions and how to make coding requests testable.

We Ran One Config Across Cursor + Claude Code, Here's What Each Tool Actually Loaded

We tested this on a live Techsy client repo (a Next.js 15 backend) using Cursor 3.7 (June 17, 2026 build) and Claude Code v2.1.x (early July 2026). One AGENTS.md, three sharing setups, same prompt opened in both tools. Here's exactly what each one pulled in.

We started with a minimal file:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

Setup 1: AGENTS.md alone. Cursor picked it up immediately. The file showed in its context and it correctly refused to suggest npm install. Claude Code did nothing with it. Running /memory in Claude Code listed zero project memory files: no CLAUDE.md found, and AGENTS.md wasn't even acknowledged. Confirmed: no native fallback.

Setup 2: symlink. We pointed CLAUDE.md at the same file:

ln -s AGENTS.md CLAUDE.md

Now /memory in Claude Code listed ./CLAUDE.md as a Project memory, and the loaded content was our AGENTS.md byte-for-byte. Cursor still read AGENTS.md directly. One physical file, both tools happy. On Windows this needs Admin or Developer Mode enabled, or ln/mklink fails silently.

Setup 3: @import. We deleted the symlink and instead put a single line at the very top of a real CLAUDE.md:

@AGENTS.md

/memory then showed CLAUDE.md as the loaded file with AGENTS.md pulled in as an imported reference beneath it. This is the path Anthropic actually documents, and it needs no special OS permissions.

The verdict from our test: the symlink makes Claude Code read AGENTS.md byte-for-byte; the @AGENTS.md import is the Windows-safe version Anthropic actually recommends. Both give you one source of truth. Pick the symlink on macOS/Linux for zero indirection, or the import line if anyone on the team is on Windows.

Migrating Between Formats: .cursorrules → .cursor/rules → AGENTS.md

Most teams land here with a legacy .cursorrules file and want out of the single-file trap. The migration is short in every direction, and the moves are copy-paste. The one gotcha that bites people: a .md file inside .cursor/rules without frontmatter is silently ignored, so it has to be .mdc.

To modernize an old .cursorrules, you've got two clean paths:

• To .cursor/rules/*.mdc: create .cursor/rules/general.mdc, add frontmatter (alwaysApply: true for a global rule), and paste your old content below it. Delete .cursorrules once verified.
• To AGENTS.md (recommended for multi-tool teams): to convert cursorrules to agents.md, copy the body of .cursorrules into a new AGENTS.md at your repo root. No frontmatter needed; it's plain Markdown. Then add the symlink or @AGENTS.md import so Claude Code reads it too.

If you're staying inside Cursor and want to squeeze more out of it, our guide on getting more out of Cursor day to day covers rule scoping in practice.

Going the other way (AGENTS.md → CLAUDE.md) is just the symlink or import from the last section. There's no lossy conversion because all three are Markdown under the hood.

Where Do SKILL.md and Copilot Instructions Fit?

Two more formats show up in this conversation, and skills md is a breakout search right now, so it's worth a quick placement. Neither replaces the three main files; they sit alongside them.

SKILL.md is Anthropic's Skills format: task-specific instructions bundled in .claude/skills/*/SKILL.md that Claude loads on demand when a task matches, rather than always-on like CLAUDE.md. Think of it as a specialized playbook Claude reaches for, not a project-wide memory file. The scope is still evolving, so don't over-invest yet. For how it fits a real workflow, see where CLAUDE.md fits in a real Claude Code workflow.

Copilot instructions live in .github/copilot-instructions.md for GitHub Copilot. Good news: Copilot also reads AGENTS.md, so if you've standardized on the open standard, Copilot is already covered without a separate file.

Which Should You Use? (By Team Shape)

Match the format to how your team actually works:

• Solo Claude Code user: just use CLAUDE.md. No reason to add AGENTS.md unless you plan to bring in Cursor or Codex later.
• Solo Cursor user: .cursor/rules/*.mdc for the glob scoping, or a single AGENTS.md if you want portability from day one.
• Mixed-tool team: one AGENTS.md as the source of truth, symlinked or imported into CLAUDE.md. Add a small .cursor/rules file only for Cursor-specific behavior.
• Monorepo: AGENTS.md at the root plus nested files per package, so each subproject describes itself and the nearest file wins.

At Techsy we standardize AI-coding config across mixed-tool teams, usually one AGENTS.md as the source of truth with per-tool overrides where a tool needs them. If your team is juggling three config files by hand, get a free consultation and we'll map it out.

One last pointer: this post compares the config files. If you're actually trying to decide between the tools themselves, read comparing the assistants themselves, not their config.

Frequently Asked Questions

Does Cursor read CLAUDE.md?

No. Cursor reads .cursor/rules/*.mdc and AGENTS.md natively, but CLAUDE.md is never mentioned in Cursor's docs and isn't loaded. If you're on Cursor and want to share config with Claude Code users, put your rules in AGENTS.md (which Cursor does read) rather than CLAUDE.md.

Does Claude Code read AGENTS.md?

Not natively. Claude Code reads CLAUDE.md only, with no automatic fallback to AGENTS.md. To make it work, either symlink the files (ln -s AGENTS.md CLAUDE.md) so Claude reads AGENTS.md byte-for-byte, or add @AGENTS.md on line 1 of a CLAUDE.md to import it. The import is Anthropic's recommended, Windows-safe option.

Can I just use one file for all three tools?

Yes. Adopt AGENTS.md as your single source of truth, and Cursor and Codex read it directly. For Claude Code, add one bridge: either symlink AGENTS.md to CLAUDE.md, or drop @AGENTS.md at the top of a CLAUDE.md. You maintain one file, and every tool loads the same rules. That's the whole share-one-config recipe.

Is .cursorrules deprecated?

Soft-deprecated. The single-file .cursorrules at your repo root still works in Cursor, but it's no longer in the official docs, which is the usual signal a format is on the way out. New projects should use .cursor/rules/*.mdc for scoped rules or AGENTS.md for portability.

How do I convert .cursorrules to AGENTS.md?

Copy the body of your .cursorrules file into a new AGENTS.md at your repo root. It's plain Markdown, so no frontmatter or reformatting is needed. Then add a symlink or @AGENTS.md import so Claude Code reads it too, and delete the old .cursorrules once you've confirmed Cursor picks up the new file.

What's the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is Claude Code's proprietary memory file, read only by Claude Code. AGENTS.md is an open standard read by Cursor, Codex, Copilot, and 20+ other tools, but not by Claude Code natively. Same Markdown format, same job. The difference is reach. AGENTS.md travels across tools; CLAUDE.md stays inside Claude Code.

Which format should a team using multiple AI tools standardize on?

AGENTS.md. It's the open standard, read natively by most tools and already in 60,000+ repos. Standardize your shared rules there, bridge it into Claude Code with a symlink or import, and add small tool-specific files (like .cursor/rules) only where one tool needs behavior the others don't.

How does precedence work when I have nested config files?

For both Claude Code and AGENTS.md, the file closest to your working directory wins, so a rule in packages/api/AGENTS.md overrides the repo-root file for anything inside that folder. Cursor is different: it merges Team, Project, and User rules by source tier rather than folder depth, with earlier sources winning conflicts.

Where does SKILL.md fit in?

SKILL.md is Anthropic's emerging Skills format: task-specific instructions in .claude/skills/*/SKILL.md that Claude loads on demand when a task matches, rather than always-on like CLAUDE.md. It complements CLAUDE.md rather than replacing it. The scope is still evolving in 2026, so treat it as a specialized add-on, not a fourth file every project needs.