Cursor Rules vs Claude Code CLAUDE.md (2026)

Cursor rules are files with YAML frontmatter stored at .cursor/rules/*.mdc, each one scoped to a glob (or marked always-apply) so only the matching files trigger it. CLAUDE.md is a single plain-markdown file Claude Code loads in full on every turn, with no frontmatter and no built-in path scoping. If you're standardizing on one editor, the two formats aren't drop-in compatible — migrating well means re-checking every rule's scope by hand, not just copy-pasting the prose.

Format and scope, side by side

A Cursor rule lives at .cursor/rules/<name>.mdc with YAML frontmatter at the top: description, a globs pattern, and an alwaysApply boolean. Cursor only injects a rule's body into context when the file being edited matches its glob, or when alwaysApply: true forces it in on every request. A repo can hold dozens of small .mdc files, each scoped to one slice of the codebase — one for app/api/**, another for *.test.ts.

CLAUDE.md has none of that machinery. It's one markdown file (optionally nested per-directory) that Claude Code reads in full at the start of every session — no frontmatter, no glob matching, no conditional loading. Scope has to be expressed in prose ("in app/api/, always validate the tenant from the session") rather than enforced by a matcher, and everything in the file is paid for on every single turn whether or not the current task touches that area.

Path-scoped rules in both ecosystems

Cursor's path scoping is a first-class feature: write globs: app/api/**/*.ts and the rule simply doesn't exist for a request that never touches that directory. Claude Code gets a rougher equivalent through nested CLAUDE.md files — a CLAUDE.md inside app/api/ that only applies when Claude is working in that subtree, read alongside the root file. It's directory-level, not glob-level: you can't scope to *.test.ts specifically, only to the folder those tests happen to live in.

The practical effect: a Cursor setup with ten narrow, well-scoped .mdc files can stay lean indefinitely, because each one only costs tokens when relevant. A single root CLAUDE.md with the same ten rules pasted in costs tokens on every turn, which is why Claude Code projects tend to push anything not universally true into skills instead of nested CLAUDE.md files — see CLAUDE.md vs Skills vs Subagents vs Hooks.

Migrating .mdc rules into a CLAUDE.md

  1. Separate always-apply from path-scoped rules. Any .mdc with alwaysApply: true maps directly to the root CLAUDE.md. Rules with a globs pattern need a decision, not a copy-paste.
  2. For path-scoped rules, pick directory or skill. If the glob roughly matches a real directory (app/api/**), move the rule into a CLAUDE.md nested in that folder. If the glob is cross-cutting (*.test.ts anywhere in the repo) or the rule is a multi-step walkthrough rather than a short instruction, it belongs in a skill instead, since a nested CLAUDE.md can't match file extensions and skills only load when the task actually matches.
  3. Strip anything Claude can already infer. Rules that just restate the stack ("this is a Next.js app") add nothing; CLAUDE.md should hold constraints a reasonable default wouldn't guess.
  4. Grade the result. Run the merged file through the Rules File Grader — it flags rules that have gone stale, vague instructions with no concrete check, and files that have grown past the point of being skimmed.
  5. Keep the two in sync going forward, or pick one source. If you still use Cursor on the same repo, maintaining both by hand drifts fast; the Config Converter generates one format from the other so you're not hand-copying every change.

Our recommendation

If you've fully switched to Claude Code, don't try to replicate Cursor's glob-level precision — you can't, and chasing it just produces a sprawl of nested CLAUDE.md files that are harder to reason about than Cursor's flat list of .mdc files ever was. Keep the root CLAUDE.md short and universally true, push directory-specific constraints into nested CLAUDE.md files only where they map cleanly to a real folder, and move everything else — multi-step procedures, anything conditional on the kind of task rather than the kind of file — into a skill. That's a different shape than Cursor rules, not a worse one: skills load on relevance rather than on a path match, which covers cases glob syntax can't ("when touching Stripe webhooks," not "when touching this directory").

Run your CLAUDE.md through the linter

Whichever direction you migrate, check the result before trusting it in production. The Rules File Grader scores a CLAUDE.md or .mdc file for length, specificity, and staleness, and flags rules that read fine to a human but give Claude nothing concrete to check against. Paste the file in, fix what it flags, and re-run it after your next few migrations rather than assuming the first conversion got everything.

Related pages

Frequently asked questions

  • Can Claude Code read .cursor/rules/*.mdc files directly?
    No. Claude Code reads CLAUDE.md, not .mdc files, and ignores their YAML frontmatter entirely. You need to convert the content, either by hand or with a tool like the Config Converter.
  • Does CLAUDE.md support glob-scoped rules like Cursor's globs field?
    Not natively. The closest equivalent is a nested CLAUDE.md placed inside the directory you want the rule to apply to, which scopes by folder, not by file pattern — you can't target just *.test.ts across the repo the way a Cursor glob can.
  • What happens to alwaysApply: true rules when migrating?
    Those map cleanly to the root CLAUDE.md since both are loaded unconditionally on every turn — no scoping logic to lose in the conversion.
  • Should I keep maintaining both formats if I use Cursor and Claude Code on the same repo?
    Only by generating one from the other. Hand-maintaining both drifts the moment someone edits just one side; use the Config Converter to regenerate the other format after each change.

Check your CLAUDE.md after migrating

Run the merged file through the Rules File Grader to catch bloat, vague instructions, and rules that no longer have a path to scope them to.