How to Migrate Your .cursorrules to CLAUDE.md (and AGENTS.md)

Cursor’s .cursorrules file and Claude Code’s CLAUDE.md solve the same problem — giving an AI assistant persistent project context and coding conventions — but they were built with different assumptions. The migration is mostly mechanical, but there are a handful of places where a direct copy-paste will not do what you expect.

This guide walks through the full migration: what to translate directly, what to rewrite, and how to end up with a setup that works across both tools if you need to support both.

Before You Start: Know What You Have

Open your .cursorrules file (or your .cursor/rules/ directory if you have migrated to the newer MDC format) and mentally sort its contents into four categories:

1. Role definition — “You are an expert TypeScript developer…”
2. Code style rules — indentation, naming conventions, import ordering
3. Project-specific context — architecture decisions, key files, domain concepts
4. Behavioral instructions — “Always ask before deleting files”, “Prefer functional style”

All four categories translate to CLAUDE.md. The main difference is that CLAUDE.md tends to reward more structured, specific instructions over the freeform paragraph style common in .cursorrules files.

Step 1: Create Your CLAUDE.md

If you do not have a CLAUDE.md yet, create it at your project root:

touch CLAUDE.md

The structure that works best for Claude Code:

# Project Name

One-sentence description of what this project is.

## Tech Stack

- Runtime: Node.js 22
- Framework: Next.js 15 (App Router)
- Language: TypeScript 5.4
- Database: PostgreSQL via Prisma
- Testing: Vitest + Playwright

## Architecture

Brief description of how the project is organized. Where are the main entry points? What are the key abstractions?

## Code Style

Specific, enforceable rules. Not vague preferences.

## Key Files

Files that are important to understand before making changes.

## Common Tasks

How to run tests, how to build, how to deploy.

## Conventions

Project-specific decisions that would not be obvious to someone reading the code.

Step 2: Translate the Role Definition

.cursorrules files often open with a role prompt:

You are an expert TypeScript developer with deep knowledge of React and Next.js best practices. You write clean, maintainable code and always consider performance implications.

For CLAUDE.md, drop the role framing. Claude Code does not respond to persona-assignment the same way an IDE assistant does. Instead, write direct instructions:

Before (cursorrules style):

You are an expert TypeScript developer who always uses proper types and never uses `any`.

After (CLAUDE.md style):

## Code Style

- TypeScript: No `any` types. If a type is genuinely unknown, use `unknown` and narrow it.
- All functions must have explicit return types.
- Prefer `const` assertions for literal values.

The behavioral outcome is the same. The second version is just more direct about what it wants.

Step 3: Translate Code Style Rules

Code style rules translate almost verbatim. The main change is organizing them under clear headers instead of as a flat list.

Before:

Always use 2-space indentation.
Use single quotes for strings.
Add trailing commas in multi-line expressions.
Use async/await instead of .then() chains.
Prefer named exports over default exports.

After:

## Code Style

### Formatting
- 2-space indentation
- Single quotes for strings
- Trailing commas in multi-line expressions (ES5 compatible)

### JavaScript/TypeScript Patterns
- `async`/`await` only — no `.then()` chains
- Named exports preferred over default exports
- Early returns to reduce nesting

The organization helps when Claude needs to reference a specific rule. A flat list of 40 rules is harder to work with than grouped categories.

Step 4: Translate Project-Specific Context

This section benefits most from migration. CLAUDE.md is where you give Claude Code the context it needs to work autonomously on your codebase — and that requires more detail than Cursor typically needs, since Cursor has real-time IDE access to your file tree.

Before (cursorrules):

This is a SaaS application for managing construction projects.
The main data model is organized around Projects, which contain Tasks and Documents.

After (CLAUDE.md):

## Architecture

This is a multi-tenant SaaS application for construction project management.

### Domain Model
- **Workspace**: top-level tenant container
- **Project**: a construction project within a workspace
- **Task**: work item within a project (has status, assignee, due date)
- **Document**: file attachment linked to a project or task

### Key Files
- `src/lib/db/schema.prisma` — complete database schema
- `src/lib/auth/` — authentication and authorization logic
- `src/app/api/` — all API routes
- `src/components/ui/` — shared UI components (do not modify without reviewing usage)

### Multi-tenancy
All database queries must filter by `workspaceId`. The `withWorkspace()` helper enforces this. Never query across tenants.

