Cursor Rules: Project Rules, .mdc Files, and AGENTS.md

Cursor rules are persistent instructions that Cursor's Agent reads before it answers, so you stop typing "use named exports" into every chat. Write the convention once, check it into git, and every session starts from it.

Here's the short version, as of September 2026:

• Project rules live in .cursor/rules/ as .mdc files. A plain .md file in that folder is ignored.
• Each rule has one of four apply modes: Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually.
• The old .cursorrules file is legacy. Cursor's own help page says it will be deprecated and tells you how to migrate.
• AGENTS.md and CLAUDE.md both work too, as plain markdown with no frontmatter.
• Rules only reach Agent (Chat). They don't touch Tab completion or Inline Edit.

The rest of this post covers which rule type to use, the frontmatter that controls each mode, one example file, and the mistakes that make a rule silently do nothing.

The four types of Cursor rules

Cursor supports four places to put instructions. They differ in who owns them and where they're stored:

A few details from Cursor's rules documentation that matter in practice:

User rules come in two flavours. Rules you add in Customize are stored on your Cursor account and sync when you sign in on another machine. Rule files you put in ~/.cursor/rules stay on that one machine and don't sync.

Team Rules need a Team or Enterprise plan. Admins can mark a rule as enforced, which means members can't switch it off. Non-enforced team rules are on by default, but each person can disable them.

Precedence runs Team → Project → User. All applicable rules get merged, and when two of them conflict, the earlier source wins. So a team rule beats your repo's rule, which beats your personal preference.

The four apply modes, and the frontmatter behind them

This is where older guides trip people up, because the mode names have changed. In the current editor you pick the mode from a type dropdown. Under the hood, the dropdown just writes three frontmatter fields: alwaysApply, description, and globs.

If you've read older guides, "auto-attached" is the file-pattern mode and "agent-requested" is Apply Intelligently. Same behaviour, new labels.

Pick the mode by how often the rule is true. A rule that applies to every file in the repo ("never edit anything in dist/") is Always Apply. A rule that only matters for React components gets a glob like src/components/**/*.tsx. A rule for an occasional task, like writing a database migration, is a good Manual rule: it costs nothing until you call it.

Apply Intelligently sits in the middle, and it lives or dies on the description. If the description is vague, Agent won't know when to pull it in. Write it the way you'd write a function docstring: what the rule covers, in one line.

Globs follow the usual patterns. **/*.ts matches TypeScript files anywhere, src/** matches everything under src/, and you can list several patterns separated by commas.

A Cursor rule example you can adapt

Here's a hypothetical Apply to Specific Files rule. Save it as .cursor/rules/api-routes.mdc:

---
description: Conventions for API route handlers
globs: src/app/api/**/*.ts
alwaysApply: false
---

- Validate every request body with zod before using it
- Return errors as an object with `code` and `message`, never a raw string
- Keep database calls in `src/lib/db/`, not inside the route file
- For a new route, follow the structure in @route-template.ts

Three things are doing the work here. The glob keeps the rule out of every conversation that isn't about API routes. The bullets are specific enough that Agent can check its own output against them. And @route-template.ts points at a real file instead of pasting code into the rule, which keeps the rule short and stops it going stale when the template changes.

You don't have to write the frontmatter by hand. Type /create-rule in Agent and describe what you want, and it writes the file with the right frontmatter into .cursor/rules. Or open Customize → Rules → Add Rule. The Cursor help page on rules also lists a "New Cursor Rule" command in the command palette.

.cursorrules vs .cursor/rules: how to migrate

If your repo still has a .cursorrules file at the root, it's running on borrowed time. Cursor's help page says plainly that the file "is legacy and will be deprecated."

The migration Cursor recommends is short:

1. Open the command palette and run New Cursor Rule.
2. Paste the contents of .cursorrules into the new file.
3. Set the rule type to Always Apply. That matches how .cursorrules behaved.
4. Delete .cursorrules from the project root.

Then go one step further than Cursor's checklist. An old .cursorrules file is usually one long wall of instructions for every part of the stack. Split it. Keep the handful of truly global rules as Always Apply, and move the frontend, backend, and test sections into their own files with globs. Your context window will thank you, because Agent stops loading your SQL conventions while you edit a CSS file.

The extension trap. Project rules must end in .mdc. A plain .md file inside .cursor/rules/ is ignored, because it has no frontmatter to tell Cursor when to apply it. This is the most common reason a freshly migrated rule seems to do nothing.

