How to migrate from Cursor to Claude Code: convert your rules, config, and workflow

You have been using Cursor. Your .cursorrules file has your project conventions, your preferred patterns, your testing setup. Now you want to try Claude Code, and the first thing you notice is that it ignores your .cursorrules entirely.

Claude Code reads CLAUDE.md. Different tool, different config file. The content is mostly the same. The translation is straightforward, but there are a few things that change and a few things Claude Code does that Cursor does not.

What you are translating

Both .cursorrules and CLAUDE.md tell an AI coding tool about your project. The core categories are identical:

• Project structure and file locations
• Coding conventions and naming patterns
• Technology stack and framework details
• Testing setup and commands
• Rules and restrictions

If your .cursorrules covers these, you already have 80% of a good CLAUDE.md. The remaining 20% comes from Claude Code-specific features.

Step 1: copy the content, change the format

.cursorrules is typically plain text or loosely formatted. CLAUDE.md is markdown. This matters because Claude Code parses headings and structure to prioritize information.

Take your existing rules and organize them under clear markdown headings:

# Project Overview
[Your project description — stack, purpose, one-liners]

# File Structure
[Directory layout — where components, routes, models, tests live]

# Coding Conventions
[Naming, formatting, import ordering, component patterns]

# Testing
[Framework, commands, file naming, mocking strategy]

# Guardrails
[What to never do — destructive commands, off-limits files, confirmation requirements]

These five sections are the backbone. You can add more, but if you cover these you are already ahead of most CLAUDE.md files.

Step 2: add what Cursor does not need

Claude Code is a terminal agent, not an IDE extension. It has capabilities that Cursor does not, and those capabilities need configuration:

Shell commands

Claude Code runs shell commands directly. It needs to know which commands are safe and which need confirmation.

# Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev server: `npm run dev`

# Command Safety
- Never run `rm -rf` — use `mv` to .trash/ instead
- Never run `git push --force` without confirmation
- Database migrations require confirmation before applying

Cursor does not execute shell commands the same way, so your .cursorrules probably does not have this section. Add it.

Multi-file operations

Claude Code regularly works across multiple files in one session. It reads, edits, creates, and deletes files. Rules about how to handle multi-file changes matter:

# Multi-file Rules
- Prefer editing existing files over creating new ones
- When refactoring, update all imports in a single session
- Run tests after any multi-file change
- Do not create new files unless the task specifically requires it

The rules directory

Claude Code supports .claude/rules/*.md for section-specific rules. If your project has a frontend and a backend with different conventions, you can split rules:

.claude/rules/frontend.md  — React conventions, component patterns
.claude/rules/backend.md   — API patterns, database rules
.claude/rules/testing.md   — Test framework, mocking strategy

Cursor does not have an equivalent. This is useful for monorepos or projects where different directories follow different patterns.

Step 3: handle tool-specific directives

Some things in your .cursorrules are Cursor-specific and do not apply to Claude Code:

• Tab completion rules — Claude Code does not do inline completions. Remove these.
• Editor-specific commands — References to Cursor commands or keybindings. Remove.
• Chat vs compose modes — Claude Code has one mode. It reads files, makes changes, runs commands. Simplify accordingly.

Conversely, add Claude Code-specific directives:

• Tool preferences: "Use the Edit tool for small changes, Write for new files"
• Agent behavior: "Use subagents for independent research tasks"
• Permission boundaries: "Do not push to remote without confirmation"

Step 4: keep both files in sync (or use one source)

If you use both Cursor and Claude Code on the same project, you now have two config files with overlapping content. There are two approaches:

Option A: maintain both manually

This works for small projects. When you update a convention, update both files. The risk is drift: after a few months the files diverge and one tool follows outdated rules.

Option B: generate from one source

The ContextKit Generator builds configs for Claude Code, Cursor, Gemini CLI, and GitHub Copilot from one set of inputs. You answer questions about your project once, then export to whichever format you need.

When you update your project config, regenerate all formats at once. No drift, no forgotten updates.

What to expect after switching

Claude Code works differently from Cursor. A few things to prepare for:

• It is terminal-based. No GUI, no visual diff. You work in your terminal and check results in your editor or browser.
• It is more autonomous. Claude Code can chain multiple operations: read a file, make changes, run tests, fix failures, commit. Cursor is more step-by-step.
• It is better at multi-file tasks. Refactoring across 10 files, adding a feature that touches routes/models/tests/types — this is where Claude Code shines.
• It is slower for quick edits. If you just need to rename a variable on one line, Cursor is faster. Claude Code is built for bigger tasks.

The quality of your CLAUDE.md directly affects the quality of Claude Code sessions. A well-configured file means Claude follows your patterns from the first task. A bare-bones file means you spend the first few minutes of every session correcting behavior.

Check your migration

After creating your CLAUDE.md, run it through the ContextKit Analyzer to see how it scores. The analyzer checks five categories (structure, architecture, conventions, testing, guardrails) and tells you exactly what is missing.

Most files migrated from .cursorrules score around 5-6 on the first pass — they have the content but miss Claude Code-specific sections like guardrails and command safety. The analyzer shows you exactly what to add to get to 8+.