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

Bug Report
1

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
2

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