AGENTS.md vs CLAUDE.md vs .cursorrules: what Cursor actually reads now (and in what order)

Cursor has accumulated four different places to put project rules, and most explanations you'll find online describe a version of the app that no longer exists. I re-checked Cursor's official docs today (2026-08-11) before writing this — every claim below has a quote or a directly verifiable statement behind it.

The four file kinds, in one table

File	Status	When it applies
.cursor/rules/*.mdc	Current, primary mechanism	Depends on rule type (always / intelligent / glob / manual)
AGENTS.md	Current, plain-markdown alternative — now with nested subdirectory support	When working in that directory tree
CLAUDE.md	Read by Cursor for Claude Code compatibility	Always, every conversation
.cursorrules	Legacy, will be deprecated	Always (old behavior) — migrate off it

Now the details, because the details are where the surprises are.

1. .cursor/rules/*.mdc — the primary mechanism

Project rules live in .cursor/rules/ as .mdc files with frontmatter that controls activation. The two failure modes the official FAQ calls out are worth repeating, because they cover most "my rule never fires" reports:

Check the rule type. For Apply Intelligently, ensure a description is defined. For Apply to Specific Files, ensure the file pattern matches referenced files.

In other words: an "intelligent" rule with no description has nothing for the agent to decide with, and a glob rule only enters context when a matching file does.

2. AGENTS.md — now nested

AGENTS.md is the cross-tool plain-markdown format, and Cursor's docs recently added something genuinely useful — nested support:

Nested AGENTS.md support in subdirectories is now available. You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.

And the merge semantics:

Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence.

So frontend/AGENTS.md wins over the root AGENTS.md where they conflict, while both still apply. If you've been simulating per-directory rules with glob-scoped .mdc files just to scope instructions, a nested AGENTS.md is now the simpler way to do it.

3. CLAUDE.md — Cursor reads it, and reads it unconditionally

This is the one most people don't know. From the official help page:

Cursor reads CLAUDE.md files the same way it reads AGENTS.md. Place a CLAUDE.md file in your project root and Cursor picks it up automatically.

And the part that matters for anyone running both tools:

CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply frontmatter setting.

Read that second quote carefully. It means Claude-specific instructions leak into your Cursor sessions. If your CLAUDE.md says "always run pnpm test before committing" because that's your Claude Code workflow, Cursor's agent will absorb that instruction too — always, with no way to scope it. The docs are explicit that conditional behavior is not available for this file: if you need conditional rules, that's what .cursor/rules/ is for.

4. .cursorrules — formally legacy

No ambiguity left here:

The .cursorrules file in your project root is legacy and will be deprecated.

The documented migration is four steps: create a new rule via the command palette ("New Cursor Rule"), copy your .cursorrules content in, set the rule type to Always Apply (that matches the old behavior), and delete the .cursorrules file. Five minutes, and you stop depending on a file with a removal date.

Precedence: who wins when rules conflict

For teams, the docs give an explicit order:

Precedence: Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts.

So organization-level Team Rules beat your repo's rules, which beat your personal User Rules. Everything is merged — precedence only matters where guidance actually conflicts. Within AGENTS.md files, the separate rule applies: more specific (deeper) files win over parents.

What I'd actually do with this

Single-tool repo (Cursor only): use .cursor/rules/ for anything conditional, plus one root AGENTS.md for the always-true project facts. Skip CLAUDE.md entirely — it buys you nothing and its unconditional loading is a blunt instrument.

Cursor + Claude Code repo: you have two workable shapes.

• One file: a single root CLAUDE.md. Claude Code reads it natively, Cursor picks it up automatically. Fine for small projects where both tools should behave identically.
• Split: AGENTS.md as the shared base (project facts, conventions), CLAUDE.md for genuinely Claude-specific workflow — but remember the leak: Cursor will read the Claude file too. Keep anything that would misdirect Cursor's agent out of CLAUDE.md, or accept that both agents follow it.

Anything still on .cursorrules: migrate now, on the official four-step path, before deprecation makes it urgent.

The meta-lesson from re-checking the docs: the answer to "what file does Cursor read" keeps changing under people's feet — .cursorrules went from standard to legacy, and CLAUDE.md support arrived without much fanfare. When behavior seems wrong, read the current docs before adding another rules file — the fix is usually that the mechanism changed under you, not that your rule text is bad.

---

I maintain Rulestack — tested rule packs for Cursor, Claude Code, and Codex, kept in sync with changes like the ones above.

I post daily notes on AI coding agent configuration on Bluesky: @ai-shop.bsky.social