CLAUDE.md vs .cursor/rules: which one wins

What these two files actually are

Both files do the same broad job: they are standing instructions you write once so you do not have to repeat yourself in every chat. “Use tabs, not spaces.” “Never touch the generated folder.” “Validate input before it reaches the database.” The difference is which program picks them up.

• .cursor/rules is Cursor’s own rules system — a folder in your repository holding one or more rule files, each of which can be scoped so it only applies to certain files.
• CLAUDE.md is Claude Code’s instruction file — a plain markdown file that Claude Code loads as memory.

People assume these two fight each other because both are “the rules file,” and both are sitting in the same repository. They are not symmetrical, though, and that asymmetry is the whole answer.

Who reads what

Precedence, where it genuinely exists

Inside Cursor’s rules system, the order is documented: Team Rules → Project Rules → User Rules. All applicable rules are merged, and earlier sources take precedence when guidance conflicts. So a team rule beats your personal preference, which is the sane way round.

Two related details that surprise people. First, Cursor identifies rules by their full file path, not by filename — two rules with the same name in different folders both apply if their conditions match, and neither overrides the other. Second, AGENTS.md files nest: instructions from a nested AGENTS.md are combined with those from parent directories, with the more specific ones taking precedence.

On the Claude Code side, the model is concatenation, not overriding. Files load from broadest to most specific — managed policy, then user, then project, then local — so a project instruction simply appears later in context than a user instruction. Nothing is deleted by anything else.

The Claude Code side in detail

Claude Code loads memory files in this order, broadest scope first:

Within a directory tree, files load from the filesystem root down toward your working directory, and CLAUDE.local.md loads after CLAUDE.md in the same folder. Memory files in subdirectories are loaded on demand rather than at launch.

You can also split a large file up: @path/to/import pulls in another file from anywhere in your CLAUDE.md. Relative paths resolve against the importing file, not your working directory, and imports recurse up to four hops deep. A path wrapped in backticks is treated as literal text, not an import — handy when you want to mention a file rather than load it.

The one sanctioned bridge between the two ecosystems is /init. When it generates a CLAUDE.md, it reads your existing Cursor rules — .cursor/rules/ or .cursorrules — and folds the relevant parts in. That is a one-time incorporation at generation time. It does not set up any ongoing sync, and it does not mean Claude Code consults .cursor/rules afterwards.

The gotchas that actually bite

1. A .md file in .cursor/rules does nothing. Project rules must use the .mdc extension. A plain .md file there is ignored by the rules system because it has no frontmatter — and it fails silently, which is the worst way to fail.
2. Cursor’s User Rules do not apply to Inline Edit. They are used by Agent (Chat). If a rule “works in chat but not when I hit Cmd+K,” that is expected behaviour, not a broken rule.
3. alwaysApply does not restrain CLAUDE.md. The frontmatter switches govern .mdc rules. Cursor applies CLAUDE.md to every conversation regardless.
4. Duplication is the real enemy. Two files stating the same policy in different words is how you end up with an agent that follows the older, wronger version. Delete, do not restate.

A setup that does not contradict itself

Decide which file owns each topic, then hold the line:

• Codebase conventions that are true no matter who is driving — architecture, naming, what not to touch — belong in .cursor/rules, scoped with globs so they attach only where relevant.
• Instructions you want in effect everywhere, in both tools — belong in CLAUDE.md, since both Cursor and Claude Code read it. This is the honest reason to keep a CLAUDE.md even in a Cursor-first team.
• Personal preferences — verbosity, commit style — belong in Cursor’s User Rules under Customize → Rules, or in ~/.claude/CLAUDE.md. Not in the repo, where they become everyone’s problem.

Here is a scoped Cursor rule doing its job — narrow, specific, and attached only to the files it concerns:

---
description: API route conventions
globs: src/api/**/*.ts
alwaysApply: false
---
- Every route handler validates its input before touching the database
- Errors return a problem+json body, never a bare string

And an always-on one, straight from Cursor’s documentation:

---
alwaysApply: true
---
- All source files must include the company copyright header
- When you are unsure about implementation details, read the relevant
  source files before proposing changes
- Never modify generated files in the `dist/` or `build/` directories

How to check what is actually loaded

Do not audit this by reading your own files — read them and you will see what you intended, which is exactly the thing in question. Open a fresh session and ask the agent to tell you which rules are currently active and where each came from. If it names something you do not recognise, or cannot account for a rule you know exists, that is your real configuration. Fix the files, then ask again.

What to read next

If you still have a legacy .cursorrules file in the mix, clear that up first — .cursorrules is deprecated. For how the two tools divide responsibility more broadly, read Using Claude with Cursor.