How to write Cursor rules: project rules and .mdc files, with examples

Guide · checked against the docs on Oct 15, 2026

Cursor rules are instructions that Cursor's Agent reads every time, so you don't have to repeat yourself in chat. This guide shows where project rules live, the one file-format detail that trips people up, the four ways a rule can be applied, and what Cursor says to leave out. Everything here comes from Cursor's rules docs, read on October 15, 2026.

Not affiliated with or endorsed by Anysphere (Cursor). Check Cursor's current docs before relying on these details.

Our tool page: Cursor

What rules do

Cursor's docs explain why rules exist: "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."

The docs list four kinds:

This guide covers project rules. For AGENTS.md, see our AGENTS.md and CLAUDE.md guide.

The .mdc rule

This is the detail most people miss. Cursor's docs say: "Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply." If you'd rather write plain markdown, the docs say to "use AGENTS.md instead."

You can name rule files anything and organize them in folders. The docs show this layout:

.cursor/rules/
  react-patterns .mdc     # Recognized as a project rule
  api-guidelines .md      # Ignored (wrong extension)
  frontend/              # Organize rules in folders
    components .mdc

The four rule types

Each rule is a markdown file with frontmatter at the top. Three fields, alwaysApply, description and globs, decide when Cursor uses it. Here's the docs' table:

In Cursor's menu these are called Always Apply, Apply to Specific Files, Apply Intelligently and Apply Manually.

Always apply (NOT TESTED)

---
alwaysApply: true
---
- Never modify generated files in the `dist/` or `build/` directories
- When unsure about implementation details, read the relevant source files before proposing changes

Apply to specific files (NOT TESTED)

---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports
- Keep components under 200 lines

Apply intelligently (NOT TESTED)

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---
- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary

Apply manually (NOT TESTED)

---
alwaysApply: false
---
- Every database migration must have both `up` and `down` functions

You'd use this one by typing @ and the rule's name in chat, for example @my-rule.

These examples are shortened from the ones in Cursor's docs.

Glob patterns

Globs pick which files a rule applies to. The docs say to "Separate multiple patterns with commas." A few from the docs' table:

Pointing to files instead of pasting them

A rule can mention a file, like @migration-template.sql. The docs say "Agent reads the file with its tools when it needs the content. The file's contents are not inlined into the prompt". So "Put anything that must always be in context directly in the rule body."

Creating a rule

The docs give two ways:

• In chat: "Type /create-rule in Agent and describe what you want." Agent writes the file with frontmatter and saves it to .cursor/rules.
• From Customize: "Open Customize in the sidebar, go to Rules, and click Add Rule."

What Cursor says to keep out of rules

Cursor's tips: "Keep rules under 500 lines", "Split large rules into multiple, composable rules", and "Avoid vague guidance." The docs also list what to avoid:

• "Copying entire style guides: Use a linter instead."
• "Documenting every possible command: Agent knows common tools like npm, git, and pytest."
• "Adding instructions for edge cases that rarely apply"
• "Duplicating what's already in your codebase: Point to canonical examples instead of copying code."

Never put secrets in a rule. Project rules are version-controlled, so they usually end up in your repo, and when a rule applies, it's added to the model's context. Keep API keys in a .env file instead. See our guide to keeping secrets safe with AI coding tools.

Not affiliated with or endorsed by Anysphere (Cursor). Check Cursor's current docs before relying on these details.