Cursor Rules: How to Write .cursor/rules That Change Output

Cursor rules change the output when they are short, specific, and actually loaded into the agent's context. Most "ignored" rules are activation problems, such as the wrong file extension, the wrong scope, or too much text. Write a few small .mdc files with concrete instructions, scope them to the files they matter for, and check that they load.

What cursor rules actually are

Rules provide system-level instructions to Agent. You write your conventions once instead of retyping them in every prompt. Project Rules are stored in .cursor/rules, version-controlled and scoped to your codebase.

There are other kinds too. User Rules are global to your Cursor environment, and Team Rules are managed from the dashboard on Team and Enterprise plans. If you're a solo builder, you'll mostly use Project Rules and sometimes User Rules.

One limit to know about: Cursor's current documentation says rules don't apply to Tab completion or Inline Edit (Cmd/Ctrl+K). They shape the agent, not every feature in the editor.

The file format (and the extension trap)

A rule is a markdown file with a small frontmatter block at the top. Project rules must use the .mdc extension, and a plain .md file in .cursor/rules is ignored because it has no frontmatter. That is the most common silent failure. If you'd rather write plain markdown, use AGENTS.md instead.

You can also organize rules in subfolders. A file like frontend/components.mdc still counts as a rule.

A note on the newer folder format

The docs have been inconsistent here. A reference copy of the docs says as of 2.2, .mdc rules remain functional but new rules are created as folders in .cursor/rules. The current docs page I checked still describes .mdc files. On the forum, users reported that rules only appeared in Settings when using flat .mdc files directly in .cursor/rules/. I can't tell you which version you'll hit. Flat .mdc files are the safe default, and you can check Settings to confirm yours are detected.

The four ways a rule gets loaded

The frontmatter decides when the rule is included. This is where most of the "does anything change?" confusion comes from.

This matches how a third-party best-practices guide lays out the types. Use "always" for things true everywhere, like your stack and folder layout. Use globs for rules tied to a file type, such as app/api/**/*.ts. One common mistake is setting everything to alwaysApply, and the fix is to use globs and intelligent rules for scoped content.

A starter set that works

Start with two files. The first holds project context, always on:

---
description: Core project context
alwaysApply: true
---
- Stack: Next.js (App Router), TypeScript, Supabase, Tailwind.
- Use server actions for mutations. No new API routes unless asked.
- Never edit files in /migrations. Propose a new migration instead.
- Before finishing, run `npm run lint` and `npm run typecheck`.

The second is scoped to one area:

---
description: Conventions for API routes
globs: app/api/**/*.ts
alwaysApply: false
---
- Validate every request body with zod at the top of the handler.
- Return { error: string } with the right status code on failure.
- Prices are integers in cents. Never use floats for money.

The second example borrows the pattern from a DEV Community post on team rules, which uses a similar glob-scoped file for a checkout service. Notice what these have in common: each line is a fact or a command you could check. Nothing says "write clean code."

How to write rules the agent will follow

1. Write what to do, not what to be

"Write maintainable, well-structured code" gives the model nothing to act on. "Put shared UI in components/ui, one component per file" does. Name real paths, commands, libraries, and versions.

2. Add rules after the agent gets something wrong

Don't try to write the perfect rulebook on day one. Cursor suggests adding rules when you see the agent make the same mistake again. The first time is a prompt fix. The second time it goes in a rule.

3. Keep each file small

Cursor suggests keeping each rule under 500 lines, and shorter is usually better. The docs also advise splitting large rules into multiple, composable rules. A rule with twelve unrelated topics is harder for the model to weigh than three rules with four lines each.

4. Say what to do instead

"Don't use any" leaves the model guessing. "Don't use any; use unknown and narrow it" tells it the replacement.

5. Point to examples instead of pasting them

Reference a good existing file, like @components/ui/button.tsx, rather than pasting a long code sample into the rule. That keeps the rule short and the example current.

6. Put the guardrails where they matter

Security and data rules should be explicit, such as "never log request bodies" or "every Supabase table gets RLS." Rules are a good place for the checks in AI generated code security: 6 mistakes and how to fix them. They won't replace reviewing the code, though.

Rules, AGENTS.md or neither?

AGENTS.md goes in your project root as a simple alternative to .cursor/rules, and it's plain markdown with no metadata. If you use more than one coding tool, it's the easier choice. One guide suggests putting shared fundamentals in AGENTS.md and Cursor-only behavior, like globs or manual invocation, in .cursor/rules. If you're comparing tools, Cursor vs Claude Code vs Windsurf covers where each one fits.

For things the agent needs to do, such as query a database or read docs, a rule is the wrong tool. That's a job for MCP servers.

When a rule isn't working

StackHawk's guide makes a useful point: most Cursor rules that appear broken are activation problems, not content problems. Check these in order:

1. Extension. Is it .mdc, not .md?
2. Location. Is it inside .cursor/rules? A forum reply says Cursor detects project rule files only there. Nested .cursor/rules folders in subdirectories also work.
3. Scope. A glob rule only loads when a matching file is in context. If you're chatting without opening or attaching the file, it won't fire.
4. Description. For intelligent rules, the description is all the agent sees when deciding. Make it specific.
5. Global rules. Staff replies on the forum say using ~/.cursor/rules/*.mdc for all projects isn't supported, and global preferences belong in User Rules. That reply is from early on, so check whether it still holds for your version.
6. Conflicts. Two rules that contradict each other produce erratic output. Search your rules for opposing instructions.

A prompt to audit your rules

Paste this into the agent once you have a few files:

Read every file in .cursor/rules and any AGENTS.md.
1. List instructions that are vague or can't be checked.
2. List any that contradict each other.
3. Flag anything marked alwaysApply that only matters for certain files, and suggest a glob.
4. Rewrite the vague ones as concrete, checkable instructions.
Don't change anything yet. Show me the proposed edits.

Then do a test. Make a request that should trigger a rule, such as "add an endpoint," and see whether it follows it. If the answer is no, go back to the checklist above.

Rules are one layer, not the whole thing

Rules set defaults. The request itself still matters, so pair them with good prompts, as in Prompts for AI Coding. Commit .cursor/rules to git so you can see what changed when behavior shifts. Built something with a good rule setup? Share it at xvibers.com/built.

FAQ

Where do I put cursor rules?

Put them in .cursor/rules at your project root as .mdc files. You can create one with the New Cursor Rule command or from Cursor Settings. Commit the folder so the rules are version-controlled with your code.

Should I use alwaysApply on everything?

No. Reserve it for context that's true on every task, like your stack, key commands and hard prohibitions. Scope the rest with globs or a clear description so the agent isn't loading rules that don't apply to the task.

What's the difference between .cursor/rules and AGENTS.md?

AGENTS.md is plain markdown with no metadata, and other tools can read it too. .cursor/rules files have frontmatter, so you get scoping by file pattern and manual invocation. Plenty of projects use AGENTS.md for shared basics and .cursor/rules for Cursor-specific behavior.

Cover photo: AltumCode on Unsplash