Mastering Cursor AI: A 5-Level Guide to Editor Rules

There are five distinct levels of rules in the Cursor AI code editor. You can access them by navigating to Cursor Settings and opening the Rules section. This is where you'll find your global code editor rules. Additionally, there are four levels of project-specific rules, which are stored within each project's repository rather than in your global settings.

Let's explore how these work.

Level 1: Global Code Editor Rules

First, let's start with the code editor's global rules. There's a large input field where you can define instructions that Cursor will prepend to every request you make. When you send a prompt, the editor doesn't just send your text to the model; it sends your predefined instructions first, followed by your prompt.

This is the perfect place to define your high-level preferences, such as the primary language you code in, your preferred methods, or coding styles you want to avoid. These rules apply across all your projects.

The main advantage of global rules is their persistence; they are added to every request automatically. The downside is that they are difficult to share with teammates. You should also be cautious with these rules, as every request will consume LLM tokens to process them. Overly long rules can sometimes reduce the quality of the output. While modern models have larger context windows, it's still a best practice to keep these rules concise.

For instance, you can include habits, information about README files, or common GitHub CLI instructions.

Project-Specific Rules: 4 Additional Levels

Below the global rules, you'll find the section for project rules, which offers four more levels of granularity.

How to Create Project Rules

There are several ways to create a new rule for your project:

1. The UI Button: Simply click the Add New Rule button and give your rule a name, like "Test Rule." This creates a new project-level rule, which is set to manual by default.
2. In-Chat Command: You can generate a rule directly from the chat. For example, you could type, "I would love to create a rule about your answers," and then use the /generate_cursor_rule command. The editor will generate a new rule for you, complete with suggestions from the LLM.
3. Manual File Creation: You can create a rule by adding a new .mdc file directly inside your project's .cursor/rules/ directory. As long as the file follows the correct format, it will function just like a rule created through the UI.

All these methods simply create a document with a special format. If you open one of these rule files in a text editor, you'll see a few lines of metadata at the top:

always_apply: true
run_type: always

This metadata controls how the rule is applied. Changing run_type to manual would set always_apply to false.

The 4 Levels of Project Rules Explained

Let's dive into the four types of project rules.

1. always

In any project, it's a good practice to create an initial index.mdc rule and set its run_type to always. This means the text in this rule will be included in every request for this specific project, much like the global code editor rules.

Here, you can provide an overview of the project, describe its main components, and highlight key areas you want the AI to remember. The key difference between an always project rule and a global rule is shareability. Since this file is part of your repository, you can share it with your team, allowing everyone to work with the same context.

Just like with global rules, keep these files concise to avoid unnecessary token consumption and potential degradation of response quality.

Note on Legacy Files: An older method involved using a .cursor-rules file. This still works but is now considered legacy. It's recommended to switch to the new .cursor/rules/ directory structure for managing always rules.

2. agent_requested

This rule type allows the AI agent to decide whether to apply the rule based on the context of the conversation. For an agent_requested rule to work effectively, you must provide a detailed description explaining when the agent should use it.

For example, you might have an image-optimization.mdc rule with the agent_requested type. If you then ask the AI, "Please optimize the image I will send you," the agent will see the rule's description and automatically apply it without you needing to mention it explicitly.

A Word of Caution: If you create too many agent_requested rules with numerous different descriptions, the agent might fail to recall the correct one, even when you expect it to. Always check that the rule appears in the chat interface. If it doesn't, you may need to add it to your prompt manually. It's often easier for the agent to remember rules at the beginning of a conversation, so consider starting a new chat when introducing new, complex tasks.

3. auto_attached

This rule type lets you create path-based patterns that trigger a rule only when you are working with files matching those paths.

For instance, if you store your articles in a content/articles/ directory, you can create a rule with a specific writing style that only activates when a file from that directory is part of the conversation's context. This is incredibly useful for separating concerns. You can have one set of rules for writing articles and another for coding Python scripts, or different rules for backend and frontend development.

4. manual

A manual rule is never automatically applied. You must add it to the chat yourself. These are perfect for storing longer, more complex instructions that you only need occasionally.

A great example is a detailed workflow for translating an article into multiple languages. When you're ready to translate, you can manually invoke the article-translation.mdc rule and instruct the AI to follow the procedure.

You can maintain a library of manual rules as a knowledge base for various tasks, such as connecting to a specific database, checking a data schema, or submitting a new URL to a search index. This keeps your primary context clean while giving you access to powerful, reusable workflows when you need them.

Team Collaboration and Rule Management

How should teams manage rules in large projects?

A good approach is to allow everyone on the team to create rules, with the shared understanding that they should be kept concise. Then, on a regular basis—perhaps once a month or every couple of weeks—the team should conduct a refactoring session. During this session, you can unify similar rules, split large ones into smaller files, and move instructions from always rules into more specific agent_requested or manual rules to optimize performance.

The key is contribution and continuous refactoring.

A Recommended Workflow for Getting Started

To sum it all up, here’s a step-by-step guide to mastering Cursor rules:

1. Start with Global Rules: Begin by populating your global code editor AI rules with your most common, high-level preferences. A few lines will do.
2. Create Project-Specific always Rules: When you notice rules that are specific to a repository, create a project rule with the always type. This keeps project-specific context out of your global settings.
3. Refactor and Specialize: If your always rule becomes too long, break it down.
   • Move context-dependent instructions into agent_requested rules with clear descriptions. This works well if you have fewer than 10 such rules.
   • For directory-specific instructions, use auto_attached rules with path patterns.
4. Use manual for Complex Workflows: If you have too many agent_requested rules and the agent struggles to keep up, convert some of them to manual. You can then invoke them by name when needed, reducing the cognitive load on the agent.

By following this structured approach, you can build a powerful and efficient system of rules that enhances your productivity in the Cursor AI code editor.