AGENTS.md, CLAUDE.md, and nested rules

Not every project needs four apply modes. For simple repos, Cursor supports AGENTS.md, an open format for agent instructions that other coding agents read as well. It's plain markdown with no metadata. Put it in the project root and Cursor picks it up automatically.

Nested AGENTS.md files work. You can drop an AGENTS.md into frontend/, backend/, or any other subdirectory. Cursor applies it when you're working with files in that folder or below, combines it with the parent files, and lets the more specific file win. That gives you folder-level scoping without writing a single glob. If you want help drafting one per folder, the AGENTS.md generator skill writes them from your codebase.

Cursor also reads CLAUDE.md. Per the help page, a CLAUDE.md in the project root is treated the same way as AGENTS.md, and it's always applied regardless of any alwaysApply setting. Cursor does this for compatibility with repos that also use Claude Code. If you split time between the two tools, our CLAUDE.md guide covers how Claude Code's memory files are structured, and Claude Code vs Cursor covers when each tool fits.

Inside .cursor/rules/ itself, subfolders work: Cursor scans the whole folder, so .cursor/rules/frontend/components.mdc is a valid rule. Cursor's help page still recommends a flat folder with descriptive filenames, because it's easier to manage. Rules are identified by full path, so two files with the same name in different folders both apply and don't override each other.

What makes a rule actually work

Cursor's docs give a short list of practices. They line up with what goes wrong in real repos:

The last row is the useful one. Start with no rules. Add one the second time you correct Agent on the same thing. Rules written in advance tend to describe the codebase you wish you had. Rules written after a repeated mistake describe the one you have.

Two limits to keep in mind. Rules only apply to Agent (Chat); they don't affect Tab completion, Inline Edit, or Bugbot PR reviews. And if you want to share rules from a GitHub repo, Cursor won't import them on their own. You package them in a Cursor plugin, publish it through a marketplace, and install that. For a ready-made starting point, the community-maintained awesome-cursorrules repo collects .mdc rule files for many frameworks and workflows. Read one before you adopt it: a rule written for someone else's repo describes their conventions, not yours.

Rules are one person's setup, written down

A good .cursor/rules folder is a piece of someone's working environment in text form. It captures what they learned from correcting Agent over and over. That's valuable, and it's also only half the picture: the rules assume Cursor, a working repo, and a stack that already runs.

The other half is the harder part for a lot of people. You see a setup someone shared, and the rules file is the easy bit. The environment behind it is what stops you. Taku is built for that step: an AI-native desktop workspace where you mirror an AI app, skill, or workflow someone already got working, run it, remix it, and keep it. It isn't an editor, and it doesn't replace Cursor for people writing code every day. Taku is in Beta, and the Mac app is available now. If Cursor itself isn't the right fit, our Cursor alternatives guide sorts the options by what you actually want.

FAQ

What are Cursor rules?

Persistent instructions that Cursor includes at the start of the model's context, so Agent follows your conventions without you repeating them. They can be project rules in .cursor/rules/, user rules, team rules, or an AGENTS.md file.

Where do Cursor project rules go?

In .cursor/rules/ at the root of your project, as .mdc files with frontmatter. Subfolders inside that directory work, but a plain .md file there is ignored.

Is .cursorrules deprecated?

Cursor calls it legacy and says it will be deprecated. Move its contents into a new project rule set to Always Apply, then delete the old file.

What's the difference between .mdc and AGENTS.md?

An .mdc rule has frontmatter, so you can scope it by glob, let Agent decide, or load it only on mention. AGENTS.md is plain markdown with no conditions beyond which folder it sits in, and other coding agents can read it too.

Why isn't my Cursor rule being applied?

Check the extension first (.mdc, not .md). Then check the mode: Apply Intelligently needs a description, and Apply to Specific Files needs a glob that matches the files you're working on. Remember that rules don't apply to Tab or Inline Edit at all.

Do Cursor rules work with Claude Code?

Not directly. Claude Code doesn't load .cursor/rules as live rules, but its /init command reads your Cursor rules (and a legacy .cursorrules) and folds the relevant parts into the CLAUDE.md it generates. Going the other way, Cursor reads CLAUDE.md, and Claude Code reads AGENTS.md by default when there's no CLAUDE.md. A shared instruction file is the simplest way to give both tools the same guidance.