Imagine having a dedicated rulebook for your AI coding assistant. Cursor Rules do exactly that: they give your Cursor AI “persistent, reusable context at the prompt level”. AI assistant like Cursor can be a game-changer, But what if you could give your AI assistant a personal set of guidelines—a rulebook to follow for every project? This is where Cursor’s rules come in. They are essentially a way to provide consistent instructions to your AI, ensuring it understands your style, your project’s architecture, and your specific needs without you having to repeat
Think of these rules as a persistent set of instructions, preferences, and workflows that shape how the AI model behaves. They are automatically included in the model’s context, acting as a north star for the AI as it helps you code.
Types of Cursor Rules
Cursor currently supports four kinds of rules
-
Project Rules: Files in the .cursor/rules/ folder of your repo. These are version-controlled, scoped to your codebase, and can be as specific as you like (even nested in subfolders). You use them to enforce project conventions, code standards, or automate workflows.
-
User Rules: Global preferences you set in Cursor’s Settings → Rules. These apply across all your projects (e.g. “Always use TypeScript” or “Respond concisely” in chat).
-
AGENTS.md: A single markdown file at your project root. It’s an easy, one-file alternative for simple instructions. (It has no metadata or scoping – any directives here apply to the entire project).
-
.cursorrules (Legacy): The old style single-file rule. It still works but is deprecated; it’s better to use the new Project Rules system
1. Project Rules
For serious projects, Project Rules are your secret weapon. These rules are stored directly within your codebase in a dedicated .cursor/rules directory.Project rules live under a .cursor/rules/ directory in your repo. Each rule is one .mdc file (Markdown with metadata) that can be triggered manually or auto-applied based on file patterns.
For example, you might have backend-rules.mdc for server code and frontend-rules.mdc for React code. Rules can be Always applied, Auto-Attached (when matching files are in context), Agent-Requested, or Manual. By organizing subfolders (e.g. backend/.cursor/rules/), you can create nested rules that only activate within certain directories
my-project/
├─ .cursor/rules/ # rules for the whole project
├─ backend/
│ ├─ .cursor/rules/ # rules just for backend code
│ └─ ...
└─ frontend/
├─ .cursor/rules/ # rules just for frontend code
└─ ...
2. User Rules
While Project Rules are about the code, User Rules are about you. These are your personal, global preferences that you set in your Cursor settings. These rules apply to your entire Cursor environment, regardless of the project you’re working on.
User Rules are written in a simple, plain text format, making them perfect for defining your preferred communication style or general coding conventions. For example, you might create a rule that tells the AI to always explain its code changes in a concise, bulleted list or to prefer a certain naming convention for variables.
3. The Simple AGENTS.md File
Sometimes, you need a straightforward solution without the complexity of a .cursor/rules directory. That’s where AGENTS.md comes in. This is a simple markdown file that you place in the root of your project.
The instructions within this single file apply globally to your entire project. It’s a great option for straightforward use cases or for projects that don’t need a lot of detailed, scoped rules. Unlike Project Rules, you can’t split it into multiple files or use metadata, but its simplicity is its biggest strength.
4. The Legacy .cursorrules File
Finally, there’s a legacy option: the .cursorrules file. While it’s still supported, it’s considered deprecated. The documentation recommends migrating to the more powerful and flexible Project Rules for better control, visibility, and long-term support.
Rule anatomy
Each rule file is written in MDC (.mdc), a format supporting metadata and content. Control how rules are applied from the type dropdown, which changes properties description, globs, and alwaysApply.
| Rule Type | Description |
|---|---|
Always |
Always included in model context |
Auto Attached |
Included when files matching a glob pattern are referenced |
Agent Requested |
Available to AI, which decides whether to include it. Must provide a description |
Manual |
Only included when explicitly mentioned using @ruleName |
Example usage
description: RPC Service boilerplate
globs:
alwaysApply: false
---
- Use our internal RPC pattern when defining services
- Always use snake_case for service names.
@service-template.ts
Nestes Rules
Organize rules by placing them in .cursor/rules directories throughout your project. Nested rules automatically attach when files in their directory are referenced.
project/
.cursor/rules/ # Project-wide rules
backend/
server/
.cursor/rules/ # Backend-specific rules
frontend/
.cursor/rules/ # Frontend-specific rules
Best Practices
Good rules are focused, actionable, and scoped.
- Keep rules under 500 lines
- Split large rules into multiple, composable rules
- Provide concrete examples or referenced files
- Avoid vague guidance. Write rules like clear internal docs
- Reuse rules when repeating prompts in chat