[Bug] Rules in /rules folder require undocumented .mdc format and special save process

[Meh-S-Eze]

Title: [Bug] Rules in /rules folder require undocumented .mdc format and special save process

Description
The Cursor documentation suggests that placing files in the /rules folder will automatically make them available as rules. However, there are two undocumented requirements that cause confusion:

1. Files must use the .mdc extension
2. Files require a special save process that only works by closing Cursor entirely

Current Behavior

1. Regular files placed in /rules folder are not recognized as rules
2. .mdc files cannot be saved through normal save commands
3. Saving .mdc files requires:
   • Closing Cursor completely
   • Responding to “Unsaved Changes” prompt
   • Selecting “Override” option
   • Reopening Cursor

Expected Behavior
Based on current documentation:

• Any properly formatted rule file in /rules should work
• If .mdc is required, this should be documented
• Saving should work through normal editor commands
• If override protection is intended, it should be handled within the editor

Steps to Reproduce

1. Create /rules folder
2. Add a rule file (without .mdc extension)
   • Not recognized as a rule
3. Change to .mdc extension
4. Try to save normally
   • Changes don’t persist
5. Must close Cursor entirely to trigger override prompt

Workaround Documentation
We’ve documented the current required process in rule_creation_guide.yaml:

rule_file_creation:
correct_process:
steps:
1: “Create your new .mdc rule file”
2: “Add your rule content”
3: “Attempt to close Cursor completely”
4: “Wait for ‘Unsaved Changes’ override prompt”
5: “Select ‘Override’ option in the prompt”
6: “Allow Cursor to close”
7: “Reopen Cursor to see changes”

Impact

• Users waste time trying to create rules that won’t work
• Undocumented extension requirement causes confusion
• Unintuitive save process disrupts workflow
• Potential for lost work if special save process isn’t known

Environment

• Editor: Cursor
• File Type: Rule files in /rules directory
• Action: Rule creation and modification

Additional Context
This was discovered while trying to create a rule system following Cursor’s documentation. The workaround process was found through trial and error, but this should either be:

1. Documented clearly if intended behavior
2. Fixed to match documented behavior
3. Made more intuitive with in-editor override handling

[danperks]

Thanks for the detailed report! I’ll make sure this gets added to our docs at Cursor – Rules for AI to help other users

In the meantime, you can use the command palette (Cmd/Ctrl + Shift + P > New Cursor Rule) which handles all this automatically and is the recommended way to create rules

[shoelessness]

Hopping in here to say I like getting the Cursor Agent to write + update rules as part of the development process. Currently the workaround is to copy the contents that the agent prepares, then paste them into the rule file in another editor.

Also worth noting that the “Read file” tool thinks that it sees the contents the agent “applied”, but often if I run a cat on the file itself, it will only contain a % character.

[KirkPX]

@shoelessness

Hopping in here to say I like getting the Cursor Agent to write + update rules as part of the development process. Currently the workaround is to copy the contents that the agent prepares, then paste them into the rule file in another editor.

Came here to echo this. Very much looking forward to this fix being rolled out. Thanks for all the hard work team!

[Meh-S-Eze]

If you didn’t see it this is a pretty powerful work around. [Bug] Rules in /rules folder require undocumented .mdc format and special save process - #2 by danperks

Also if you search for a GitHub airules it has a tool that is another approach.

[T1000]

Indeed there is still a lot of friction when creating rules and lets be honest not every developer wants to play around with an UI that has issues when a direct file editing approach works better. however there are still issues with documentation even for manual editing. happy to elaborate further.

[kevinold]

I found a temporary solution for creating MDC rules by instructing the agent to “Create the files under .cursor/rules as regular markdown files with the complete output, including frontmatter” and it worked.

I then asked it for a command line script to rename *.md files to *.mdc

[hongfeiyang]

Pls fix this now my cursor agent cannot even make edits to rules, it always go with ‘no changes made’ even though it made some changes, and will stuck in a loop of retrying different ways. Really frustrating

[Meh-S-Eze]

Yeah I found this to work for me part of the time. I have started having it populate rules initially in a proposed rules folder then use terminal commands to delet the old rule and move the update via terminal to the correct folder and change them to .mdc this works really well for me. There are a few tools out there on GitHub that kind of do this, but I found that then I just spent too much time working on my rules and not actually projects

[erik.aybar]

This is painful. I’m working to help others adopt Cursor more and Cursor rules and now it seems Cursor rules themselves are broken and we aren’t able to use Cursor to help create or edit Cursor rules.

[rdeman]

Work around: tell agent to insert a meta rule: update Cursor rule file by direct manipulation via Terminal editing, avoid using internal Cursor tools. After update, confirm rule file gas been correctly updated by dumping the rule file to terminal and read out out directly

Its kinda hacky (you’ll see Agent fail a couple of times, generating new line characters wrong and stuff, but eventually it learns to do it right) not ideal but does the job for now