Cursor: Mastering Cursor Rules

What are Cursor Rules?

Large language models do not retain memory between completions. Rules solve this by providing persistent, reusable context at the prompt level. When a rule is applied, its contents are included at the start of the model context. This gives the AI consistent guidance whether it is generating code, interpreting edits, or helping with a workflow.

Cursor supports three types of rules:

• Project Rules: Stored in .cursor/rules, version-controlled and scoped to your codebase. These are ideal for project-specific guidelines.
• User Rules: Global to your Cursor environment. Defined in settings (Cmd+, or Ctrl+, then navigate to "Rules") and always applied. Perfect for personal preferences like response language or tone.
• .cursorrules (Legacy): A single file in the project root. Still supported, but deprecated. It's recommended to use Project Rules instead for better organization and features.

Project Rules: Structure and Types

Project rules live in the .cursor/rules directory within your project. Each rule is a separate file written in MDC (.mdc), a lightweight format supporting metadata and content.

Rule Structure (MDC File):

---
description: Brief explanation of what the rule does. Essential for 'Agent Requested' rules.
globs: ["**/frontend/**/*.tsx", "**/components/*.js"] # Optional: for 'Auto Attached' rules
alwaysApply: false # Optional: true for 'Always' rules, false otherwise
---

# Rule Content Section
- Your detailed instructions go here.
- Use markdown for clarity.
- You can reference other files like @path/to/template.ts to include their content.
                

Project Rule Types:

Rule Type	Description
Always	Always included in the model context. Set alwaysApply: true in the MDC metadata.
Auto Attached	Included when files matching a globs pattern are referenced in your prompt or context.
Agent Requested	The rule is available to the AI, which decides whether to include it based on its description. Ensure your description is clear and informative.
Manual	Only included when explicitly mentioned in your prompt using @ruleName (where ruleName is the filename of the rule without the .mdc extension).

How to Create and Manage Rules

Creating Project Rules:

1. Command Palette: Use Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux) and search for "New Cursor Rule". This will create a new .mdc file in the .cursor/rules directory.
2. Manual Creation: Create a .cursor/rules directory in your project root if it doesn't exist. Then, add new .mdc files for each rule.
3. Generate from Chat: After a conversation where you've refined how the AI should behave, you can ask Cursor to create a rule from it using a prompt like "/Generate Cursor Rules" or "turn this into a rule".

Defining Instructions:

• Write your instructions in Markdown within the .mdc file, after the --- metadata block.
• Be clear and concise.
• You can reference other files using the @path/to/file.ext syntax to include their content as part of the rule's context.

User Rules:

1. Go to Cursor Settings (Cmd+, or Ctrl+,).
2. Navigate to the "Rules" section.
3. Add your global rules in plain text. These do not support MDC format. For example:

   Please reply in a concise style. Avoid unnecessary repetition or filler language.

Legacy .cursorrules file:

If you have an existing .cursorrules file in your project root, Cursor will still use it. However, for new projects or when organizing existing ones, it's better to migrate these to the .cursor/rules directory structure. The content of a .cursorrules file is typically plain Markdown.

Example based on this course's .cursorrules:

This learning path project itself uses a .cursorrules file to guide the AI assistant (like me!). Here's a snippet of how it might look, defining personality and coding principles:

# Project Overview
This is a course aimed at teaching people how to use Cursor AI assistant. The audience is technical people who may not be familiar with AI tools.

# Personality
You are an expert in writing and teaching and knowledgeable about Cursor AI assistant. You have vast experience in writing rich frontend applications and designing easy-to-maintain apps.

# Fundamental Principles
- Write clean, simple, readable code
- Implement features in the simplest possible way
- Keep files small and focused (<200 lines)
- ALWAYS write simple, clean and modular code.

# Comments
- ALWAYS try to add more helpful and explanatory comments into our code
- Include LOTS of explanatory comments in your code. ALWAYS write well-documented code.
                  

If this were a Project Rule in .cursor/rules/course_guidelines.mdc, it might look like this:

---
description: Guidelines for the AI assistant working on the NSTECH Learning Path AI course, covering personality, coding principles, and commenting style.
alwaysApply: true
---

# Project Overview
This is a course aimed at teaching people how to use Cursor AI assistant. The audience is technical people who may not be familiar with AI tools.

# Personality
You are an expert in writing and teaching and knowledgeable about Cursor AI assistant. You have vast experience in writing rich frontend applications and designing easy-to-maintain apps.

# Fundamental Principles
- Write clean, simple, readable code
- Implement features in the simplest possible way
- Keep files small and focused (<200 lines)
- ALWAYS write simple, clean and modular code.

# Comments
- ALWAYS try to add more helpful and explanatory comments into our code
- Include LOTS of explanatory comments in your code. ALWAYS write well-documented code.
                  

Best Practices for Effective Rules

• Keep Rules Concise: Aim for under 500 lines. Long rules can be hard to manage and might dilute focus.
• Focused and Actionable: Each rule should address a specific aspect. Avoid vague guidance.
• Split Large Concepts: Break down complex guidelines into multiple, composable rules.
• Provide Concrete Examples: Use code snippets or reference template files (e.g., @service-template.ts) when helpful.
• Use Clear Language: Write instructions as if you were explaining them to a new team member.
• Iterate and Refine: Start with a few key rules and add more as you identify common areas where the AI could be better aligned.
• Keep Them Updated: As your project evolves, review and update your rules to reflect new standards or library choices.
• Commit Project Rules: Add the .cursor/rules directory to your version control.
• Combine with Prompt Engineering: Rules provide a baseline. You can still use specific prompt engineering techniques for ad-hoc tasks.

Examples of Good Rules:

For Frontend Development (e.g., .cursor/rules/frontend-standards.mdc):

---
description: Standards for frontend components and API validation in our React/Tailwind project.
globs: ["**/src/components/**/*.tsx", "**/src/pages/api/**/*.ts"]
alwaysApply: false
---

# Frontend Development Standards

## Component Design
- Always use Tailwind CSS for styling.
- Use Framer Motion for animations.
- Follow our component naming conventions (PascalCase for components, camelCase for props).
- Reference: @../../assets/css/styles.css

## API Validation (Next.js API Routes)
- Use Zod for all request and response validation.
- Define return types with Zod schemas.
- Export types generated from Zod schemas.
                  

For Boilerplate/Templates (e.g., .cursor/rules/express-service-template.mdc):

---
description: Template for creating new Express.js services.
alwaysApply: false 
# This rule would typically be manually invoked: @express-service-template
---

# Express Service Template
Use this template when creating a new Express service:
- Follow RESTful principles.
- Include error handling middleware.
- Set up proper logging using our standard logger.
- See @path/to/your/express-service-template.ts for the base structure.