You wrote a rules file, and your AI coder ignored half of it anyway. Or you are running Cursor and Claude Code side by side, keeping two rules files that say nearly the same thing, and quietly wondering which one is even doing any work. I spent about two years on Cursor writing rules, then moved my whole setup to the Claude Code and Codex command lines, and the part nobody tells you is that the rules were never really about Cursor. They are a conventions file, and a conventions file is portable.
Here is the short version. If you only use one tool, use that tool’s native rules: Cursor Project Rules in .cursor/rules/ for Cursor, a CLAUDE.md for Claude Code. If you use more than one AI coder, keep a single plain-text conventions file at the repo root as your source of truth and stop maintaining copies, because Cursor reads AGENTS.md and CLAUDE.md too. Cursor rules and CLAUDE.md are not rivals. They are the same idea, a project-scoped instruction set loaded every session, in two file formats.
On this page
What Cursor rules actually are in 2026
Cursor moved its rules system a while ago, and the old advice still floating around is why so many files silently do nothing. There is no single magic file anymore. Cursor supports four kinds of rules, and it also reads the plain markdown files the other tools use. The official Cursor rules docs are the reference; here is the version that matters in practice.
- Project Rules live in
.cursor/rules/as.mdcfiles, version-controlled with the repo and scoped to it. This is the current system. - User Rules are global, set in Cursor’s settings, and apply to every project.
- Team Rules are managed from the dashboard for an organization.
- AGENTS.md and CLAUDE.md at the repo root are read as lightweight, tool-portable alternatives.
Inside Project Rules, each file declares how it loads, and this is the setting people get wrong:
| Rule type | How it loads | Use it for |
|---|---|---|
| Always | Prepended to every request in the project | Two or three hard invariants only |
| Auto Attached | Fires when you touch files matching a glob | Framework or folder-specific rules |
| Agent Requested | The model pulls it in when the description matches | Situational guidance |
| Manual | Only when you @-mention it | Rare, on-demand playbooks |
Two traps account for most “my rule does nothing” complaints. The first is scope: a rule sitting in the repo is not the same as a rule in context, and an Auto Attached glob like *.ts only matches files in the root, so it never fires inside src/. Use **/*.ts. The second is format: a plain .md file dropped into .cursor/rules/ is ignored, because Cursor only reads .mdc files with a frontmatter header. The legacy single .cursorrules file at the project root still works, but it is superseded, and keeping it alongside .cursor/rules/ is a reliable way to get two sets of instructions fighting each other.
Cursor Rules vs CLAUDE.md: the honest comparison
Strip the branding and both are the same object: a project-scoped instruction set your assistant loads at the start of every session. Claude Code reads a CLAUDE.md from the repo root and your home folder; Cursor reads Project Rules and, per its own docs, a root AGENTS.md or CLAUDE.md too. Cursor’s own docs list AGENTS.md and CLAUDE.md as valid rule sources, which tells you the two systems were never meant to compete. What differs is the machinery around the file.
| Dimension | Cursor Project Rules | CLAUDE.md / AGENTS.md |
|---|---|---|
| Where it lives | .cursor/rules/*.mdc |
One markdown file at repo root |
| Scoping | Globs and four attach modes | Load order and import lines |
| Portable to other tools | No, Cursor only | Yes, read by Claude Code, Codex, Cursor |
| Team management | Dashboard team rules | Whatever your repo already does |
| Best for | An all-in Cursor team | Anyone juggling more than one tool |
The verdict is about how many tools you run, not which file is smarter. If you are all-in on Cursor, use Project Rules with globs and skip the legacy .cursorrules; the scoping is genuinely useful once a codebase is large and a Cursor team can share Team Rules from the dashboard. If you touch more than one AI coder, and most solo builders now do, keep your conventions in one CLAUDE.md or AGENTS.md at the root and let every tool read that. Maintaining a .cursor/rules/ set and a CLAUDE.md that say the same thing is exactly how they drift apart. I keep one file.
The conventions file I actually run
Rules people share online are usually generic (“write clean code,” “add tests”). That is precisely the kind of line an assistant nods at and then ignores. The ones that hold are specific and mostly negative: they name the thing you keep having to undo. This is a trimmed version of what my sessions actually start with. It works as a CLAUDE.md as written:
# Working conventions
- Be concise. Lead with the answer, then the reasoning if I ask.
- Before writing code that reads a database or an API, confirm the exact
field names exist in that collection or response. Never guess a field.
- Hand file exploration and long reads to a subagent, so this session
keeps its context.
- Never run the dev server or a build unless I ask.
- Web-search for current library docs before using an unfamiliar API.
- Use the framework's Link and Image components, never a raw anchor or img.
- Ask before executing a script. Activate the venv before any Flask command.
- Reuse existing components and the branding tokens. Never hard-code a color.
- No hover effects on non-interactive elements. shadow-md is the ceiling.
- Do not add log statements unless I ask.
- Never read or print the secrets file. Load values through the injector.
To use the same file as a Cursor Project Rule, drop it into .cursor/rules/conventions.mdc with a frontmatter header on top, which is the step people miss:
---
description: Working conventions
alwaysApply: true
---
Before you paste your own file anywhere, run it through the free CLAUDE.md analyzer I built. It scores the file out of 100, flags rules that are vague or that contradict each other, and runs in the browser so nothing gets uploaded. Most files it sees are too long and too polite; the fix is almost always to cut.
Keep the always-on part short. Every always-on rule is prepended to every request, so a bloated file is a token tax you pay on turns that never needed it. A good target is under about two hundred words in the always tier, with everything situational moved to Auto Attached by glob in Cursor, or split into an imported file in a CLAUDE.md. If you want working examples to start from rather than a blank file, I keep 23 of my own skills and agents public at locul.ai/skills, installable in Claude Code with one command.
Why your rules get ignored, and the three fixes
The most common complaint about rules, in both camps, is that the model acknowledges a rule and then breaks it and apologizes. That is not a bug you can configure away, and understanding why saves a lot of wasted effort.
A rule is context, not a constraint. Cursor and Claude both read your rules as a strong suggestion that competes with the live request and the conversation so far. When the immediate instruction pulls one way and a rule pulls the other, the request usually wins. The fix is not more rules, it is fewer: put the two or three you cannot compromise on at the top, and verify the output rather than trusting that thirty rules all held.
It is in the repo, but not in context. This is the glob problem from earlier plus its cousins. If a rule only needs to apply to your API layer, attach it to **/*.ts under that folder rather than making it Always. If it is a .md in .cursor/rules/, Cursor is skipping it because it is not .mdc. A rule that never loads is indistinguishable from a rule that gets ignored.
The file is too big to respect. Past a certain length the model treats a rules file as background noise, and you are paying tokens for all of it on every turn. Cut anything generic, fold near-duplicates together, and demote everything that is not truly always-on. A tight file that gets followed beats a comprehensive one that does not.
Keeping two AI coders on the same conventions
I do not run Cursor anymore. I moved to Claude Code for most work and Codex for the rest, both from the terminal, and I wrote up why in Cursor vs Claude Code. But the problem in the title is real, and it did not go away when I dropped Cursor: I still run two AI coders, and they have to build the same way.
The answer is one source of truth. My conventions live in a root file both tools read, a CLAUDE.md for Claude and an AGENTS.md carrying the same content for Codex, rather than a separate rules set per tool that slowly diverges. I ran a .cursorrules file for about two years and the rules transferred to CLAUDE.md almost unchanged, because they were never really about Cursor. That is the whole case for keeping them portable.
The one rule I enforce with actual machinery rather than words is secrets. My credentials sit in a single local file of names and descriptions, and a small injector loads the real value into the process at run time so the key never enters the model’s context. It is the one guardrail I deliberately built, and it is what lets the AI run unattended on a schedule without ever seeing a secret. Everything else in the file is a convention; that one is a wall. If you want the rest of that setup, the schedule and the runner script, it is in how I run a business on Claude Code.
FAQ
Do Cursor rules and CLAUDE.md conflict if I have both?
They can. Cursor reads both, so if a .cursor/rules/ file and a CLAUDE.md give different instructions, the model gets mixed signals and picks unpredictably. Keep one as the source of truth. If you use more than one tool, make that the root CLAUDE.md or AGENTS.md and let Cursor read it.
Should I use one big rules file or split into many?
One file is fine for a small project. Split once it grows, but split by scope, not by whim: a short Always file for invariants, and Auto Attached files keyed to the folders they govern. The goal is that any given turn only loads the rules it needs.
Why does Cursor ignore my .cursorrules file?
Usually because it is not being loaded the way you think. Check that the file is .mdc if it lives in .cursor/rules/, that any glob uses ** to reach subfolders, and that you do not have a legacy root .cursorrules fighting the newer directory. And remember a rule is a suggestion, so a long one competes with the request.
Does AGENTS.md work in both Cursor and Claude Code?
Yes. AGENTS.md is the emerging shared standard, and both Cursor and Claude Code read a root AGENTS.md or CLAUDE.md. That is exactly why keeping your conventions in a plain markdown file is the portable choice when you run more than one assistant.
Do rules even matter now that the models are better?
They matter more for consistency than for correctness. A strong model writes good code without rules; it does not write your code, in your conventions, without them. Rules are how you stop every session from re-deciding your folder structure, your component library and your naming.
Where this comes from
I build and run eight products on my own, and the back office runs on Claude Code schedules, so I have written rules for Cursor, Claude Code and Codex on real work rather than demos. I ran Cursor for about two years before moving to the command-line tools, and the conventions file above is a trimmed copy of what my sessions actually start with today. The comparison reflects what I keep in one place now and why. The free CLAUDE.md analyzer and the 23 skills are part of Locul, built to plug into this exact setup. Pick the three rules you cannot compromise on, put them at the top of one file both tools read, and delete the twenty that were quietly being ignored.