How to write Cursor rules that keep the AI agent on track
Where Cursor rules live, the four rule types, what a useful rule says in a real project, why rules get ignored, and how to test and share them with other tools.
Leer en español →
Good Cursor rules are short, specific project instructions saved as .mdc files in .cursor/rules (or as a plain AGENTS.md), each covering one topic. Only a few should apply to every request; the rest should load for the files they're about. They work best when they state your stack and commands, the things the agent must never do without asking, and what "done" means, and when anything that truly must not happen is also blocked by a setting or a test.
This guide covers where rules live, how the four rule types work, what to put in them for a real project, why agents ignore them, and how to check that a rule is doing its job.
Where do Cursor rules live?
Cursor reads instructions from several places. They stack, so it helps to know which one to use for what.
| Kind | Where | Good for |
|---|---|---|
| Project rules | .cursor/rules/*.mdc, committed with the code | Anything about this project: stack, conventions, boundaries |
| AGENTS.md | A plain Markdown file in the project root, optionally more in subfolders | Instructions you also want other tools to read |
| User rules | Cursor settings, under Customize → Rules | Your personal preferences across all projects |
| Team rules | The Cursor dashboard, on Team and Enterprise plans | Company-wide rules an admin can enforce |
Two details trip people up. A plain .md file inside .cursor/rules is ignored; project rules must be .mdc. And user rules apply to the Agent chat, not to inline edits (Cmd/Ctrl+K). When rules conflict, team rules win over project rules, which win over user rules.
If your project still has a single .cursorrules file in the root from an older setup, move its contents into .cursor/rules or AGENTS.md, which is what Cursor's current documentation describes.
What are the four rule types?
Each project rule has a small header that decides when it loads. In the editor you pick the type from a dropdown; underneath, it's three fields:
---
description: How we query Supabase and change the database schema
globs: supabase/**
alwaysApply: false
---- Always Apply (
alwaysApply: true): loaded into every request. Keep this to one or two short rules. - Apply Intelligently: only a
description. The agent reads the description and decides whether the rule is relevant. - Apply to Specific Files: a
globspattern. The rule attaches when a matching file is in the conversation. - Apply Manually: no description and no globs. It loads only when you mention it, for example
@release-checklist.
Cursor's rules documentation recommends keeping each rule under 500 lines and splitting large ones into smaller pieces that can be combined.
What should rules say in a real project?
Rules that work read like a briefing for a capable new hire on their first morning. Five areas carry most of the value.
The stack and the commands
Say what the project is built with and exactly how to run, test and build it. Agents waste a lot of effort guessing whether it's npm run dev or pnpm dev.
Boundaries
List what must not happen without your explicit approval: editing migrations that already ran, touching .env files, adding dependencies, changing authentication or payment code, deleting files. Each of these is cheap to prevent and expensive to undo after the fact.
Conventions
Where new components go, how files are named, which helper to use for API calls, which UI library is already installed. This stops the agent from creating a second date-formatting function next to the first one.
Definition of done
Tell the agent what it must do before it says it's finished: run the build, run the tests, and list the files it changed.
Known traps
Write down the mistakes that already happened once. "Every new table needs Row Level Security policies" is worth more than a page of style advice.
Here is a compact always-on rule for a Vite and Supabase app:
---
description: Core project rules
alwaysApply: true
---
- Stack: React + Vite + TypeScript, Supabase for auth and data, Tailwind.
- Run: `npm run dev`. Check: `npm run build` and `npm test` must pass before you say a task is done.
- Never edit files in supabase/migrations that already exist. Create a new migration instead.
- Never read or change .env files. Ask me if a new environment variable is needed.
- Ask before adding any npm package, deleting any file, or changing auth or payment code.
- Reuse helpers in src/lib before writing new ones.
- At the end of each task, list every file you changed and why.Why does the agent ignore my rules?
Usually for one of these reasons:
- Too long. A 900-line rule competes with your actual request. The agent keeps the gist and drops details.
- Too vague. "Write clean, secure code" gives it nothing to act on. "Every query on
invoicesmust filter byorg_id" does. - Contradictory. One rule says to use the shared fetch helper, another example uses
axios. The agent picks one. - Out of date. The rule still describes a folder you renamed two months ago.
- Used as a lock. Rules are context, not enforcement. If something must never happen, block it with a setting too. Cursor's run modes include File-Deletion Protection, and
.cursorignorekeeps files away from the agent's file tools, though the docs note it does not stop terminal or MCP access.
How do I test that a rule works?
- Start a new chat so old context doesn't help.
- Give a task that should trigger the rule, for example "add a
notescolumn to invoices". - Check what happened: did it create a new migration instead of editing an old one?
- If not, make the rule more specific or change its type, then try again.
- Commit the rule with the code, so the next person (or agent) gets it too.
Review your rules whenever you change the structure of the project, the same way you'd update a README.
Can I share one set of rules with Claude Code, Copilot and others?
Mostly, yes, through AGENTS.md. Cursor reads it, GitHub Copilot reads it as agent instructions, and Claude Code reads it when the project has no CLAUDE.md. If you do keep a CLAUDE.md, it can import the shared file with a line like @AGENTS.md. Keep tool-specific details, such as Cursor's glob-scoped rules, in each tool's own format.
Quick answers
How many rules should a project have? Start with one short always-on rule and two or three file-scoped ones for the riskiest areas, such as the database and payments. Add more only when a mistake repeats.
Do rules cost anything? Always-on rules are sent with every request, so they use part of the context each time. That's another reason to keep them short.
Should rules be in English? Write them in the language you think in most clearly. What matters is that they're specific.
Can rules replace code review? No. They reduce the number of bad changes; they don't catch the ones that still get through.
Want a second pair of eyes on your setup?
If your agent keeps wandering in a large project, read how to use Cursor or Claude Code on a large codebase and how to review AI-generated code. When you'd rather have someone set up rules, tests and guardrails with you, our Cursor project help explains how that works, and you can reach a person here.