The explicit file paths, the warning about multi-tenancy, the key abstractions — this is the kind of context that lets Claude Code work on your project without constantly asking clarifying questions.

Step 5: Translate Behavioral Instructions

Behavioral instructions like “always ask before deleting” or “prefer immutable patterns” also translate directly, but be specific about scope:

Before:

Always ask before making large refactors.
Never modify the database schema without discussion.

After:

## Working Conventions

- Before refactoring more than 3 files, describe the plan and ask for confirmation.
- Changes to `schema.prisma` require explicit approval. Do not modify the schema as a side effect of other work.
- Run `npm test` after any change to `src/lib/`. Do not leave failing tests.

The second version is actionable. “Large refactors” is ambiguous; “more than 3 files” is not.

Step 6: Handle Cursor-Specific Instructions

Some things in .cursorrules are Cursor-specific and do not translate:

Remove these:

• References to Cursor’s inline suggestions (“when suggesting code, use the ghost text style”)
• Cursor UI-specific behavior (“in the chat panel, prefer concise answers”)
• Cursor-specific @ mentions (“when I use @file, explain what you’re doing”)

These mean nothing to Claude Code. Strip them out. If the underlying intent matters, restate it as a general behavioral instruction.

Review these:

• Instructions about when to show diffs vs. full files — Claude Code has its own behavior here
• Instructions about not changing files outside the request — Claude Code already tends to follow this; you may not need to repeat it

The Result: A Complete Example

Here is a before/after for a typical React project:

Before (.cursorrules):

You are an expert React developer who writes clean, accessible, and performant code.

Always use TypeScript. Never use `any`.
Use functional components only. No class components.
Use React hooks for state management. Avoid Redux unless the project already uses it.
Follow WCAG 2.1 AA accessibility standards.
Use Tailwind CSS for styling. No CSS modules or styled-components.
Write tests for all components using React Testing Library.
Always handle loading and error states.
Import from '@/' using the configured alias.
Do not use default exports for components.

After (CLAUDE.md):

# React Dashboard

Internal analytics dashboard for the marketing team.

## Tech Stack
- React 19 + TypeScript 5.4
- Tailwind CSS v4
- React Testing Library + Vitest
- Path alias: `@/` → `src/`

## Component Rules
- Functional components only (no class components)
- Named exports only (no default exports)
- Props interface defined above the component, not inline

## TypeScript
- No `any`. Use `unknown` + type narrowing for genuinely unknown values.
- All component props must be explicitly typed.

## Styling
- Tailwind CSS only. No CSS modules, no styled-components, no inline styles.
- Use the `cn()` utility from `src/lib/utils` for conditional classes.

## State Management
- React hooks for local state
- React Query for server state
- No Redux (not in this project)

## Testing
- React Testing Library for all components
- Test loading states, error states, and empty states explicitly
- Tests live alongside components: `Button.tsx` → `Button.test.tsx`

## Accessibility
- WCAG 2.1 AA required
- All interactive elements need accessible names
- Use semantic HTML elements before reaching for ARIA

## Conventions
- Always handle loading and error states. No component should assume data is always present.
- Import from `@/` always. No relative imports that traverse up more than one directory.

The CLAUDE.md version is longer, but every line is doing work.

Supporting Both Tools: The AGENTS.md Approach

If your team uses both Cursor and Claude Code, maintain a single source of truth in AGENTS.md at the project root. Both tools respect this file.

# agents

## default
description: General-purpose coding assistant for this project
tools: read, write, bash, edit

Then put your shared project context in AGENTS.md using the same structure as CLAUDE.md. Cursor reads the content. Claude Code reads the content. You maintain one file instead of two.

For tool-specific behavior that cannot be unified, keep separate files:

• AGENTS.md — shared context, architecture, code style
• CLAUDE.md — Claude Code-specific settings (subagent configs, hook scripts, tool permissions)
• .cursor/rules/ — Cursor-specific rules (inline suggestion behavior, panel preferences)

After the Migration

Test with a real task. Ask Claude Code to implement a small feature that requires understanding your project structure. Check whether it:

• Follows your naming conventions without being reminded
• Uses the right import paths
• Handles edge cases you documented
• Asks for confirmation when your conventions require it

If it gets something wrong, add it to CLAUDE.md explicitly. The migration is working when Claude Code’s first attempt matches what you would have written yourself.