Cursor rules: .mdc files, AGENTS.md and scope

A rule file can exist in a repository without ever reaching Cursor’s agent. The extension, location and application settings determine whether an instruction is always included, attached for a matching file or available only when you ask for it.

This guide applies to Cursor’s documented rules system, checked October 8, 2026.

On this page

Choose the right place for the instruction

Cursor’s rules documentation separates project rules, user rules, team rules and AGENTS.md. Project rules belong in .cursor/rules and travel with the repository. User rules apply across your Cursor environment. Team rules are administered centrally on supported organizational plans.

For a small project that needs ordinary Markdown instructions, AGENTS.md is the simpler option. Use project rules when you need file matching or explicit application modes. These choices answer different questions: where the instruction is shared and when the agent receives it.

Why a .md file in .cursor/rules is ignored

Project rules use the .mdc extension. Cursor explicitly documents that a plain .md file inside .cursor/rules is ignored by the rules system. Renaming a file is therefore part of configuring a project rule, not merely tidying its name.

The documentation’s example distinguishes the two:

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

A README remains useful documentation, but putting it in this directory does not make it a rule. Keep plain Markdown instructions in AGENTS.md when that is the intended format.

Application mode controls the context

Cursor’s rule editor exposes four modes: always apply, apply intelligently, apply to specific files and apply manually. Underneath them are the alwaysApply, description and globs fields.

An always-applied rule ignores the description and glob conditions. With alwaysApply: false, a supplied glob attaches a rule when a matching file is in context. A description without a glob lets the agent select the rule by relevance. Without either field, the rule needs an explicit mention.

For example, a project could keep a short rule for component files:

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Export UI components by name.
- Keep component styles in a nearby CSS module.
- Read the existing component before introducing a new pattern.

Those conventions illustrate file scope; they are not requirements for every application. Decide which instructions should reach every task before selecting an always-applied mode.

A file reference is a pointer

A rule may tell the agent to read an existing template. Cursor says a reference such as @migration-template.sql does not automatically inline the file’s contents into the prompt. The agent reads that file with its tools when needed.

Put indispensable instructions in the rule itself. Point to the canonical source for longer examples, and explain what the agent should inspect there. That keeps a rule from accumulating stale copies of application code.

Check a rule before adding another

Start with the repeated mistake you want to correct. Confirm that the file has the right extension, that its scope includes the files in the current task and that its application mode matches your intention. Then make the instruction concrete enough to follow.

Cursor recommends focused rules, version control and composable files. A rule should explain a decision specific to your project; ordinary formatting can remain in a linter. For broader tool differences, see Cursor or VS Code; for data handling, see Cursor security and Privacy Mode.