Claude Code Users: Why Your Rules Get Ignored (And How to Fix It with CLAUDE.md)

What Changed — The Legacy of .cursorrules and Claude Code's Approach

Cursor's .cursorrules file is silently ignored in Agent Mode. This isn't a Claude Code issue—Claude Code uses CLAUDE.md for project rules. But if you're migrating from Cursor, you need to know: CLAUDE.md is the only way to enforce rules in Claude Code's agentic workflows.

Cursor's .cursorrules works in standard chat but not in Agent Mode. The newer system uses .cursor/rules/*.mdc files with YAML frontmatter. Claude Code users have a simpler, more powerful alternative: CLAUDE.md.

What It Means For You — Concrete Impact on Daily Claude Code Usage

If you've been relying on .cursorrules to guide Claude Code's behavior, you've been getting zero rule enforcement. Claude Code ignores .cursorrules entirely. It uses CLAUDE.md at the project root.

This explains:

• Why Claude Code keeps using the wrong framework
• Why naming conventions get ignored mid-run
• Why the same instruction works in chat but not in agent tasks

The fix? Create a CLAUDE.md file in your project root.

Try It Now — How to Structure CLAUDE.md for Claude Code

Minimal working structure:

your-project/
└── CLAUDE.md          ← global rules, always loaded
└── .claude/
    └── rules/
        ├── backend.md ← loaded for backend files
        └── frontend.md ← loaded for frontend files

Global Rules (CLAUDE.md)

---
description: Core project rules for all agent tasks
alwaysApply: true
---

# Project Rules
- Stack: Next.js 14, TypeScript strict, Tailwind CSS
- Never use `any` type — use explicit types or `unknown`
- All components in `/components`, never inline in pages
- Write tests for every exported function
- Commit messages: conventional commits format

The key field is alwaysApply: true. Without it, Claude Code may skip the rule file entirely.

Context-Specific Rules (.claude/rules/backend.md)

---
description: Rules for API routes and server-side code
globs: ["app/api/**", "lib/server/**"]
alwaysApply: false
---

# Backend Rules
- All API routes must validate with Zod
- Never expose raw database errors to the client
- Use the shared `apiResponse()` helper for all responses

The globs field tells Claude Code when to load this file. If the agent touches app/api/users/route.ts, it picks up backend rules automatically.

Common Migration Mistakes

1. alwaysApply: false on your global rules — Without alwaysApply: true, Claude Code only loads the rule when a file glob matches. Global rules need explicit opt-in.

2. Keeping both .cursorrules and CLAUDE.md files — Mixed state causes inconsistent behavior. Delete .cursorrules once migrated.

3. One giant CLAUDE.md file — Rule files are evaluated per-context. Split by domain: always-apply globals, language-specific, framework-specific, no-go lists.

4. Missing the YAML frontmatter — The --- block at the top is required. A CLAUDE.md without frontmatter may silently fail to load.

Quick Migration Checklist

• Create CLAUDE.md in your project root
• Set alwaysApply: true for global rules
• Copy critical .cursorrules content into CLAUDE.md
• Split domain rules into separate .claude/rules/*.md files with globs
• Delete .cursorrules or rename to .cursorrules.bak
• Run a Claude Code agent task and verify rule enforcement

Why This Matters for Claude Code Users

Cursor's .cursorrules deprecation is quiet and undocumented in most tutorials. If your Claude Code agent keeps ignoring your rules, this is almost certainly why. Claude Code's CLAUDE.md system is more transparent and powerful—use it right.

Source: dev.to