Cursor Docs Update - We want your feedback!

[jdvmi00]

No information about notepads.

[ericzakariasson]

added back now: Cursor – Notepads

[ericzakariasson]

thank you, updated now!

[ericzakariasson]

we currently have this: Cursor – Ignore Files

more changes coming soon, we’ll make sure to flesh out the docs at the same time

[nick2]

Custom documentation can be referenced only from Cursor instance where it was created. This is a critical issue for teams, which must be addressed in docs. Sending images as context files works only once per chat or composer session - I assume it is a limitation of LLM in the background, but it also must be explained. Cursor settings like notes and rules are not synchronised between Cursor instances - please make this statement in bold.

[kaandok]

Yes, which is good. Now, if only we could get Cursor Tab to respect those, it’d be just great.

[SlippyDong]

The Model Context Protocol documentation could be improved upon. Adding a server is not as easy as it looks and the only way to debug the issue is by opening cursor’s devtools to figure out why “No tools are found”.

This error could mean the server couldn’t be started due to missing .env keys or the response from the server is different from what cursor expects. Even if tools are found because they’re available in the setRequestHandler, they may fail to work when the agent tries to use it because the response is using a different format from what the agent expects.

[Meh-S-Eze]

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?

2. Rule Management

• Best way to handle rule conflicts?

• How to manage rule dependencies?

• Recommended file organization?

3. 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

• Rules for AI

• My MDC Best Practices

• Rule File Change Management

---

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

[Agnos]

Where did the Gemini go from the list of models?

[KamilTheDev]

You also need to update this on the homepage:

IMO you should also put an asterisk next to “Unlimited slow premium requests”:

It’s more like you get a few extra slow requests, until it becomes a 2 minute wait per each message, rendering it unusable.

As users have said:

@SalaciousCarrot

However, from a user’s perspective, that distinction isn’t obvious. The way the subscription is presented—“500 fast, unlimited slow”—implies that unlimited calls are a fundamental part of the service, not an extra or a temporary fallback. Naturally, users interpret their subscription as providing unlimited usage, with the only tradeoff being speed.

This difference in expectation leads to frustration when users discover that the slow pool is so slow that it’s practically unusable.

Slow Request Hobbies

I’ve started learning how to crochet while I wait for my slow requests to finish, I’m almost done with a sweater I started this morning. What about you guys?

[codekiln]

@ericzakariasson

we’d love to get your feedback on it

• what is missing?
• what can we improve?
• anything we should remove?

want to make sure we cover as much as possible and is useful!

A number of undocumented or under-documented features

Right now it seems like the “actual” docs are on twitter and in forum posts. For example, I learned about Summarized Composers from your tweet (thanks!) x.com

- this isn’t in the docs according to the search:

Another example: what exactly are the rules for .project/rules? Can they be recursively included in directories so we can use git submodules to bring common rules in? Admittedly, this feature is nascent, and the docs reflect that…

Recommendation: adopt Diataxis technical documentation framework

I’d love to see the docs follow Diataxis framework - https://diataxis.fr/ - right now the cursor docs are fairly lacking when it comes to the top / Action portion of the stack (tutorials, how-to guides) as well as the Understanding / Explanation quadrants:

Consider creating “extended” docs or supporting a community project to create an unofficial docs site

• I’d love to see an agential application that crawled the web to assemble the cursor docs. Build something like dzhng/deep-research → Diataxis documentation generator.
• I understand if for legal reasons this sort of thing couldn’t be the “official” documentation, but it would be SO helpful to the community. I don’t want to spend time on social media just to learn Cursor.

[ericzakariasson]

incredible feedback, thank you!

going forward, we really want to spend more time on

• language & framework guides
• best practices
• cookbooks (started collecting some here a lot to cleanup, open to contributions!)

i’ll make sure to add the missing @-symbols

[T1000]

Semantic Descriptions: Each rule can include a description of when it should be applied

the word ‘can’ here should be MUST as so many people struggle to understand why the rules are not picked up.

Additionally its actually not clear as follows:

Automatic Attachment: Rules can be automatically included when matching files are referenced

Who references matching files where to get the rules to work? its supposed to be the description that declares when which rule is used per docu and Cursor team comments in the forum. lots of users are confused with so many threads here.

[erlebach]

Here are a few suggestions for enhance Cursor:

1. Each reply form the LLM in chat or composer should list the language model used in the reply. Why? Because if I switch LLMs during a conversation, the LLM changes, but there is no record of the previous LLM used.
2. Each chat should track the LLM used separately. Currently, when I change LLM in a new conversation in chat, and then return to a previous chat conversation, it is the new LLM that is selected, rather than the last LLM used in the previous chat thread.

[mazeincoding]

100% agree

[testacode]

New user here. I’ve been working in development for 15 years, mostly on the frontend side. I really like the agent/context feature—it’s a game-changer. It would be great to have more documentation on configuration rules and maybe additional examples for different languages with the proper format. Some parts feel unclear, and more guidance would definitely help.

[codekiln]

@erlebach

Here are a few suggestions for enhance Cursor:

1. Each reply form the LLM in chat or composer should list the language model used in the reply. Why? Because if I switch LLMs during a conversation, the LLM changes, but there is no record of the previous LLM used.
2. Each chat should track the LLM used separately. Currently, when I change LLM in a new conversation in chat, and then return to a previous chat conversation, it is the new LLM that is selected, rather than the last LLM used in the previous chat thread.

I like these suggestions @erlebach, consider raising them in a dedicated Feature Request thread since this thread is about improving the cursor docs

[sanjeed5]

Add a community highlights page about Cursor Setup and tips from the community

[bmadcode]

this is great feedback and really needs to be clarified in the doc - once I realized this was the case, improved so much the usage of the granular rules over the base rules file.