Cursor Docs Update - We want your feedback!

Discussion  Featured Discussions
28

Cursor Rules Documentation Feedback

've been experimenting with different approaches to .mdc rules, and wanted to share some thoughts about documentation and actual usage patterns. Also version control doesn’t seem to work on .mdc I documented a bug report which is included in referenced links.

Documentation vs Reality Gap

Based on my experiments and community discussions, there’s quite a difference between the docs and actual behavior:

  • Docs suggest any file works in .cursor/rules

  • Reality: Needs .mdc extension specifically

  • Format flexibility unclear (YAML vs XML vs JSON?)

My Current Experimental Approach

1. Rule Development Flow

I’m trying a staged approach (not sure if this is “correct”, but it’s working for me!):


ideas/000-*.yaml → draft/100-*.yaml → final/100-*.mdc

2. Naming Convention

Using a numbered system for organization:


Core Rules: 001-099

Integration Rules: 100-199

Pattern Rules: 200-299

3. MDC Structure Experiments

Currently testing this format:


---

name: Chat Interface Rule

version: "1.0"

globs:

- "src/**/*.py"

triggers:

- file_change

---

# Core Principles

[markdown content here]

Documentation Improvement Suggestions

1. Format Clarity Needed

  • Explicitly state .mdc requirement

  • Clarify supported formats (YAML/XML/JSON?)

  • Show complete working examples

  • Document format mixing (YAML headers with markdown content)

2. Known Issues Section

Some quirks I’ve encountered:

  • File changes sometimes vanish

  • Need to close Cursor completely to save

  • “Unsaved Changes” override process

  • Restart required for changes to take effect

3. Best Practices Guide

Would love to see:

  • Numbering system for rule ordering

  • Rule organization patterns

  • Creation methods (Settings UI vs direct file)

  • Format recommendations

Open Questions

  1. Format Standards

  • Is YAML the preferred format?

  • When should we use different formats?

  • How do mixed format files work?

  1. Rule Management

  • Best way to handle rule conflicts?

  • How to manage rule dependencies?

  • Recommended file organization?

  1. Development Flow

  • Is the staged development approach (ideas → draft → final) useful?

  • Should we standardize rule development patterns?

  • How to handle rule versioning?

Suggested Documentation Structure


1. Getting Started

- File requirements (.mdc extension)

- Basic structure

- Creation methods

2. Rule Organization

- Numbering system

- Rule types

- File hierarchy

3. Known Issues & Workarounds

- Save process

- Change management

- Troubleshooting

References

Would love to hear from the Cursor team about these suggestions and whether my experimental approach aligns with intended usage! :blush:

4 Likes