Home › Coding & Cursor Rules

Cursor Rules Not Working? .mdc Fix Checklist + Starter Rules

Why Cursor ignores your rules (plain .md files, missing frontmatter, wrong globs) plus a correct .mdc starter pack you can copy into .cursor/rules/.

Copy template

# Cursor rules not applying? Check these in order.

1. Location: rules live in .cursor/rules/ at the project root (not in .cursor/ or docs/).
2. Extension: the file must end in .mdc, not .md. A plain .md file is silently ignored.
3. Frontmatter: the very first line is --- with no blank line or BOM before it.
4. Rule type, set by frontmatter:
   - Always on:     alwaysApply: true
   - Auto-attached: globs: src/**/*.tsx  (only loads when a matching file is in context)
   - Agent-picked:  description: "When to use this rule"  (alwaysApply: false, no globs)
   - Manual:        no description, no globs, alwaysApply: false  (only when you @mention it)
5. Globs: comma-separated, no quotes, relative to the project root. "src/**/*.ts" in quotes or a leading ./ can fail to match.
6. Length: keep each rule under ~100 lines. Split big rules by topic so each one loads only when needed.
7. Test it: open a new chat, ask "Which project rules are active right now? List their file names." If yours is missing, recheck 2-5.

# Starter pack (copy each block into its own file)

## .cursor/rules/core.mdc
---
description: Core project rules
alwaysApply: true
---
- Stack: [FRAMEWORK, LANGUAGE, DB]. Don't add dependencies without asking.
- Plan first: list files you'll change, then make the smallest change that works.
- Run [CHECK COMMAND] before saying done, and report the result.

## .cursor/rules/frontend.mdc
---
description: React component conventions
globs: src/components/**/*.tsx,src/app/**/*.tsx
alwaysApply: false
---
- Function components, named exports, props typed with an interface.
- Use [DESIGN SYSTEM / COMPONENT LIBRARY] components before writing new ones.
- No inline styles; use [Tailwind / CSS modules].

## .cursor/rules/tests.mdc
---
description: Testing rules
globs: **/*.test.ts,**/*.spec.ts
alwaysApply: false
---
- Test behavior, not implementation. One assertion focus per test.
- Never delete or weaken a test to make it pass.

How to use it

1. Click Copy template.
2. Paste into ChatGPT, Claude, Grok, Cursor, or your agent framework.
3. Replace the [BRACKETED] parts with your details.

FAQ

Why does Cursor ignore my rules file?

The most common cause is saving it as .md instead of .mdc, or a missing or malformed frontmatter block. Cursor only loads .mdc files from .cursor/rules/.

alwaysApply or globs?

Use alwaysApply: true for a few short project-wide rules. Use globs for anything that only matters for certain files, so it doesn't eat context on every request.

Can I keep using AGENTS.md too?

Yes. Put shared rules in AGENTS.md and use .mdc files for file-specific rules, or add a one-line alwaysApply rule that points at AGENTS.md.

Related templates

Browse all Coding & Cursor Rules templates

New on PromptLoot