Cursor Rules vs CLAUDE.md: When to Use Which (And How They Work Together)

If you're using AI coding tools seriously, you've probably heard of both .cursorrules and CLAUDE.md. They solve the same fundamental problem: giving AI persistent context about your project.

Without them, every AI session starts from scratch. The AI doesn't know your tech stack, your folder conventions, your naming patterns, or the quirks that make your project unique. You end up repeating the same instructions over and over.

Both files fix this. But they work differently, they're read by different tools, and they have different strengths. Most developers pick one and ignore the other. That's a mistake — they're most powerful when used together.

What .cursorrules Does

.cursorrules is Cursor's project-level configuration file. When you open a project in Cursor, it automatically reads this file and applies the rules to every AI interaction within that project.

Key characteristics:

• Tool-specific — only Cursor reads it. Other AI tools ignore it completely.
• Instruction-focused — best for telling the AI what to do and what not to do.
• Applies to all interactions — every chat, every inline edit, every Cmd+K generation follows these rules.
• Supports glob patterns — you can scope rules to specific file types or directories.

A typical .cursorrules:

You are an expert in TypeScript, React, Next.js App Router, and Tailwind CSS.

Key Principles:
- Write concise, technical TypeScript code
- Use functional and declarative programming patterns
- Prefer iteration and modularization over duplication
- Use descriptive variable names with auxiliary verbs (isLoading, hasError)

Naming Conventions:
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with "use" prefix (useAuth.ts)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE

DO NOT:
- Use `any` type
- Use default exports (except for pages)
- Put business logic in components
- Use inline styles

What CLAUDE.md Does

CLAUDE.md is Claude's project context file. Claude Code, Claude in the terminal, and other Claude-powered tools read it automatically when they enter your project directory.

Key characteristics:

• Tool-specific — Claude tools read it. Cursor doesn't (unless you explicitly include it in context).
• Context-focused — best for explaining your project's architecture, decisions, and constraints. Not just rules, but why those rules exist.
• Hierarchical — you can have a root CLAUDE.md plus subdirectory-specific ones (e.g., src/components/CLAUDE.md). Claude merges them based on what files it's working with.
• Supports project commands — you can define shortcuts for common tasks like building, testing, and deploying.

A typical CLAUDE.md:

# Project Overview
Next.js 15 SaaS app for invoice management.
- Frontend: React 19, TypeScript, Tailwind CSS
- Backend: Next.js API routes, Drizzle ORM
- Database: PostgreSQL (Supabase)
- Auth: Better Auth with Google OAuth
- Payments: Stripe
- Deployment: Vercel

# Architecture
Feature-based folder structure:
src/
  app/         # Pages and API routes
  features/    # Feature modules (auth/, billing/, invoices/)
  components/  # Shared UI components
  lib/         # Utilities, DB client, API helpers

# Important Constraints
- Auth middleware runs on Edge Runtime — no Node.js APIs
- All monetary values stored as integers (cents), displayed as decimals
- Invoices use optimistic locking — always check version before update

# Commands
- Build: npm run build
- Test: npm run test
- Dev: npm run dev

The Key Differences

When to Use Which

Use .cursorrules when:

• Your team primarily uses Cursor as their AI coding tool
• You want to enforce strict coding patterns across all AI interactions
• Your rules are mostly about code style: naming, imports, error handling patterns
• You want rules that apply to inline edits and quick generations, not just chat

Use CLAUDE.md when:

• Your team uses Claude Code or Claude-powered tools
• You need to document complex architecture that requires explanation, not just rules
• Your project has non-obvious constraints (edge runtime limitations, data format decisions, etc.)
• You want project commands integrated into the AI workflow
• Different parts of the codebase need different context (use subdirectory CLAUDE.md files)

Use both when:

• Team members use different AI tools (some on Cursor, some on Claude)
• You want consistent AI behavior regardless of which tool is used
• You want the best of both: Cursor's pattern enforcement + Claude's architectural context

How to Use Them Together

Here's the approach that works best: put architectural context in CLAUDE.md, put coding rules in .cursorrules, and keep them in sync.

What goes in CLAUDE.md only:

• Project overview and tech stack
• Architecture decisions and their reasoning
• Non-obvious constraints ("monetary values are stored as cents because...")
• Common tasks with step-by-step instructions
• Build/test/deploy commands

What goes in .cursorrules only:

• The persona prompt ("You are an expert in...")
• Cursor-specific behaviors (how to handle inline edits, tab completions)

What goes in both (keep synced):

• Naming conventions
• Folder structure
• Import patterns
• Error handling approach
• "Do not" rules

Yes, there's some duplication. That's the cost of supporting multiple tools. The alternative — having rules in one file and not the other — means your AI behavior is inconsistent depending on which tool you're using. That's worse.

Keeping them in sync

The practical approach: treat CLAUDE.md as the source of truth for architecture and constraints, and .cursorrules as the source of truth for coding patterns. When you update a shared rule (like naming conventions), update both files. It takes 30 seconds and prevents drift.

Common Mistakes

1. Making them too long

Both files compete for the AI's attention window. A 2,000-line rules file means the AI is spending context on your instructions instead of on understanding the code it's working with. Aim for 200-500 lines max for each file.

2. Being vague

"Write clean code" is useless in both files. "Use named exports for all non-page files" is actionable. Be specific enough that there's only one way to interpret the rule.

3. Never updating them

Your project evolves. Your rules should too. If you switched from REST to tRPC three months ago but your CLAUDE.md still describes REST patterns, the AI will generate REST code. Review your files monthly.

4. Not including examples

AI tools are pattern matchers. A rule like "use the repository pattern for database access" is vague. A rule with a 5-line code example of what that looks like in your project is crystal clear.

Getting Started Today

If you have neither file, here's the 30-minute setup:

1. Create CLAUDE.md — write your project overview, tech stack, folder structure, and top 5 constraints.
2. Create .cursorrules — write your coding conventions, naming rules, and "do not" list.
3. Copy shared rules — naming conventions, folder structure, and import patterns should appear in both.
4. Test it — ask both tools to create a new component. Does the output match your conventions? If not, your rules aren't specific enough.

If you already have one file, creating the other takes 15 minutes — most of the thinking is already done.

For a deeper dive into CLAUDE.md specifically, check out our CLAUDE.md setup guide.

Originally published at bivecode.com