The documentation gives this example for rules structure:
.cursor/rules/
react-patterns.mdc # Rule with frontmatter (description, globs)
api-guidelines.md # Simple markdown rule
frontend/ # Organize rules in folders
components.md
However, from my testing (using just .mdc files) this causes Cursor to read none of the rules when this is a top level folder in a multi-root workspace.
(I didnât test with plain .md files as that just adds more confusion).
The mixture of subdir and non-subdir rules works ok with single folder workspaces. But with multi-root if Cursor encounters this mixture of sub-dir and non-subdir rules it will simply read none of them at all.
On a side note there have been some inconsistencies with the regexes for the âcreate ruleâ skill and what Cursor actually uses to read it in (and the documentation is another variable again). However the fact it seems to find nothing suggests this might be causing a more fatal error of some kind rather than just a regex bug.
Steps to Reproduce
For a single root workspace:
Create the rules structure from the description (use only .mdc files) and ask Cursor âwhat rules are in effectâ.
Add another folder to the workspace to make it a multi-root, reload cursor, and ask again.
Repeat for each of the examples.
Expected Behavior
All rules files should be in effect in all scenarios.
Despite being effectively the same. The multi-root workspace will only read rules if they are in a â.cursorâ directory as an immediate child, and only if the rules are all in subdirs under ârulesâ, or all in a flat list under ârulesâ. This is in contrast to the single folder workspace behaviour.
Hey, thanks for the report. Looks like this is an edge case that slipped past the previous multi-root fixes. The documented mixed layout (files + subfolders in .cursor/rules/) should work, but something breaks specifically during multi-root detection.
What works in multi-root:
All rules in subfolders: .cursor/rules/react/*.mdc, .cursor/rules/api/*.mdc
All rules flat: .cursor/rules/*.mdc
What breaks:
A mixed layout, some files in the root plus some in subfolders
I reproduced this myself on macOS, so itâs not Windows-specific.
Workaround: move all rules into subfolders (even single-file folders). That immediately fixes rule loading in multi-root.
Your detailed repro steps were really helpful, thanks for documenting the exact combinations that work and the ones that break.
@deanrie Is this intended as a temporary workaround or the final decision? I frequently rely on a mixed layout within .cursor/rules. In full-stack work, most developers operate across multiple domains at once: UI, API, and infrastructure. We need the flexibility to organize rules at both the component level and the overall project level.
Because the LLM is a conversational tool, we need to engage with it at both levels. Frontmatter is one of the key differentiators of Cursor compared to other products, so limiting mixed-layout usage feels like a step backward. Is there a plan to fully support this pattern in multi-root?
The subfolder workaround is temporary and not a final decision. Mixed layouts (files plus subfolders in .cursor/rules/) are supported per the docs, and we expect them to work in multi-root the same way they do in single-root.
This is a known bug and the team has flagged it. Thereâs no ETA for a fix yet, but your feedback helps us prioritize it, especially since multi-root plus mixed rules is a common setup for full-stack work.
For now, the subfolder workaround is the most reliable option. You can keep top-level project rules in a generic subfolder like .cursor/rules/project/ to keep a similar structure.