What is a Cursor rules file?

A Cursor rules file is a markdown document at your project's root that Cursor reads on every chat and inline-edit request. It's how you tell Cursor — and the model behind it — what your project is, how it's built, and what conventions to follow.

Two formats

Cursor supports two formats. They both work; new projects should prefer the second.

Legacy: .cursorrules — A single markdown file at the repo root. Plain text, no frontmatter, no globs. Cursor loads the entire thing into context on every interaction.

Modern: .cursor/rules/*.mdc — A directory of .mdc files, each with YAML frontmatter declaring a description, optional file globs (so the rule only applies to certain files), and an alwaysApply flag. Multiple files compose; Cursor picks the relevant ones based on what you're working on.

A minimal .mdc file looks like:

---
description: "TypeScript code conventions"
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

# TypeScript conventions

- Strict mode is on.
- No `any` — use `unknown` and narrow.
- Named exports only.

What goes in it

The same things you'd tell a new hire on day one:

• Stack overview — frameworks, languages, libraries, versions
• Folder structure — where things live, why
• Conventions — naming, exports, import style, formatting
• Patterns to follow — the "always do" rules with examples
• Patterns to avoid — the "never do" rules with examples
• Testing approach — what framework, where tests live
• Tooling — how to run dev, build, test, lint
• AI behavioral rules — meta-rules like "ask before installing dependencies" or "run tests before declaring a task complete"

What not to put in it

• Platitudes. "Write clean code" / "follow best practices" / "use TypeScript." The model already knows.
• Documentation that belongs in the README. Rules files are for things the AI needs to act on every turn, not for project history.
• Secrets. The file is committed to git.
• Entire codebases pasted in as context. Use Cursor's file references for that, not the rules file.

How long should it be?

500 lines is roughly the upper bound for .cursorrules. For .cursor/rules/*.mdc, you can split across multiple files — each scoped to a different glob pattern — and Cursor only loads the relevant ones at a time. This is the main practical reason to migrate to the new format on large projects.

Does Cursor still read .cursorrules?

Yes. Cursor still honors the legacy file for backwards compatibility. New projects should use the modern format because globs and multi-file composition are real wins on anything larger than a few hundred lines.

Where can I find good examples?

The stack library on this site has 20 hand-curated rules files for popular stacks — Next.js, FastAPI, Django, Rails, Flutter, and more. Each one has a one-click copy as Cursor .cursorrules or Cursor .mdc. Or use the generator to build one from your own stack choices.