Cursor Rules Not Working? 8 Fixes, Checked Against the Docs

Published 2026-10-18 · 5 min read · by AgentKit Co

You wrote rules, and Cursor's agent still does its own thing. Almost every time, the cause is one of a short list: the file isn't being loaded at all, it loads only in situations you didn't expect, or it loads and is too long or vague to follow.

This page walks through that list in order. Everything here was checked against Cursor's Rules docs on 2026-10-18. Cursor changes quickly, so re-check the docs for anything you depend on.

1. The file has the wrong extension

Project rules live in .cursor/rules/ and must end in .mdc. Cursor's docs say a plain .md file in that folder is ignored by the rules system, because it has no frontmatter to say when it applies.

.cursor/rules/
  react-patterns.mdc     # loaded
  api-guidelines.md      # ignored (wrong extension)
  frontend/
    components.mdc       # subfolders are fine

If you prefer plain Markdown with no frontmatter, use an AGENTS.md file in the project root instead (see fix 7).

2. You are relying on an old .cursorrules file

Cursor's current Rules page describes four kinds of rules: project rules in .cursor/rules, user rules, team rules and AGENTS.md. It does not mention a single root .cursorrules file. If yours seems to be ignored, don't debug it: move its contents into .cursor/rules/*.mdc files or an AGENTS.md.

3. The frontmatter doesn't say "apply this when you think it does"

Three frontmatter fields decide when a rule is included. This is the table from Cursor's docs, in plain words:

The last row is the classic trap: a rule with no description and no globs looks fine in the editor but never loads unless you mention it. Cursor's own FAQ answer to "Why isn't my rule being applied?" is to check this: an "Apply Intelligently" rule needs a description, and an "Apply to Specific Files" rule needs a pattern that matches.

A rule you want on every request:

---
alwaysApply: true
---

- Run `pnpm test` for the files you changed before saying a task is done.
- Never edit files in `dist/` or `build/`.

4. The glob doesn't match the files in context

A file-scoped rule only attaches when a matching file is in the conversation. Patterns from the docs:

*.ts when you meant **/*.ts is the most common slip. Also remember the rule attaches only when a matching file is actually in context, so a brand new chat with no files open may not trigger it.

5. The description is too vague to be picked

For "Apply Intelligently" rules, the agent sees only the description when deciding. "Backend stuff" gives it nothing to match. Name the situation instead: "Conventions for RPC services under src/services/: validation, errors and file layout."

6. The rule is long, vague or a copied style guide

Cursor's best practices: keep rules under 500 lines, split big rules into smaller ones, give concrete examples, and write them like clear internal docs. Their "what to avoid" list includes copying whole style guides (use a linter), documenting every command the agent already knows, and edge cases that rarely apply.

A good test for each line: would the agent get this wrong without it? If not, cut it. Shorter rules leave more room for the lines that matter.

7. Two sources disagree

Rules stack up. Cursor merges team rules, project rules and user rules, and the docs say earlier sources win when guidance conflicts: Team → Project → User. AGENTS.md files can also be nested in subfolders; instructions combine with the parent folders, and the more specific file wins.

So if a project rule says "use Jest" and a team rule says "use Vitest", the team rule wins. Search all your rule sources for the conflicting topic before rewriting anything.

8. You expected a rule to do something rules don't do

Three things that surprise people, all from Cursor's docs:

• Rules don't affect Cursor Tab or other AI features. They are for the agent (chat).
• User rules don't apply to Inline Edit (Cmd/Ctrl+K).
• @file mentions inside a rule are not pasted in. A mention like @service-template.ts tells the agent where to look, and it reads the file with its tools when it needs it. If something must always be in context, put it in the rule body.

And the big one: rules are guidance, not enforcement. If something must never happen (deleting files, pushing to main, reading .env), add a technical guard such as a git hook, CI check or tool permission rather than a stronger sentence.

A quick checklist

1. File is .cursor/rules/name.mdc, not .md, and not a root .cursorrules.
2. Frontmatter matches how you want it applied (table in fix 3).
3. Globs use **/ when you mean "any folder".
4. Descriptions name a concrete situation.
5. Each rule is short, specific and under 500 lines.
6. No team, user or nested AGENTS.md rule contradicts it.
7. Anything that must never happen has a real guard, not just a rule.

Start from a working file

If you'd rather not start from a blank page, our free AGENTS.md generator builds an AGENTS.md plus a Cursor rule (project-baseline.mdc with alwaysApply: true) in your browser. You can paste your package.json or pyproject.toml and it fills in your real commands. For file-scoped .mdc rules and templates for 12 stacks, see the AI Coding Agent Config Kit.

Sources: Cursor Rules docs (checked 2026-10-18). Related: AGENTS.md vs CLAUDE.md vs Cursor rules and how to write an AGENTS.md. AgentKit Co is not affiliated with Cursor or Anysphere. This guide was written with AI assistance and checked against the page above.

Keep reading