Playbooks · Coding agents
Why Cursor ignores your rules, and how to fix it
Written October 26, 2026 · Edited November 19, 2026
For a solo developer × rules that sit on disk while the agent does something else × Cursor project rules, ending with every rule in the loading mode you actually intended — and a test that proves each one loads before you trust it again.
Before you start
You need a project with rules already written — the ones being ignored — in .cursor/rules/, and a fresh Cursor chat to test in. You do not need to rewrite a single rule's body to start: most "ignored" rules have correct bodies and wrong frontmatter, and this page fixes the frontmatter first. The loading model below is Cursor's own rules documentation, and the tests are behavioral checks you run in your own editor.
The one fact that reframes the whole problem: a rule that was never loaded was not ignored. The model cannot follow instructions it never received, so "the agent ignores my rules" usually means "my rules never reached the model," and the fix is in the file, not in the prompt.
What "done" looks like
At the end of one sitting every rule file in .cursor/rules/ has frontmatter that puts it in the mode you intended, the legacy single-file rules (if any) have moved into the current format, and each rule has passed a visible test in a fresh chat: the behavior it demands shows up in the agent's output, or you know it did not load and why.
Steps
- Learn the four modes, because the frontmatter is the whole mechanism. Cursor's docs describe project rules as
.mdcfiles in.cursor/rules/, and three frontmatter fields —alwaysApply,description, andglobs— decide when a rule reaches the agent. The docs' own table gives four combinations:alwaysApply: truemeans always included, and globs and description are ignored;alwaysApply: falsewith globs provided means auto-attached when a matching file is in context;alwaysApply: falsewith a description and no globs means the agent reads the description and pulls the rule in when it judges it relevant; andalwaysApply: falsewith neither description nor globs means included only when you @-mention the rule in chat. There is no fifth mode, and there is no "load everything" default. - Audit every rule file and name its actual mode. Open each file in
.cursor/rules/and write down, per file, which of the four modes its frontmatter produces. Do not go by what you meant when you wrote it, and do not go by the filename. Most audits end here with the diagnosis already in hand: the rule you expected to fire on every task has no frontmatter at all, which makes it manual-only, and it has never fired because you never @-mentioned it. - Fix the silent default first: a rule with no frontmatter is manual. A rule with no
alwaysApply, noglobs, and nodescriptionloads only when explicitly @-mentioned. If that was not your intent, give it one of the other three modes: add globs if it is about specific files, add a description if it is about a kind of task, or setalwaysApply: trueif it genuinely belongs in every session. This single fix resolves the most common "ignored rule" report, and it costs nothing but frontmatter. - Give file-scoped rules globs, not descriptions. A rule about API routes, test files, or components should carry the glob that matches those files — the docs' own examples use patterns like
**/*.tsfor all TypeScript files anywhere,src/**for everything under a directory, and comma-separated patterns for several directories. Auto-attachment is a deterministic match on a file in context, which makes it the most reliable mode: it does not depend on the model judging relevance. A file-scoped rule left in agent-decided mode depends on exactly that judgment, and judgment is where rules go to be silently skipped. - Write agent-decided descriptions as a statement of when the rule applies. For rules that are about a kind of task rather than a set of files, the description is the only thing the agent sees when deciding whether to pull the rule in. Write it as a precise statement of the situation the rule covers — the task, the area, the trigger — not as a summary of the rule's contents and not as a vague aspiration. A description that says what the rule is about gives the agent nothing to match against; a description that says when the rule applies gives it the match itself.
- Keep always-apply rules short, and check the file extension. Two separate traps live here. First, the docs advise keeping rules under 500 lines and splitting large rules into composable pieces — and an always-apply rule loads into every session, so a long one taxes every chat, not just the ones it concerns. Second, project rules must use the
.mdcextension: the docs state plainly that a plain.mdfile in.cursor/rules/is ignored by the rules system because it has no frontmatter to specify the three fields. If your guidance still lives in a single legacy rules file at the repo root, there are two documented routes: move it into.mdcfiles in.cursor/rules/, or keep it as plain markdown in a rootAGENTS.md— the Cursor rules documentation namesAGENTS.mdas the plain-markdown alternative, andAGENTS.mdfiles placed in subdirectories are applied automatically to work in that directory and its children. What does not work is leaving it in the old single-file format: the current docs do not describe that file at all. - Put must-always content in the rule body, not behind a reference. The docs warn that a file mentioned inside a rule is read by the agent with its tools when needed, and its contents are not inlined into the prompt. Referencing a canonical example is good practice for keeping rules short and fresh, but anything that must always be in context — a naming rule, a forbidden pattern, a required header — belongs pasted in the body itself. A rule that only points elsewhere leaves its most important instruction out of the context it was supposed to govern.
- Test each rule with a visible tell, in a fresh chat. Give the rule a temporary, observable requirement — for example, that every new test file gets a header comment naming the module it covers — then open a fresh chat, do the kind of task the rule governs, and check whether the tell appears in the output. For a glob rule, reference a matching file first; for an agent-decided rule, ask about exactly the topic its description names; for a manual rule, @-mention it and confirm it applies. If the tell does not appear, the rule did not load: go back to step 2 and re-check the frontmatter, because the frontmatter is almost always the answer. Remove the tell once the rule passes, and keep the test procedure — re-run it whenever a rule changes, since a frontmatter edit can silently change a rule's mode.
Check the agent's work
- Check that every file in
.cursor/rules/ends in.mdc. A.mdfile in that directory is ignored, however good its contents. - Check that no rule you expect to fire automatically has empty frontmatter. Empty frontmatter is manual mode, and manual rules fire only on @-mention.
- Check that every file-scoped rule carries a glob that actually matches its files. A glob for the wrong directory is the same as no glob, with more confidence.
- Check that always-apply rules are short. A long always-apply rule loads into every session, including the ones it has nothing to do with.
- Check that must-always instructions are pasted in the rule body, not only referenced. Referenced files are read on demand; their contents are not inlined.
What can go wrong
- Diagnosing a loading problem as a model problem. Rewriting the rule body, rewording the prompt, or switching models will not fix a rule that never loaded. Check the frontmatter first, every time, before blaming the model.
- Everything always-apply. Marking every rule always-apply guarantees they all load and guarantees every chat carries guidance most of it does not need. The docs' advice is to keep rules under 500 lines and split them; scoping by glob or description is what makes a large rule set affordable.
- A vague description on an agent-decided rule. The agent decides from the description alone. A description that could match anything matches nothing in practice, because nothing in it tells the agent this task is the one.
- Testing in the same chat where you wrote the rule. Context from the conversation can mask a loading failure: the agent may follow guidance it read in your messages rather than from the rule file. Test in a fresh chat, where the rule file is the only source of the instruction.
Limits
- This page covers project rules in
.cursor/rules/. User rules in Cursor settings, team rules from the dashboard, andAGENTS.mdfiles follow their own loading rules and are out of scope here, though the docs describe them alongside project rules. - Cursor does not document a way to ask the agent which rules it loaded for a given chat, so the tests on this page check behavior — the tell in the output — rather than a loading report. A rule that passes the tell test loaded; a rule that fails it did not, whatever the reason.
Related playbooks
- Copilot CLI 1.0.109: CIDR sandbox rules
- Cursor Agent SDK: define an agent as a folder
- Cursor Agent SDK is GA, with 300-repo environments
- Cursor builds live apps from cloud agents
Sources
Sources: Cursor rules documentation.
Back to: Coding playbooks hub · Also: Cursor starter kit