Using Project Rules in Cursor

Here’s a refined and polished rewrite of your provided content, enhancing readability, clarity, and engagement:

Cursor 0.46 introduces Project Rules, a powerful new feature designed to customize AI behavior specifically for your projects. This guide will walk you through everything you need to know to effectively leverage Project Rules and enhance your coding workflow.

1. Introduction

What Are Cursor Rules?

Cursor Rules provide essential context to guide the AI’s behavior within your projects. There are two main types:

1. Global Rules:
   • Apply universally across all your projects.
   • Configured in Cursor Settings under “General” > “Rules for AI”.
   • Ideal for setting personal coding preferences.

2. Project Rules:
   • Tailored specifically to individual codebases.
   • Stored as .mdc files within the .cursor/rules directory.
   • Help the AI adhere to your project’s unique conventions and standards.

Why Use Project Rules?

Project Rules significantly improve AI-generated suggestions by aligning them closely with your project’s specific frameworks, conventions, and coding standards.

2. Evolution of Cursor Rules

Previous Formats

Initially, Cursor Rules were defined in a .cursorrules file using JSON:

{
  "rules": [
    {
      "name": "React Component Style",
      "description": "Use functional components with TypeScript",
      "pattern": "src/components/**/*.tsx"
    },
    {
      "name": "API Service Implementation",
      "description": "Follow established patterns for API services",
      "pattern": "src/services/**/*.ts"
    }
  ]
}

Some users experimented with a more readable Markdown-like format:

## React Component Guidelines
- Use functional components with TypeScript
- Apply to: src/components/**/*.tsx

## API Service Guidelines
- Follow established patterns for API service implementation
- Apply to: src/services/**/*.ts

Current Format: .cursor/rules Directory

The latest approach uses a dedicated .cursor/rules directory containing multiple .mdc files in Markdown format, offering improved readability, granular control, and easier version management.

Example (react-components.mdc):

---
description: React Component Standards
globs: src/components/**/*.tsx
alwaysApply: true
---

React components should:
1. Use functional components with TypeScript.
2. Define prop interfaces above components.
3. Include clear JSDoc comments.

3. Setting Up Project Rules

To set up Project Rules:

1. Create a .cursor directory at your project’s root.
2. Inside .cursor, add a rules folder.
3. Save your rule files with the .mdc extension inside this folder.

Note: If Cursor doesn’t immediately recognize your rules, close the file, select “Override” when prompted, and restart Cursor.

4. Writing Effective Rules

Rule Structure

Each rule file should include:

• Description: Clearly explains the rule’s purpose.
• Globs: Specifies file patterns where the rule applies.
• AlwaysApply: Ensures the rule is automatically applied.
• Body Content: Provides detailed guidelines or examples.

Best Practices

• Write clear, concise descriptions.
• Use precise glob patterns to target relevant files.
• Keep each rule focused on a single concept for modularity.
• Include practical examples demonstrating correct usage.

5. Applying Rules

Rules automatically activate when:

• A file matches the specified glob pattern.
• The rule’s description aligns with the current context.
• The AlwaysApply setting is enabled.

Rule Precedence

• Specific glob patterns override general ones.
• Project-specific rules take precedence over global rules.
• Conflicts are resolved based on specificity or the most recent modification date.

6. Practical Examples

React Components

---
description: React Component Standards
globs: src/components/**/*.tsx
alwaysApply: true
---

React components must:
1. Use functional components with TypeScript.
2. Define prop interfaces above components.
3. Export components using named exports only.

TypeScript Standards

---
description: TypeScript Standards
globs: src/**/*.ts
alwaysApply: true
---

TypeScript code should:
1. Explicitly define return types for functions.
2. Prefer interfaces over type aliases for object definitions.
3. Enable strict null checks in `tsconfig.json`.

7. Troubleshooting Common Issues

• Verify the structure and file extensions of .cursor/rules/*.mdc.
• Check the Cursor sidebar to confirm active rules.
• Simplify glob patterns if rules aren’t matching as expected.
• Test rules explicitly by referencing them in prompts.

8. FAQs

Do I need to include @cursorrules in prompts?

No. Rules automatically apply when file patterns match or when AlwaysApply is enabled.

What happens if two rules conflict?

Specific glob patterns take precedence, and project rules override global rules.

Can I share rules across my team?

Absolutely! Include .cursor/rules in your version control system and document their usage clearly.

9. Tips for Optimizing Rules

• Organize rules with descriptive filenames for easy identification.
• Write clear, informative descriptions to help the AI understand each rule’s intent.
• Regularly review and update rules as your project evolves.