← Back to blog

    Cursor Rules vs CLAUDE.md

    The search intent behind "cursor rules vs claude.md" is usually practical. A team is using Cursor for editor-side agent work and Claude Code for terminal-side agent work. Cursor has .cursor/rules. Claude Code has CLAUDE.md. Both files look like markdown instructions. Both seem to tell an AI how to behave. The obvious question is whether they are the same thing with different names.

    They are not the same thing. They are neighboring harness surfaces with different loading semantics.

    That distinction matters because most bad comparisons stop at file format. They say Cursor rules are markdown and CLAUDE.md is markdown, so you can copy one into the other. That is how teams end up with stale rules, duplicated project policy, and agents that disagree about how the repo works. A useful comparison has to ask four questions: where does the file live, when does it fire, what metadata controls loading, and which parts should be shared.

    My rule of thumb is direct: use AGENTS.md for cross-agent project rules, use CLAUDE.md for Claude Code-specific context or as a pointer, and use .cursor/rules for Cursor-specific scoped rules. If one of those files grows into the source of truth for everything, the harness will eventually fork.

    What Cursor rules are

    Cursor project rules live under .cursor/rules. The current Cursor docs describe them as version-controlled project rules that give persistent, reusable instructions to Agent and Inline Edit. Each rule is a file, usually .mdc, with frontmatter plus markdown content. The frontmatter is not decorative. It controls how the rule is attached.

    A small rule looks like this:

    ---
description: React component conventions
globs: "src/components/**/*.tsx"
alwaysApply: false
---

