# Cursor Rules vs Claude Code CLAUDE.md

> How Cursor's .cursor/rules/*.mdc system differs from Claude Code's CLAUDE.md — frontmatter, path scoping, always-apply flags — and the actual steps to migrate rules into a CLAUDE.md.

Canonical: https://www.agentickit.co/compare/cursor-rules-vs-claude-md
Last updated: 2026-11-18

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/&lt;name&gt;.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](https://www.agentickit.co/skills) instead of nested CLAUDE.md files — see [CLAUDE.md vs Skills vs Subagents vs Hooks](https://www.agentickit.co/compare/claude-code-skills-vs-subagents-vs-hooks).

## Migrating .mdc rules into a CLAUDE.md
<ol>- **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.
- **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.
- **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.
- **Grade the result.** Run the merged file through the [Rules File Grader](https://www.agentickit.co/tools/rules-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.
- **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](https://www.agentickit.co/tools/config-converter) generates one format from the other so you're not hand-copying every change.
</ol>

## 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](https://www.agentickit.co/tools/rules-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.



## FAQ

### 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.

## Related
- [Rules File Grader](https://www.agentickit.co/tools/rules-grader)
- [Config Converter](https://www.agentickit.co/tools/config-converter)
- [Cursor Rules vs AGENTS.md vs CLAUDE.md (three-way version with Codex/Windsurf)](https://www.agentickit.co/compare/cursor-rules-vs-agents-md-vs-claude-md)
- [CLAUDE.md vs Skills vs Subagents vs Hooks](https://www.agentickit.co/compare/claude-code-skills-vs-subagents-vs-hooks)
- [Is there really a 200-line rule for CLAUDE.md?](https://www.agentickit.co/blog/claude-md-200-line-rule)
