DEV Community

Olivia Craft
Olivia Craft

Posted on

Switching from Cursor to Claude Code? Your Rules Stop Working (Migration Guide)

#cursor #claudecode #aicoding #tutorial

Switching from Cursor to Claude Code is fast. But there is a quiet cost nobody warns you about: your rules stop working.

Your .cursorrules file? Claude Code does not read it. Your .cursor/rules/*.mdc files? Also invisible. Every rule you spent time writing — the one that stops the agent from touching production, the one that enforces your naming conventions — gone.

This is not a bug. It is just two different tools with two different rule systems. But it catches almost everyone who switches.

What Cursor Uses

Cursor reads rules from:

  • .cursorrules (legacy, works in most modes)
  • .cursor/rules/*.mdc (current format, required for Agent mode)

Rules in .mdc files have frontmatter that controls when they fire:

---
description: "TypeScript project conventions"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
Enter fullscreen mode Exit fullscreen mode

When alwaysApply: true, the rule is included in every Agent mode context. When false, it only fires when matching files are in scope.

What Claude Code Uses

Claude Code reads rules from CLAUDE.md. One file (or a few, with a hierarchy).

The structure is different. There is no frontmatter. No glob matching. Rules are plain Markdown sections that Claude reads as part of its working context.

A typical CLAUDE.md:

## Safety Rules
- NEVER push to production without explicit human approval
- ALWAYS run tests before marking a task done

## Code Style
- Use TypeScript strict mode
- Prefer named exports over default exports

## Project Context
- This is a monorepo with /packages/api and /packages/web
- Database: PostgreSQL via Prisma
Enter fullscreen mode Exit fullscreen mode

Claude Code reads this at the start of every session. It also reads CLAUDE.md files in subdirectories when working in those folders.

The Migration Problem

The mental model difference is the core issue. Cursor rules are tool-level configuration — they control when and how the IDE applies context. CLAUDE.md is agent-level instruction — it is read by the model as part of its working context.

This means:

  1. You cannot copy-paste your .cursorrules into CLAUDE.md and expect the same behavior
  2. Glob-based rules have no equivalent in CLAUDE.md (everything applies everywhere)
  3. alwaysApply: false rules need to be rethought — in Claude Code, either the rule is in CLAUDE.md or it is not

How to Migrate Cleanly

Step 1: Export your most important Cursor rules

Go through your .cursor/rules/*.mdc files. For each rule with alwaysApply: true or that fires constantly, it is a candidate for CLAUDE.md.

Step 2: Translate the format

# Cursor .mdc
---
description: Never push to production directly
alwaysApply: true
---
Never push directly to the main branch. Always create a feature branch.
Enter fullscreen mode Exit fullscreen mode

Becomes in CLAUDE.md:

## Deployment Rules
- Never push directly to main. Always use a feature branch.
- Production deployments require explicit human approval.
Enter fullscreen mode Exit fullscreen mode

Step 3: Handle glob-scoped rules differently

If you had rules that only fired for *.py files, you have two options:

  1. Promote them to global CLAUDE.md rules (safe if they are general enough)
  2. Create a CLAUDE.md inside the Python subfolder — Claude Code reads the nearest one

Step 4: Test with a cheap task

Before trusting your migrated rules, run a small task and watch if Claude respects the constraints. If it ignores a rule, the phrasing may be too weak. "Prefer X" fails more often than "Always use X. Never use Y."

The Deeper Issue

The reason rules get ignored is not just format. It is instruction density.

When your CLAUDE.md grows to 500+ words, the important rules get buried. Claude weighs all context together — your rules compete with the task description, the codebase, and the conversation history.

The rules that survive are:

  • Short and specific
  • At the top of the file
  • Stated as absolutes, not preferences
  • Repeated in the task prompt when critical

The rules that get lost are:

  • Buried in the middle of a long file
  • Vague or hedged
  • Only written once, never reinforced

If You Use Both Tools

Some teams use Cursor for day-to-day editing and Claude Code for longer autonomous tasks. In this case you need both systems working.

The practical approach: keep a AGENT_RULES.md as your source of truth, then generate both .cursor/rules/main.mdc and CLAUDE.md from it. This is more work upfront but prevents drift — the worst outcome is when your Cursor rules say one thing and your CLAUDE.md says another.

What This Means for Your Workflow

If you are switching from Cursor to Claude Code (or running both):

  1. Do not assume your rules transferred — they did not
  2. Rewrite the top 5 most important rules into CLAUDE.md explicitly
  3. Put safety rules first, style rules after
  4. Test that each rule actually fires before trusting the agent with real tasks

The cost of an ignored rule is not just a style violation. It is an agent that pushes to production without asking, deletes files it should not, or skips tests because nothing was there to stop it.

If you want a battle-tested starting point:

The migration is worth doing. Just do it with your eyes open.

Top comments (0)