What are Cursor rules?
Cursor rules are standing instructions for Cursor's Agent, stored as .mdc files in your project's .cursor/rules folder and checked into git. Each rule says when it applies: always, for files matching a glob, when the Agent judges it relevant, or only when you @mention it. User rules add personal preferences across every project.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
You add a rule with /create-rule in Agent chat, or under Customize, then Rules. Cursor saves it as an .mdc file in .cursor/rules, which you commit.
Front matter decides the type: alwaysApply: true for every chat, globs for matching files, a description for the Agent to judge by, or none of those for manual.
When a rule applies, its content is inserted at the start of the model context. Team rules win over project rules, which win over user rules.
An @file reference inside a rule is not inlined. The Agent opens that file with its tools when it needs the content.
User rules under Customize, then Rules are your own preferences and apply in every project. A root AGENTS.md is read too, with no front matter needed.
Source: Cursor docs: Rules
Cursor rules versus AGENTS.md
Cursor reads two kinds of standing instruction from a project. Project rules are .mdc files in .cursor/rules, each with front matter that says when it should load. AGENTS.md is a plain Markdown file in the project root with no metadata; Cursor picks it up automatically, and a nested AGENTS.md applies when the Agent works in that directory. Other agents read AGENTS.md too, so it is the right place for the few things every tool should know: how to build, how to test, what never to touch. Rules are for instructions that should only load sometimes, like React conventions that matter only when a .tsx file is in the conversation.
One boundary people miss: rules apply to the Agent in chat. They do not shape Tab completions or Cursor's other AI features.
Example: a rule that loads only for API handlers
---
description: Conventions for HTTP handlers under src/api
globs: src/api/**/*.ts
alwaysApply: false
---
- Validate the request body with the shared schema before reading any field.
- Return errors through httpError(); never build a Response by hand.
- Follow the shape in @src/api/_template.ts.
When a file under src/api is in context, Cursor attaches this rule. The last line is a reference, not a paste: the Agent opens _template.ts with its tools only if it decides it needs the shape. If something must be in front of the model every time, write it into the rule body.
Where rules live and how they load
There are three scopes. Project rules sit in .cursor/rules and travel with the repository, so everyone who clones gets them. User rules are set under Customize, then Rules; they are global preferences, such as asking for short answers, and they follow you into every project. Team rules are created in the Cursor dashboard on Team and Enterprise plans; an admin can enforce one so members cannot switch it off.
When several rules apply, Cursor merges them and resolves conflicts in the order Team, then Project, then User. Whatever applies is placed at the start of the model context, ahead of your message. Subfolders inside .cursor/rules work, so you can group rules by area.
Common mistakes
- Saving a
.mdfile. The rules system ignores it. The extension has to be.mdc. - Keeping
.cursorrulesaround. The current docs describe rules as.mdcfiles only. Move the text into an Always Apply rule and delete the root file. - Expecting
@fileto inline the file. It doesn't. The reference tells the Agent where to look. - One giant rule for everything. Cursor's guidance is to keep a rule under 500 lines. Past that, split by concern so each rule can have its own trigger.
- Marking every rule
alwaysApply: true. Then globs and descriptions are ignored and every chat carries every rule. Use the type that fits.
FAQ
- Is the .cursorrules file still supported in Cursor?
- Cursor's current rules documentation does not cover it; it describes project rules as .mdc files in .cursor/rules. If you still have a .cursorrules file, create a new rule, copy its text in, set the type to Always Apply so it loads in every chat as the old file did, and delete the root file.
- Why is my Cursor rule being ignored?
- Check the extension first: only .mdc files count, and a plain .md in .cursor/rules is skipped. Then check the type: with alwaysApply false and no globs or description, the rule is manual and loads only when you @mention it. Rules also apply to the Agent only, not to Tab or other AI features.
- How long should a Cursor rules file be?
- Cursor's guidance is under 500 lines. Split a big rule into focused files, one concern each, and point at files with @ instead of pasting their contents, so the rule doesn't go stale when the code changes.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.