Blog
Cursor rules best practices, and why Cursor ignores them
Published: October 28, 2026
Put Cursor rules in .cursor/rules/ as .mdc files with frontmatter, one topic per file, each under 500 lines. Make only the few rules every task needs alwaysApply; attach the rest by glob or by description. Rules only reach Agent (Chat), never Tab or Inline Edit. If a rule does not fire, check its type first.
Everything below was checked against Cursor's rules docs and its help page on 2026-09-23, and the User Rules row again on 2026-10-06. Cursor has changed this system several times, and most guides that rank for it still describe .cursorrules.
What are the types of Cursor rules?
Cursor reads four kinds of instructions. They are applied in the order Team Rules, then Project Rules, then User Rules, and when two conflict the earlier one wins.
| Kind | Where it lives | Who writes it | Shared with |
|---|---|---|---|
| Project Rules | .cursor/rules/*.mdc in the repo | Anyone with commit access | Everyone who clones the repo |
| Team Rules | Cursor's dashboard | Team admins (Team and Enterprise plans) | Every member, can be enforced so users cannot switch it off |
| User Rules | Customize, then Rules (synced with your account), or files in ~/.cursor/rules (this machine only) | You | Only you, only in Agent (Chat) |
AGENTS.md | Repo root and any subdirectory | Anyone with commit access | Everyone, and every other tool that reads AGENTS.md |
Cursor also reads CLAUDE.md “the same way it reads AGENTS.md”, per its help page. If your team already keeps a CLAUDE.md for Claude Code, Cursor sees it too. The file-by-file comparison across tools is in AGENTS.md vs CLAUDE.md.
Is .cursorrules deprecated?
Yes. Cursor's help page says the root .cursorrules file “is legacy and will be deprecated.” To move it, create a rule with the command palette's New Cursor Rule, paste the old content in, set it to Always Apply (that matches how .cursorrules behaved), and delete the old file. Then split it, because the old file was one block that went into every chat.
How do you write a .mdc rule?
A .mdc file is markdown with a frontmatter block. Three fields decide when it loads:
--- description: Payment webhooks, retries and idempotency globs: src/payments/** alwaysApply: false --- - Webhook handlers must be idempotent. Key on the provider's event id. - Retries use the shared backoff in src/lib/retry.ts. Do not write a new one. - See docs/decisions/0012-webhook-retries.md for why we stopped at 5 attempts.
A plain .md file in .cursor/rules/ is ignored, because it has no frontmatter. That one detail accounts for a lot of “my rule does nothing” threads.
Always, Auto Attached, Agent Requested, Manual: which should you use?
| Mode | Frontmatter | Loads when | Use it for |
|---|---|---|---|
| Always Apply | alwaysApply: true | Every chat session | The handful of rules that are true for every task |
| Apply to Specific Files | globs: src/payments/** | A matching file is in context | Rules about one part of the codebase |
| Apply Intelligently | description: … | Agent judges the description relevant | Topic rules that do not map to paths |
| Apply Manually | none of the above | You type @rule-name | Checklists and procedures you invoke on purpose |
The default instinct is to make everything Always Apply, because then you know it is there. That is the same mistake as a CLAUDE.md that only grows: every always-on line is in the prompt of every chat, including the chats it has nothing to do with. Globs are the cheapest way to keep a rule out of the prompt until it applies.
An Apply Intelligently rule is picked by its description, the way a skill is, and since Cursor 2.4 the built-in migrate-to-skills skill turns those rules into skills. When to write which, in Cursor and in the other three agents, is in rules vs skills. If you are here because Cursor stopped remembering things, that was Memories, removed in 2.1: what replaced Cursor Memories.
Cursor rules best practices
Cursor's own guidance is short: keep rules under 500 lines, split large rules into composable ones, and reference files instead of copying their contents. What teams learn after a few months:
| Practice | Why |
|---|---|
| One topic per file | A rule you can name is a rule you can find, glob and delete. |
| Write the reason, not only the rule | A rule with its why survives the next refactor. A bare "never do X" gets deleted by the first person who does not know what X broke. |
| Point at the code, do not paste it | A pasted snippet goes stale the day the code changes. A path stays true longer. |
| Only what the model cannot infer | Linters, formatters and the code itself already say how the repo looks. Rules are for what is not in the code: decisions, exceptions, history. |
| A hook for anything that must never happen | A rule asks. Cursor hooks run on events and can stop an action. A rule is context, not enforcement. |
| Date and own each rule | Rules grow by addition and are rarely removed. An owner is who you ask before you cut one. |
The last row is where the research is. A 2026 study that mined 7,310 rules across five AI IDEs, Cursor among them, found that rule files change mostly by expansion, and that developers add negative constraints after the model makes a mistake (arXiv:2606.12231). Rules are written after incidents and almost never retired. More on that in context rot and stale rules.
Why are my Cursor rules not working?
Work down this list. Each item is a documented behaviour, not a bug.
| Symptom | Likely cause | Fix |
|---|---|---|
| Rule never loads | It is a plain .md file, or it has no frontmatter | Rename to .mdc and add the frontmatter block |
| Rule ignored in Tab or Cmd+K | Rules only apply to Agent (Chat) | Nothing to fix. Tab, Inline Edit and Bugbot reviews do not read rules |
| Apply Intelligently rule never picked | Missing or vague description | Write the description as the task it is for: "Payment webhooks, retries and idempotency" |
| Glob rule never picked | No matching file is in context yet | Open or mention a matching file, or widen the glob |
| Project rule overridden | A Team Rule says otherwise | Team Rules win. Fix the conflict at the team level |
| Rule loads but is not followed | Too many competing rules, a long session, or a rule that is no longer true | Fewer always-on rules, a fresh chat, and a hook for hard limits |
The last row is the hard one, and it is not specific to Cursor. A factorial study of 1,650 Claude Code sessions found that none of four file-structure variables changed adherence in a detectable way, while compliance fell as the session went on (arXiv:2605.10039). How you format the file matters less than how many rules compete and how long the chat has run. The same causes, for Claude, are in why Claude ignores CLAUDE.md. The free rule-file checker also says whether Cursor loads a file from where it sits.
How do you share Cursor rules with your team?
Commit .cursor/rules/ and review rule changes like code. On a Team or Enterprise plan, rules that must hold for everyone can be Team Rules, set by an admin in the dashboard and enforced so members cannot switch them off. How they rank against Project Rules, and how Copilot and Claude Code handle the same job, is in Cursor Team Rules.
Two gaps remain. First, both are Cursor only. Half the team is in Claude Code or Codex, and a Team Rule does not reach them. Committing AGENTS.md narrows that gap for the rules you have written down, since Cursor, Codex and Copilot read it and Claude Code can.
Second, somebody has to write the rule. The decisions behind most rules were made somewhere else first: a pull request review where a senior engineer said “we do not retry non-idempotent calls,” a thread in #eng-payments that settled the webhook retry limit. Until someone copies that into a rule file, Cursor does not know it, and neither does any other agent. See turning review comments into agent rules.
Where Harbor fits
Harbor reads the places those decisions are made (Slack threads, pull request reviews, docs), and a person approves what becomes a fact, or a policy you set approves the routine ones. The same approved facts then reach Cursor, Claude Code and Codex, so a decision is written once instead of once per tool.
In Cursor, harbor init installs Harbor's hooks and adds it to ~/.cursor/mcp.json. Cursor gets the team's facts that apply to the repo at session start and, on the Cursor 3.17 app or later, on every prompt, and the agent can search for more over MCP when a task needs it. Each answer cites the facts it used as [#1], [#2], and Harbor counts, per fact, how often it was served against how often it was cited. A fact served for months and never cited is the first one to question. A cite is evidence, not proof: an uncited fact may still have shaped an answer. That is served vs cited.
Questions
Where do Cursor rules go?
Project rules go in .cursor/rules/ as .mdc files with a frontmatter block. Cursor also reads AGENTS.md and CLAUDE.md in the project root. Team Rules are set by an admin in the Cursor dashboard on Team and Enterprise plans.
Is .cursorrules deprecated?
Yes. Cursor calls the root .cursorrules file legacy. Move its content into a rule in .cursor/rules/, set it to Always Apply to match the old behaviour, then split it by topic.
Why is my Cursor rule not being applied?
The most common causes are a plain .md file instead of .mdc, missing frontmatter, a vague description on an Apply Intelligently rule, or a glob that matches no file in context. Rules also never apply to Tab or Inline Edit.
Do Cursor rules apply to Tab completion or Cmd+K?
No. Cursor rules only apply to Agent (Chat). They do not apply to Tab completion, Inline Edit or Bugbot reviews.
Does Cursor read CLAUDE.md?
Yes. Cursor reads CLAUDE.md the same way it reads AGENTS.md, so a CLAUDE.md in the project root is picked up automatically.