Cursor Rules: The Complete Guide (.cursorrules + .mdc)

What are Cursor rules?

Cursor rules are persistent instructions injected into the model’s context so the AI codes the way your project expects — your stack, your patterns, your forbidden moves. Without them, Cursor re-derives your conventions from whatever files happen to be open, and gets them wrong often enough to be annoying. With them, “use our internal RPC pattern” or “never use any” becomes a standing order.

There are two generations of the feature. Understanding which is which is the whole game.

The legacy .cursorrules file

The original mechanism was a single .cursorrulesfile at the repo root: free-form text or Markdown, no frontmatter, injected into every conversation. It’s elegant — one file, no schema — but everything in it is always on, with no way to scope a rule to one task or one file type. As the file grows it starts contradicting itself.

# Project: Acme API
## Standards
- Strict TypeScript. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.
## Testing
- Vitest for unit, Playwright for E2E. 80% line coverage.
## Don't
- Don't run `pnpm install` without asking.

The .cursor/rules system (.mdc)

Project Rules live in .cursor/rules/ as individual .mdcfiles — “Markdown with metadata.” The metadata matters: a plain .md file in that directory is ignored, because it has no frontmatter to tell Cursor when to apply it.

---
description: RPC service conventions for our internal framework
globs: ["src/**/*.ts", "src/**/*.tsx"]
alwaysApply: false
---

- Use our internal RPC pattern when defining services.
- Service names are snake_case.
- See the canonical template below and mirror its structure.

@service-template.ts

The three frontmatter fields

• description — what the rule is about. Cursor’s agent reads this to decide whether to pull the rule in (this drives the “Apply Intelligently” mode).
• globs — file path patterns. When you open, read, or edit a matching file, the rule is auto-attached.
• alwaysApply — a boolean. true includes the rule in every conversation.

The four rule types

The three fields combine into four practical activation modes. Heads up on naming:Cursor’s current UI says one thing, and almost every third-party guide (and Cursor’s own earlier docs) says another. They’re the same four modes — here are both vocabularies:

@file references

A rule can pull another file into context with @filename.ts. Instead of pasting a whole boilerplate template into the rule, reference the real file — the rule stays small and never drifts from the source. You can also @-mention a rule in chat to apply it on the spot.

Project Rules vs User Rules vs Team Rules vs Memories

Cursor has four related concepts. Keeping them straight saves a lot of confusion:

The key distinction is Rules vs Memories. Rules are static text you maintain on purpose. Memories are auto-generated— Cursor watches a chat, extracts a durable preference, and stores it so you stop re-explaining yourself. Memories are per-project and per-user, so a teammate doesn’t inherit yours unless you promote it into a rules file by hand.

How to create rules

• From a conversation: run /Generate Cursor Rules to capture the decisions from a back-and-forth into a rule (shipped in Cursor v0.49).
• From scratch: /create-rule in chat, or Cursor Settings › Rules → Add Rule, or the command palette’s “New Cursor Rule.”

Best practices

• Keep rules under ~500 lines. Split large rules into smaller, composable ones.
• Show, don’t lecture. A concrete example beats a paragraph of style-guide prose. Reference files with @file rather than duplicating them.
• Use alwaysApply: true sparingly. It’s global config; prefer Auto Attached or Agent Requested for anything scoped.
• Write rules reactively.Cursor’s own advice: add a rule when you notice the agent making the same mistake repeatedly.

For copy-paste starting points by framework, see the best .cursorrules examples by stack.

Cursor and AGENTS.md

As of 2026, Cursor natively reads AGENTS.md — including nested files in subdirectories, with more specific paths taking precedence. Cursor positions it as a simple, portable alternative to .cursor/rules for straightforward cases. The trade-off: AGENTS.md is plain Markdown with no globs or per-mode activation, so you give up Cursor-specific scoping in exchange for a file that every other agent reads too.

Using Cursor alongside other tools

Here’s the catch almost no rules guide mentions: most developers don’t only use Cursor. The moment you also run Claude Code or Copilot, the same conventions you just encoded in .mdc files have to be re-encoded in CLAUDE.md and copilot-instructions.md — and then kept in sync forever.

Two ways forward: convert your .cursorrules into the other formats once, or keep a single canonical library and compile to all of them. Skillwright does the latter — author once, deploy to Cursor, Claude Code, Windsurf, and Copilot. See how to manage AI coding rules across tools for the full picture, or grab ready-made rule templates to start.

Frequently asked questions