Writing Cursor rules

What Cursor rules are

Cursor rules are markdown files that shape how the AI agent behaves in your project. They live in .cursor/rules/ and use the .mdc (Markdown with Context) extension. Each file contains YAML frontmatter that controls when the rule activates, followed by markdown instructions the agent follows.

Rules replaced the legacy .cursorrules file, which was a single flat file with no activation control. The modern system supports multiple rule files, each scoped to specific situations.

File format

Every .mdc file starts with YAML frontmatter between --- markers:

---
description: Brief description of the rule's purpose
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

Your rule instructions here in plain markdown.

Frontmatter fields

Field	Type	Default	Purpose
description	string	—	Tells the agent (and humans) what this rule is for
globs	string or string[]	—	File patterns that trigger auto-attachment
alwaysApply	boolean	false	Whether to include this rule in every interaction

The four rule types

How you set the frontmatter determines when the rule activates:

1. Always-apply rules

Active in every chat, every file, every interaction.

---
description: Project-wide coding standards
alwaysApply: true
---

Use TypeScript strict mode. All functions must have explicit return types.
Use early returns over nested conditionals.
Never use `any` type—use `unknown` and narrow with type guards.

Use for: Universal project conventions, coding standards, response format preferences.

2. Auto-attached rules

Activate automatically when the agent works with files matching the glob patterns.

---
description: React component conventions
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Use functional components with hooks. Never use class components.
Export components as named exports, not default exports.
Colocate styles in a .module.css file with the same name.
Props interfaces must be exported and named {ComponentName}Props.

Use for: File-type-specific or directory-specific conventions.

3. Agent-decided rules

The agent reads the description and decides whether to apply the rule based on relevance.

---
description: Database migration guidelines for schema changes
alwaysApply: false
---

Use sequential migration files named YYYYMMDDHHMMSS_description.sql.
Always include a rollback section.
Never use DROP COLUMN without a data backup step.
Test migrations on a copy of production data before merging.

Use for: Situational rules that only matter for specific types of work.

4. Manual rules

No alwaysApply, no globs, no description. Only active when explicitly referenced with @rulename in the chat.

---
---

When writing API documentation:
- Use OpenAPI 3.1 format
- Include request/response examples for every endpoint
- Document error codes and their meanings

Use for: Specialized instructions you only need occasionally.

Directory structure

.cursor/
└── rules/
    ├── general.mdc              # Always-apply: project-wide standards
    ├── typescript.mdc           # Auto-attached: *.ts, *.tsx files
    ├── react-components.mdc     # Auto-attached: src/components/**
    ├── api-routes.mdc           # Auto-attached: src/app/api/**
    ├── database.mdc             # Agent-decided: migration work
    ├── testing.mdc              # Agent-decided: test writing
    └── docs.mdc                 # Manual: documentation tasks

Rule precedence

When multiple sources provide instructions, Cursor applies them in this order (highest priority first):

1. Team Rules — Synced from Cursor team settings
2. Project Rules — .cursor/rules/*.mdc files
3. User Rules — Set in Cursor's global settings
4. Legacy Rules — .cursorrules file (if it still exists)
5. AGENTS.md — Plain markdown instructions in project root

Writing effective rules

Keep rules actionable

Good: "Use zod for all runtime validation. Define schemas in lib/schemas/ with the naming pattern {resource}.schema.ts."

Bad: "Write clean code and follow best practices."

Be specific about boundaries

Good: "Never modify files in src/generated/. These are auto-generated by the OpenAPI codegen pipeline."

Bad: "Be careful with generated files."

Include examples when patterns are non-obvious

---
description: Error handling conventions
globs: ["src/app/api/**/*.ts"]
alwaysApply: false
---

API routes must use the standard error response format:

return NextResponse.json(
  { error: { code: "VALIDATION_ERROR", message: "Email is required" } },
  { status: 400 }
);

Never return plain strings or unstructured error objects.

Keep individual files focused

One file per concern. Don't put React conventions, database rules, and deployment instructions in the same file.

Migrating from .cursorrules

If you have an existing .cursorrules file:

1. Create the .cursor/rules/ directory
2. Split the content into topic-specific .mdc files
3. Add appropriate frontmatter to each file
4. Delete the old .cursorrules file
5. Commit the new rules directory to version control

AGENTS.md as an alternative

For simpler projects, you can use a plain AGENTS.md file in the project root instead of .mdc files. It's standard markdown with no frontmatter, and it's also recognized by Codex and other tools. The tradeoff is that you lose glob-based activation and rule-type control.