- Use existing components/ui primitives before adding new visual primitives.
- Keep component props explicit. Do not pass untyped rest props across public boundaries.
- Put colocated tests beside the component when the existing directory already does that.

    That file is not just a note. It is an attachable context unit. Cursor can include it always, attach it when matching files are referenced, make it available for the agent to request, or require manual mention. That makes .cursor/rules closer to a set of scoped prompt modules than one global project memory file.

    This is the core semantic difference: Cursor rules are rules-for-AI, but each file can have its own activation rule. The rule is not necessarily part of every chat. It can be narrow by path, narrow by manual invocation, or broad through alwaysApply.

    What CLAUDE.md is

    CLAUDE.md is the project memory file for Claude Code. It is plain markdown and is meant to describe the operating context Claude Code should load for the project. Teams put project facts, commands, process rules, style rules, local gotchas, and Claude Code-specific notes there.

    CLAUDE.md is not an .mdc file. It does not have Cursor-style globs or alwaysApply fields. It does not split naturally into many path-scoped rule modules unless you create your own surrounding convention. It is better understood as rules-for-current-chat: durable project context that Claude Code should have when the session starts in that repo.

    That makes CLAUDE.md stronger for broad orientation and weaker for fine-grained scoping. If every task needs to know "use npm only" or "do not print secret values," CLAUDE.md is a reasonable place for Claude Code to see it. If only apps/admin/** needs a rule about internal table components, CLAUDE.md is usually too blunt. A scoped Cursor .mdc rule fits that shape better.

    The .mdc difference

    The .mdc format is the practical reason you should not treat .cursor/rules as "just markdown." A Cursor rule can carry metadata:

    ---
description: API client generation rules
globs: "packages/api-client/**"
alwaysApply: false
---

    The content below the frontmatter is markdown, but the frontmatter decides the loading behavior. The common project-rule types are:

    Always: included in model context every time.
Auto Attached: included when referenced files match the glob.
Agent Requested: available to the AI, which decides whether to include it. Requires a description.
Manual: included only when explicitly mentioned with @ruleName.

    The exact UI labels may evolve, but the underlying design is stable enough to plan around: Cursor rules are modular and attachable. The .mdc file is a harness control surface, not just a prose document.

    CLAUDE.md has no equivalent frontmatter contract. If you paste ten .mdc files into CLAUDE.md, you lose the activation semantics. Claude Code now sees all of it, all the time. If you paste CLAUDE.md into one always-applied Cursor rule, Cursor now sees broad Claude-specific context even when a narrower rule would have been cheaper and clearer.

    When each one fires

    Cursor rules fire according to their rule type. An always-applied Cursor rule is included broadly. An auto-attached rule comes in when files matching globs are part of the current context. An agent-requested rule is available when the description makes it relevant. A manual rule waits for an explicit mention.

    CLAUDE.md fires at the Claude Code project context layer. A fresh Claude Code session in the repo should load the project guidance. If a team also has global Claude guidance, the project file sits in that chain. The important point is that it is not path-glob attached in the Cursor sense. It is the broad project instruction surface for that tool.

    This creates different failure modes.

    Cursor failure mode: a rule is correct but does not attach because the glob is wrong, the description is too vague, or the rule type is wrong. The agent acts as if the rule does not exist.

    CLAUDE.md failure mode: a rule is correct for one area but always loaded everywhere. The file becomes long, noisy, and full of local exceptions. The agent starts treating all rules as equal weight, even though many are irrelevant to the current task.

    Both failure modes are harness bugs. They are not model personality.

    What belongs in both

    Project rules that affect every agent should exist in a canonical source and be visible to both tools. Examples:

    - Use npm only. package-lock.json is canonical.
- Run npm run build before opening a PR.
- Do not edit generated dist/ output by hand.
- Never print secret values. Refer to environment variable names only.
- New public API behavior requires docs and tests.

    Do not let Cursor and Claude Code disagree on these. If Cursor thinks pnpm is fine and Claude Code thinks npm is mandatory, you do not have tool-specific nuance. You have drift.

    The cleanest pattern is to make AGENTS.md canonical for shared project rules. Then CLAUDE.md points at it, and .cursor/rules either points at it or receives generated scoped rules from it. That gives you one owner for project policy and separate adapters for harness mechanics.

    What should not be shared

    Claude Code-specific mechanics should not live in Cursor rules unless Cursor truly needs to know them. Examples include Claude Code hooks, Claude Code skills, slash command behavior, and Claude-specific MCP permission notes.

    Cursor-specific mechanics should not live in CLAUDE.md unless Claude Code truly needs to know them. Examples include .mdc glob patterns, manual @ruleName invocation, or Cursor UI rule type choices.

    The test is simple: would a human reviewer expect the same rule to apply if the edit came from a terminal agent, an editor agent, or a person? If yes, it is a project rule. If no, it is tool-specific.

    A shared pattern that works

    For a repo using both tools, start here:

    AGENTS.md
CLAUDE.md
.cursor/rules/project.mdc
.cursor/rules/frontend.mdc
.cursor/rules/backend.mdc

    AGENTS.md owns the cross-agent project rules:

    # AGENTS.md

## Commands
- Install: npm ci
- Build: npm run build
- Test: npm test

## Working rules
- Branch from main and open a PR.
- Do not edit generated dist/ output by hand.
- Never print secret values.

    CLAUDE.md is a thin adapter:

    # CLAUDE.md

AGENTS.md is the canonical project instruction file.
Read it before making changes.

Claude Code-specific notes:
- Workflow skills live in .claude/skills/.
- Hooks are configured in .claude/settings.json.

    Cursor gets one always-applied pointer plus scoped rules:

    ---
description: Canonical project rules
globs:
alwaysApply: true
---

Project rules live in AGENTS.md. Treat AGENTS.md as canonical for package manager,
commands, branch policy, generated files, and secrets.

    Then add .cursor/rules/frontend.mdc only for frontend-specific Cursor behavior:

    ---
description: Frontend implementation rules
globs: "src/**/*.{ts,tsx,css}"
alwaysApply: false
---

- Use existing UI primitives before adding new visual primitives.
- Do not introduce a new color scale without updating tailwind.config.ts.

    This layout keeps shared rules shared and scoped rules scoped. It also makes review obvious. A package-manager change touches AGENTS.md first. A Cursor glob change touches .cursor/rules. A Claude hook change touches CLAUDE.md or .claude/settings.json.

    The mistake to avoid

    Do not maintain three full copies of the same project policy. Full copies feel safe because each tool has a complete file. They are unsafe because they require perfect human synchronization. The first urgent fix will update one file. The second urgent fix will update a different file. Six weeks later, the files disagree about tests and nobody remembers why.

    The better mental model is adapter, not duplicate. AGENTS.md is the policy source. CLAUDE.md adapts it into Claude Code. .cursor/rules adapts it into Cursor and adds Cursor-only scoping.

    AgentLint fits this comparison because it treats CLAUDE.md, AGENTS.md, .cursor/rules, CI, and hooks as one harness layer. It can catch the drift that starts when "same rule, different file" turns into "same repo, different behavior."

    Related posts

    AGENTS.md vs CLAUDE.md

    Using CLAUDE.md and Cursor Rules Together

    Cursor Rules for Monorepos