Definitive Rules

Hi All

I am a massive fan of Cursor, recently ditched erm a surfboard style ‘thing’ in favour of Cursor -
However (and I want to relay I am not hating on cursor one bit)

What REALLY frustrates me is the incomplete documentation on how ‘rules’ work.

I am in a mess now, I originally started with just a few rules which I ported over from surfboard - worked almost perfectly IMO - No major issues.

Then I read in the forum and on some subreddits about cursorrules - I looked at the other subredits and the various directories online - all claim to be something astonishingly good.

Cursor has 2 types of rules and everyone and their dog knows a ‘trick’ or a ‘tip’ or most recently a whole new functionality/app to make Cursor obey rules, whether that is just fluff for their own endgame (clicks/traffic etc) or is genuine i have absolutely no idea.

I am yet to find a transparent article/document that lays out how these should be implemented or used. Varying opinions (and they are only opinions unless they come form the Cursor Team) about Text/YAML/JSON/MD etc etc

Can someone please return my sanity and explain:

  1. Why do we need Rules for AI and Cursorrules
  2. Which rules take precedence, how does it deal with possible conflict
  3. What format is optimal for Cursor to absorb the rules
  4. Do we still have to @cursorrules in the initial prompt - if so what is the point in having .cursorrules and not just a normal rules file if we still have to prompt.
  5. What benefit does having .cursor instead of just a rules.md
  6. This one ‘shot’ is for someone from cursor to reply to - why do you lack on formal documentation on this subject? surely you cant disagree that the provided information isn’t even remotely enough for someone to be able to use your product efficiently. The fact there are many many subreddits and even here in the forum about this subject - why cant we have some concrete docuemntation.

Desperately looking for my sanity back

Thanks

Rob

4 Likes

Eagerly looking to hear responses from this, especially if we get some official response from Cursor. I’m much in the same boat as you. I’ll add my thoughts for some of the items you brought up.

ONE. I think the biggest use case is providing the AI with more context about your project. I work on a massive codebase and so most of my .cursorrules is explaining the “high level view”. Secondary purpose is customizing how the AI agent behaves; I tell mine to be concise and not give examples unless I explicitly ask, in an effort to be more efficient with my context window. (I put this in Rules for AI section).

THREE. No idea, but mine is in YAML format and it seems to work well

FIVE. I don’t think so. I never @ it and it seems to be working. A good idea is to add something like Start every message with "Howdy, partner!" to the rules file to make sure it’s working.

As for the lack of documentation… I think it’s because we’re in such a crazy wild wild west era of rapid AI expansion. No one really understands the capabilities or best practices and every few days those things change as more powerful models are released. Developers using Cursor are gonna experiment and the “best practices” will change a lot depending on your use case (massive existing codebase, constant new small projects, etc).

2 Likes

Also, with the newest update there is now the option of a .cursor/rules directory with multiple rules:

Users can write several repository-level rules to disk in the .cursor/rules directory. The Agent will automatically choose which rule to follow.

I’d very much like to know if/when we should do this instead of one single .cursorrules file. And what the format of these multiple rule files should be…

Source Changelog | Cursor - The AI Code Editor

1 Like

I feel this is now rule overkill - just give us one not 2 and now a directory

I do think there is a need for the two we already had.

  1. .cursorrules is for providing additional context and specific rules about the current repository. Very important if you work on multiple different projects with Cursor.
  2. Rules for AI is for customizing how the Agent behaves, general rules for how it should write responses and generate code, etc. Basically, any rules that are not repository or project specific. I like this setting otherwise I’d have to repeat a lot of these same rules in each .cursorrules file.

But this new rule directory definitely feels like overkill.

1 Like

Thank you for your experienced feedback - how exactly did you get tot he position where you are happy with both sets of rules and confident that they are being followed? I know the first few rows of AI Rules are being met as the first rule is always start with “Hi Rob” - so i know it is looking at some of the rules.

Additionally - can you give me an example of both sets of rules?

