What are Cursor rules?

Cursor rules meaning

Cursor rules are reusable instructions that guide the AI inside the Cursor code editor. They encode your project conventions, preferred libraries, and patterns so the assistant generates consistent, project-appropriate code instead of guessing. They are the Cursor equivalent of CLAUDE.md and GEMINI.md.

.cursorrules vs .cursor/rules

There are two formats. The original `.cursorrules` file in the project root is now deprecated. The modern system uses individual `.mdc` files (Markdown Cursor) inside a `.cursor/rules/` directory. The shift matters because Cursor Agent mode loads context differently, and the old single file is not part of that path. Cursor recommends migrating to `.mdc` files in `.cursor/rules/`.

How .mdc files are structured

Each `.mdc` file is Markdown with YAML frontmatter that controls when it activates. Three key frontmatter fields are:

• description: a summary used for intelligent matching
• alwaysApply: a boolean for universal activation
• globs: file patterns for scoped activation

---
description: API route conventions
globs: ["app/api/**"]
alwaysApply: false
---

- Validate input with zod
- Return typed JSON responses

Why split rules into multiple files

Instead of one giant file, you use small `.mdc` files each scoped to a situation. This saves tokens and makes rules more reliable, because only the relevant rules load for a given file. Best practice is to keep each file under 500 lines and keep all always-apply rules under roughly 2,000 tokens combined so the context stays focused.

Commit your rules to the repo

The `.cursor/rules/` directory should be committed to version control. That is how an entire team gets the same AI behavior, the same way AGENTS.md and copilot instructions are shared. Rules in Git travel with the project and stay reviewable.

Cursor rules vs other agent files

Cursor rules play the same role as GEMINI.md, copilot-instructions.md, and Windsurf rules: tool-specific guidance for an AI coding agent. Cursor also reads AGENTS.md in many setups. Compare them all in the AI agent instruction files guide.

Write Cursor rules with a preview

Because `.mdc` files are Markdown, you can draft them in the Markdown Docs online editor to check headings and frontmatter, then save them into `.cursor/rules/`. Use the desktop app for local editing on Windows.

Related references

• Cursor rules best practices (.mdc guide) on the modern .mdc system.
• .cursorrules vs .cursor/rules format guide on migrating formats.