Rules

Rules provide system-level instructions to Agent and Inline Edit. Think of them as persistent context, preferences, or workflows for your projects.Cursor supports four types of rules:

Project Rules

Stored in .cursor/rules, version-controlled and scoped to your codebase.

User Rules

Global to your Cursor environment. Defined in settings and always applied.

AGENTS.md

Agent instructions in markdown format. Simple alternative to .cursor/rules.

.cursorrules (Legacy)

Still supported, but deprecated. Use Project Rules instead.

How rules work

Large language models don’t retain memory between completions. Rules provide persistent, reusable context at the prompt level.When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.

Rule applied in context with chat

Project rules

Project rules live in .cursor/rules. Each rule is a file and version-controlled. They can be scoped using path patterns, invoked manually, or included based on relevance. Subdirectories can include their own .cursor/rules directory scoped to that folder.Use project rules to:

• Encode domain-specific knowledge about your codebase
• Automate project-specific workflows or templates
• Standardize style or architecture decisions

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, 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

---

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

Nested 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

Creating a rule

Create rules using the New Cursor Rule command or going to Cursor Settings > Rules. This creates a new rule file in .cursor/rules. From settings you can see all rules and their status.

Comparison of concise vs long rules

Generating rules

Generate rules directly in conversations using the /Generate Cursor Rules command. Useful when you’ve made decisions about agent behavior and want to reuse them.

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

Examples

This rule provides standards for frontend components:When working in components directory:

• Always use Tailwind for styling
• Use Framer Motion for animations
• Follow component naming conventions This rule enforces validation for API endpoints:In API directory:
• Use zod for all validation
• Define return types with zod schemas
• Export types generated from schemas

This rule provides a template for Express services:Use this template when creating Express service:

• Follow RESTful principles
• Include error handling middleware
• Set up proper logging @express-service-template.ts This rule defines React component structure:React components should follow this layout:
• Props interface at top
• Component as named export
• Styles at bottom @component-template.tsx

This rule automates app analysis:When asked to analyze the app:

1. Run dev server with npm run dev
2. Fetch logs from console
3. Suggest performance improvements This rule helps generate documentation:Help draft documentation by:

• Extracting code comments
• Analyzing README.md
• Generating markdown documentation

First create a property to toggle in @reactiveStorageTypes.ts.Add default value in INIT_APPLICATION_USER_PERSISTENT_STORAGE in @reactiveStorageService.tsx.For beta features, add toggle in @settingsBetaTab.tsx, otherwise add in @settingsGeneralTab.tsx. Toggles can be added as <SettingsSubSection> for general checkboxes. Look at the rest of the file for examples.

<SettingsSubSection

                label="Your feature name"

                description="Your feature description"

                value={

                    vsContext.reactiveStorageService.applicationUserPersistentStorage

                        .myNewProperty ?? false

                }

                onChange={(newVal) => {

                    vsContext.reactiveStorageService.setApplicationUserPersistentStorage(

                        'myNewProperty',

                        newVal

                    );

                }}

            />

To use in the app, import reactiveStorageService and use the property:

const flagIsEnabled = vsContext.reactiveStorageService.applicationUserPersistentStorage.myNewProperty

Many examples available from providers and frameworks. Community-contributed rules are found across crowdsourced collections and repositories online.

AGENTS.md

AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .cursor/rules for straightforward use cases.Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. It’s perfect for projects that need simple, readable instructions without the overhead of structured rules.

# Project Instructions

## Code Style

- Use TypeScript for all new files

- Prefer functional components in React

- Use snake_case for database columns

## Architecture

- Follow the repository pattern

- Keep business logic in service layers

Current limitations

• Root level only: AGENTS.md must be placed in your project root (v1.5)
• No scoping: Instructions apply globally to your project
• Single file: Unlike .cursor/rules, you cannot split instructions across multiple files

Nested AGENTS.md support in subdirectories is planned for v1.6.

User Rules

User rules are global preferences defined in Cursor Settings → Rules that apply across all projects. They’re plain text and perfect for setting preferred communication style or coding conventions:

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

.cursorrules (Legacy)

The .cursorrules file in your project root is still supported but will be deprecated. We recommend migrating to Project Rules for more control, flexibility, and visibility.

FAQ

Check the rule type. For Agent Requested, ensure a description is defined. For Auto Attached, ensure the file pattern matches referenced files.

Yes. Use @filename.ts to include files in your rule’s context.

Yes, generate project rules from chat using the /Generate Cursor Rules command. If Memories are enabled, memories are generated automatically.

No. Rules only apply to Agent and Inline Edit

Terminal Memories