The application itself and its help files describe .cursor/rules/ as the canonical rules source.
Yet the only file that the Rules setting can actually reference is CLAUDE.md?
This is extremely strange. The documentation from “Learn about Rules” says .cursor/rules/ is the canonical rules path (Rules | Cursor Docs).
In “Rules, Skills, Subagents”, the only file that can be listed in the Rules section is CLAUDE.md.
If you delete CLAUDE.md from the Rules section, it doesn’t just remove the reference, it deletes the actual file itself (which is weird and noteworthy because “remove this setting config” usually does not mean “delete this file” but is otherwise tangential to this request).
If you click “+ New” you can choose from “User Rule, Project Rule, Import from GitHub/GitLab”. But you can NOT ref your actual rules folder or any files in it.
Why does CLAUDE.md get special treatment over Cursor’s own defined location for rules?
Why can’t I point the Rule section at .cursor/rules/{filename}? Why does it HAVE to be named CLAUDE.md, and cannot be added manually if removed?
Why is Cursor privileging a specific file from a specific provider instead of using their own .cursor/rules/ path they’ve already documented?
I waffled on filing this as a bug report vs a feature, but ended up in feature because, for some inexplicable reason, it seems like this was on purpose.
Thanks for the write-up, hope we can clear things up!
.cursor/rules/ is fully supported and is still the canonical spot, and CLAUDE.md isn’t getting special treatment. The Rules list just shows whatever rules exist. So if you’ve got a CLAUDE.md at the root and nothing in .cursor/rules/ , then CLAUDE.md is the only thing it can show. Drop an .mdc in .cursor/rules/ (or hit New → Project Rule, which writes one for you) and it shows up right alongside it. I tested with both a .cursor/rules/*.mdc and a CLAUDE.md and they list side by side
The CLAUDE.md support is compatibility, not preference. Cursor also reads root-level memory files (AGENTS.md , CLAUDE.md , old .cursorrules ) so projects built for other tools work without converting anything. It’s on top of .cursor/rules/ , not instead of it.
What’s your project’s file structure look like? If something isn’t matching here, would love to see a screenshot.
Thank you Colin, I appreciate your response and suggestions.
I use .cursor/rules/rules.md, which doesn’t show, while CLAUDE.md does appear, so I misread the situation as a preference.
As you can see I have 3 files under /rules but none appear under the Rules settings area. (The non-rules.md files should probably be reorganized, rewritten, or decomissioned they’re pretty old but still fairly valid.)
Does this mean that I have the files in the wrong location? Or does it mean I should decompose them from monolithic .md files into individual rules in their own .mdc files?
I’ve been considering decomposing or rewriting them so that I can ref individual rules easier and compose them or chain them in commands but haven’t taken that step yet, so maybe it’s time.
On another note, sometimes agents refer to the rules without being fed them, as if they’re automatically populated into the agent context (or otherwised indexed/referenced in the agent’s repo view) but most of the time agents act oblivious unless I shove the file in their face, so it’s not clear if the rules are being provided to the agent automatically.
Rules under .cursor/rules/ need to be .mdc files rather than .md. That’s probably why they aren’t being picked up! Nothing should really need to change here except for the extension.
Our docs show a bad example of an .md file directly under .cursor/rules. I’m fixing it.
On the topic of when rules get applied, have a look at our docs on rule anatomy!