I have tried many tests, it seems that if claude is experiencing high load, cursor won’t scan the .cursorrules. I also find that negative rules work better, don’t do this don’t do that kind of thing. I have also found that overengineering the project- doesn’t actually help, tried this many times, quiz on astro to suprabase, atlassian status page, regular website full layout.

I start the coding session by asking it to slowly read and summarize the cursor rules file. If it fights me on dates and new versions- I also include .md full versions of Astro 5 documentation and Tailwind 4- they all changed (if you are doing svelt- include everything. I don’t trust the docs repo in the settings anymore.
My rules now are just getting it to realize it is january 2025 and tailwind 4 is out node is on v22. IF I can get it to recognize that then I will code, if not try to use another model, or come back later.

I never know for sure, but in general I feel that the AI seems to know what’s going on, and its responses and suggestions are good and helpful. Occasionally it does seem to be confused or “missing the big picture”, in which case I’ll gently correct it and @ the relevant files to get it back on track.

In my “Rules for AI” I tell it to use humor, sarcasm, and emojis whenever possible, so it’s pretty easy to tell if it’s at least reading that :joy:

  • I almost exclusively use Chat sidebar mode, not Composer. I mostly work with a massive existing codebase and don’t trust Composer with it
  • I have only tried 4o and claude-3.5-sonnet models, and find Claude to be significantly better
  • Even with good rules, good prompting is still important. I keep each chat focused to a specific task, and take time to write up a detailed initial prompt covering the task we’re working on

Sure! Here’s my Rules for AI

And here’s my .cursorrules file. I redacted some of the info but this should give you the general idea. My goal was to help the AI understand the codebase from a “high level overview” perspective, so I don’t have to constantly explain the big picture.

# Core technology stack and versions
ruby_and_rails_usage:
  version: 'x.x.x'
  framework: 'x.x'
  syntax_and_formatting:
    follow_ruby_style_guide: true
    single_quotes_preference: true 
    use_expressive_ruby_syntax: true

# Code organization and patterns
code_style_and_structure:
  concise_idiomatic_ruby: true
  rails_conventions_and_best_practices: true
  proper_programming_patterns: true
  iteration_modularization_over_duplication: true
  follow_rails_mvc: true

naming_conventions:
  file_names: snake_case
  variable_and_method_names: snake_case
  class_and_module_names: CamelCase
  follow_rails_naming_conventions: true

# Key architectural patterns
key_conventions:
  follow_restful_routing: true
  use_concerns_for_shared_behavior: true
  implement_service_objects_for_complex_logic: true
  use_background_jobs_for_time_consuming_tasks: Sidekiq

# Domain terminology and concepts
terminology:
  '■■■': 'the name of the company that makes YYY'
  'YYY': 'the name of this application, a <general description here>'
  'admin, superadmin': 'employee of ■■■ with top-level permissions'
  'business': 'a business entity and customer of ■■■ using YYY software'
  'staff, staff member': 'employee with varying roles within a business'
  'client, person': 'a customer of a business'
  'service, class, appointment, course': 'core offerings of a business. Appointment, Class, and Course are children of the Service model'
  'event, event occurrence': 'overall session and individual instances'
  'visit': 'ties a person to an event occurrence, representing booking and attendance'

# API structure
api:
  version: 'v2'
  routing_conventions:
    desk: '/api/v2/desk'
    front: '/api/v2/front'
  core_api:
    desk: 'used by staff members'
    front: 'used by clients'
  controllers:
    base_controller: 'app/controllers/api/v2/base_controller.rb'
    desk_base_controller: 'app/controllers/api/v2/desk/base_controller.rb'
    front_base_controller: 'app/controllers/api/v2/front/base_controller.rb'

# Key models and relationships
models:
  core_models:
    - Person
    - Business
    - Event
    - Service
    - Visit
  relationships:
    business:
      has_many: ['staff_members', 'clients', 'services', 'events']
    service:
      children: ['Appointment', 'Class', 'Course']
    event:
      has_many: ['event_occurrences', 'visits']
    person:
      polymorphic_roles: ['client', 'staff_member']

# Documentation requirements
documentation:
  class_comments: required
  method_comments: required
  complex_logic_comments: 'add inline comments to clarify key points in complex methods'

# Internationalization
i18n:
  framework: 'i18n'
  location: 'config/locales'
  requirement: 'all user-facing strings must use i18n keys'

One more thing: I used Chat to make this .cursorrules file. Originally we had a very long .cursorrules file, basically taking every best practice and idea from various threads here and on Reddit. It seemed to work okay but was very long.

Using Chat to revise it was a fairly long conversation, but it boiled down to:

  1. Asking AI what the purpose and best practices of the .cursorrules file is
  2. Asking AI to review the current file, look at our codebase (important to tag @codebase), and propose revisions to the file. Set priorities of “including all relevant information while keeping the file as concise as possible”
  3. I made some additional suggestions (mostly improving some of the business and model info included)
  4. Iterated a few times till I was happy with it

I then did the same thing for creating a .cursorignore file (specifying what to exclude from indexing). This seemed to make a huge difference in the quality of responses when using codebase contexts (either @codebase or cmd+enter)

two things.

  1. Deepseek R1 gives you some interesting rules suggestions if you go back and forth with it.
  2. Regarding why cursorrules and how they are thought of, this is kind of tangential but i remember listening to a Lex podcast with the cursor team which was a fascinating listen btw. They mentioned they use JSX to do prompting and I think that kind of influences how they though of this cursorrules feature. Transcript:

(00:44:43) And we have this one system internally that we call Preempt, which helps us with that a little bit. And I think it was built for the era before where we had 8,000 token contact windows. And it’s a little bit similar to when you’re making a website. You want it to work on mobile, you want it to work on a desktop screen, and you have this dynamic information which you don’t have. For example, if you’re designing a print magazine, you know exactly where you can put stuff. But when you have a website or when you have a prompt, you have these inputs and then you need to format them to always work, even if the input is really big, then you might have to cut something down. And so the idea was, okay, let’s take some inspiration. What’s the best way to design websites? Well, the thing that we really like is React and the declarative approach where you use JSX in JavaScript, and then you declare, “This is what I want and I think this has higher priority or this has higher Z index than something else.”

(00:45:56) And then you have this rendering engine in web design. It’s like Chrome, and in our case it’s a preempt renderer, which then fits everything onto the page. And as you declare, decide what you want and then it figures out what you want. And so we have found that to be quite helpful and I think the role of it has shifted over time where initially it was to fit to these small context windows. Now it’s really useful because it helps us with splitting up the data that goes into the prompt and the actual rendering of it. And so it’s easier to debug because you can change the rendering of the prompt and then try it on old prompts because you have the raw data that went into the prompt, and then you can see, “Did my change actually improve it for this entire eval set?”

Lex(00:46:45) So do you literally prompt with JSX?

Aman(00:46:48) Yes. Yes.

Arvid(00:46:48) Yeah. So it looks like react. There are components. We have one component that’s a file component and it takes in the cursor. Usually there’s one line where the cursor is in your file and that’s probably the most important line because that’s the one you’re looking at. And so then you can give priorities. So that line has the highest priority, and then you subtract one for every line that is farther away. And then eventually when it’s rendered, it figures out how many lines can actually fit and it centers around that thing.

Lex(00:47:17) That’s amazing.

Aman(00:47:18) And you can do other fancy things where if you have lots of code blocks from the entire code base, you could use retrieval and things like embedding and re-ranking scores to add priorities for you through these components.

Lex(00:47:30) So should humans when they ask questions, also try to use something like that? Would it be beneficial to write JSX in the problem or the whole idea is this should be loose and messy?

Arvid(00:47:43) I think our goal is that you should just do whatever is the most natural thing for you, and then our job is to figure out how do we actually retrieve the relative event things so that your thinking actually makes sense?

Lex(00:47:56) Well, this is the discussion I had with Aravind of Perplexity is his whole idea is you should let the person be as lazy as he wants. That’s a beautiful thing, but I feel like you’re allowed to ask more of programmers, right?

Arvid(00:48:14) Yes.

Lex(00:48:14) So if you say, “Just do what you want,” humans are lazy. There’s a tension between just being lazy versus provide more as be prompted… Almost like the system pressuring you or inspiring you to be articulate. Not in terms of the grammar of the sentences, but in terms of the depth of thoughts that you convey inside the prompts.

Aman(00:48:39) I think even as a system gets closer to some level of perfection, often when you ask the model for something, not enough intent is conveyed to know what to do. And there are a few ways to resolve that intent. One is the simple thing of having the model just ask you, “I’m not sure how to do these parts based on your query. Could you clarify that?” I think the other could be maybe if there are five or six possible generations, “Given the uncertainty present in your query so far, why don’t we just actually show you all of those and let you pick them?”

Lex(00:49:19) How hard is it for the model to choose to talk back versus generally… It’s hard, how deal with the uncertainty. Do I choose to ask for more information to reduce the ambiguity?

Sualeh(00:49:36) So one of the things we do, it’s like a recent addition, is try to suggest files that you can add. And while you’re typing, one can guess what the uncertainty is and maybe suggest that maybe you’re writing your API and we can guess using the commits that you’ve made previously in the same file that the client and the server is super useful and there’s a hard technical problem of how do you resolve it across all commits? Which files are the most important given your current prompt? And we’re still initial version is ruled out and I’m sure we can make it much more accurate. It’s very experimental, but then the idea is we show you, do you just want to add this file, this file, this file also to tell the model to edit those files for you?

(00:50:37) Because if maybe you’re making the API, you should also edit the client and the server that is using the API and the other one resolving the API. So that would be cool as both there’s the phase where you’re writing a prompt and there’s… Before you even click, “Enter,” maybe we can help resolve some of the uncertainty.

1 Like

Thank you for the extensive narration from the podcast - I think this may be one of those things where you have to be there to appreciate it, reading it honestly doesn’t make any sense to me. Do you have the link to the podcast please?

1 Like

WOW is all i have to say, either i’m just having a really lucky morning or YAML made a difference!? Below is what i made for Rules for AI - it worked perfectly with NO mess ups or overreach.

global_development_rules:
code_structure_and_organisation:
- “Follow a modular and organised file structure for all projects.”
- “HTML: Separate templates into reusable components (e.g., headers, footers, modals).”
- “CSS (BEM): Adhere strictly to the BEM naming convention: block__element–modifier.”
- “JavaScript: Divide logic into small, reusable modules and use ES6+ syntax.”
- “PHP: Use a clear MVC structure or templates to separate logic from presentation.”
- “Python: Follow PEP 8 standards and divide large scripts into smaller functions/classes.”

documentation_and_tracking:
- “Always have a project_plan.md. Create it if it does not exist and maintain it to track progress.”
- “Always keep a record of the latest action in updates.md. Create the file if it does not exist.”
- “Include meaningful comments to explain HTML structure, JavaScript functions, PHP logic, and CSS declarations.”
- “Each file should have a brief description at the top explaining its purpose.”

code_formatting:
- “Enforce consistent code formatting across all languages.”
- “HTML: Use 2 spaces for indentation.”
- “CSS/SCSS: Use 2 spaces and group related styles together.”
- “JavaScript/Python: Use 4 spaces for indentation.”
- “Format PHP code with PSR-12 standards.”

performance_optimisation:
- “Minimise HTTP requests by combining CSS/JavaScript files during production.”
- “Optimise assets by compressing images and using modern formats like WebP.”
- “Use lazy loading for images and videos.”
- “Optimise queries in PHP and Python by avoiding redundant database calls and using indexing.”

security_practices:
- “Sanitise user inputs to prevent XSS.”
- “Use prepared statements or ORM for database interactions to avoid SQL injection.”
- “Validate and escape output when rendering user-provided data.”
- “Validate external inputs in Python when handling APIs or file operations.”

responsiveness_and_accessibility:
- “Use a mobile-first approach for CSS.”
- “Follow accessibility standards, including ARIA roles and proper colour contrast.”
- “Add alt attributes for all images.”
- “Test responsiveness on various devices and screen sizes.”

version_control_and_deployment:
- “Commit changes frequently with descriptive commit messages.”
- “Use feature branches for new functionality and merge into the main branch after review.”
- “Include a .gitignore file to exclude sensitive and unnecessary files.”
- “Automate deployment pipelines where possible (e.g., using Git hooks or CI/CD tools).”

testing_and_debugging:
- “Perform cross-browser testing for all websites.”
- “Write unit tests for complex JavaScript, PHP, or Python functionality.”
- “Debug using browser developer tools or logger libraries.”
- “Use staging environments for final testing before production.”

standards_for_external_libraries_and_apis:
- “Minimise dependency on external libraries; only use lightweight, well-supported ones.”
- “Document any external library or API used, including its purpose and version.”
- “Ensure API calls have proper error handling and retries.”

environment_management:
- “Keep development, staging, and production environments separate.”
- “Use .env files to store configuration variables and avoid hardcoding sensitive data.”
- “Ensure all third-party dependencies are pinned to specific versions.”

tools_and_support:
- “Use linting tools like ESLint for JavaScript, Stylelint for CSS, and PHP CodeSniffer for PHP.”
- “Use Prettier for consistent code formatting across all supported languages.”
- “Follow a clear branching strategy like GitFlow.”
- “Target modern browsers but include polyfills for critical features in older versions.”

2 Likes

Those numbers are links to the timestamp on the youttube video

1 Like

Nice catch, it matches benchmarks where XML shows to be the best format for prompting as JSX is XML-like, Markdown second, raw text and JSON.
@bluepenguindigital has really good results with YAML as its a structured Markdown with less overhead than XML and it may be first in class when meeting context cutoff.

“This is what I want and I think this has higher priority or this has higher Z index than something else.”

XML

<rule>
    <condition>
        <priority>high</priority>
        <zIndex>higher</zIndex>
        <comparedTo>otherElement</comparedTo>
    </condition>
</rule>

YAML

rule:
  condition:
    priority: high
    zIndex: higher
    comparedTo: otherElement
2 Likes

The usage of multiple files and automatic usage of the right file is what is important. you do not want an extremely large .cursorrules file to be always used in the context of every chat and slow you down or confuse the LLM unnecessarily. lots of people face that

Thanks, but I have to ask where did this knowledge come from - as it isn’t in the cursor formal documentation. I am not saying you are wrong at all, it just seems to me and quite a fair few people that every other person has a tip or trick or a new way of doing this. Can you breakdown your explanation as int he current context of 1 “.cursorrules” file and 1 “Rules for Ai” it makes no sense.

I think it isn’t in Cursor documentation because they don’t know either. AI is advancing way too rapidly so we’re all figuring it out together.

Okay, that makes sense. I may give this a whirl.

Agree, I’ve always disliked XML because it feels very cluttered.

Its best to write just text or markdown.

The .cursorrules file should have general guidelines that are guiding overall behavior. For specifics use the new 0.45 capabilty to have multiple cursor rule files declared that are selected by best match.

While XML, yaml or json may work best for certain models. if you ever switch models you may have an issue if you align the rules format for a specific model.

e.g. Claude prefers XML but works well with Markdown too.
Dont waste tokens on fancy formatting like yaml. lol.

According to my observations, “rules for ai” is shared across different windows. It is included. Cursorrules are obviously project specific.

Hi All

So just a new point that has come up - after using the nice simple YAML rules and having really good consistent success - today has totally gone out of the window, its like dealing with a drunk baby whi ahs never seen the project - Can someone more experienced than I (@troehrkasse ? :slight_smile: ) explain have you experienced this before and how you deal with this this?