Cursor Rules: Configure AI Behavior With .cursorrules

Cursor rules are saved instructions that tell Cursor's AI how to behave in your project (your framework, your coding style, your naming conventions, your do-nots) so the agent follows them automatically instead of you retyping them in every prompt. You configure them either as a single legacy .cursorrules file at your project root, or, better, as modern project rules stored as .mdc files inside a .cursor/rules folder, where each rule can be always on, attached by file pattern, or pulled in on demand.

Most guides treat them like a magic incantation and stop there. They are not magic; they are a system prompt you version-control. Understanding when each rule fires is what separates a config that helps from one the agent quietly ignores.

What are Cursor rules and why do they matter?

Every time you prompt Cursor, the model gets your message plus whatever context Cursor decides to include. Rules add a persistent layer to that context: standing instructions the agent should honor without being asked.

For a vibe coder building with Cursor, Lovable, Bolt, or v0, this is the difference between an agent that guesses your intent and one that already knows it. If your project is a Next.js app with Tailwind and you never want class components, a rule says so once. You stop babysitting the same corrections.

The payoff compounds. Without rules, every prompt starts from zero, and you re-explain your stack, your file layout, and your taste each time. With a solid rule set, the agent carries that briefing into every request, so your prompts get shorter and the output gets closer to what you wanted on the first try. For someone who cannot easily spot a subtle code smell, that consistency is worth more than any single clever prompt.

Rules are plain text or Markdown. You do not need to code to write them. A good rule reads like onboarding notes for a new teammate, not like a config file.

.cursorrules vs project rules: which should you use?

There are two formats, and they are easy to confuse.

The legacy .cursorrules file is a single file at your project root. It still works, but it is being phased in favor of the newer system, and it gives you one undifferentiated blob of instructions.

Project rules live in .cursor/rules/ as separate .mdc files. Each file has a small metadata header and a body. The win is granularity: you can have one rule for your API layer, another for your React components, and each only fires when relevant.

There are also User Rules in Cursor's settings that apply globally across every project, good for personal preferences like "always explain your reasoning briefly."

What are the four types of Cursor project rules?

This is the part people skip, and then wonder why a rule never triggers. Each .mdc rule has a type that controls when it enters context.

• Always — injected into every request in the project. Use sparingly; it costs context on every turn.
• Auto Attached — fires when you touch files matching a glob (for example *.tsx). The rule loads only when relevant.
• Agent Requested — the agent decides whether to pull it in, based on the rule's description. Write a clear description or it stays dormant.
• Manual — only loads when you @mention it by name.

The practical move is to make most rules Auto Attached by file pattern, keep one small Always rule for project-wide non-negotiables, and reserve Manual rules for occasional playbooks. That keeps your cursor context used indicator from ballooning, because you are not shipping every rule on every prompt.

A quick way to picture the tradeoff:

• Put your framework, language, and hard bans in one short Always rule.
• Put per-area conventions (components, API routes, tests) in Auto Attached rules scoped by glob.
• Put long reference material, like a full API style guide, in an Agent Requested rule with a precise description so the model knows when to reach for it.
• Keep rarely-used checklists as Manual rules you invoke by name.

Split this way, a request that touches a .tsx file loads your component conventions and nothing about your database layer. The agent gets exactly the guidance it needs and none it does not, which keeps both accuracy and context usage in a healthy place.

How do Cursor rules work with MCP and agent mode?

Rules and MCP solve different problems, and you will want both. Rules shape how the agent writes code. Model Context Protocol servers give the agent new abilities, like reading a database or your screen.

You register MCP servers in a cursor mcp json config file (mcp.json), and Cursor exposes their tools to the agent. If a server isn't showing up, it is almost always the JSON, not the server. Our walkthrough of Cursor MCP setup covers the config and the common failures.

In Cursor agent mode, the assistant can run multi-step tasks, edit across files, and call those MCP tools on its own. Rules ride along the whole time, so a well-scoped rule set keeps an autonomous agent from drifting. If you are new to this whole workflow, the roundup of vibe coding tools is a gentler starting point.

Why do rules not fix the "you changed the wrong thing" problem?

Because rules govern code style, not visual intent. You can write the perfect rule set and the agent will still edit the wrong button, because it never actually knew which button you meant.

This is the core pain for anyone building by feel. You look at the screen, something is off, and you type "make the top card bigger." The agent picks a card. Maybe the right one, often not. A cursor screenshot pasted into chat helps a little and costs a lot of tokens, and the agent still has to guess which pixels you care about.

The fix is a different input entirely. On a Mac, the accessibility API can name the exact element under your pointer — its role, label, and frame. So instead of describing "the top card," you point at it.

PinVari does this: you hold a hotkey, circle the element, and say what you want. It resolves the named element with a confidence score, transcribes on-device, and hands Cursor a precise instruction over a local MCP server. Your rules still shape how the code gets written; this just removes the guessing about what to change. If you want the mechanics, here is how agents figure out which UI element you mean.

For a non-coder who cannot phrase the problem in code terms, that shift from describing to pointing is the whole game. PinVari is a one-time purchase rather than a subscription; the details are on the pricing page.

FAQ

Where do I put Cursor rules?

Modern project rules go in a .cursor/rules/ folder as .mdc files, one per concern. The legacy option is a single .cursorrules file at your project root. Personal preferences that apply everywhere go in User Rules inside Cursor's settings.

What is the difference between .cursorrules and .mdc rules?

.cursorrules is one file applied to everything. The newer .mdc project rules are separate files, each with a type that controls when it loads, so you can scope a rule to certain files or have the agent request it only when needed.

Why are my Cursor rules not being followed?

Usually the rule type is wrong. An Always rule always loads, but an Auto Attached rule only fires on matching files, and an Agent Requested rule only loads if its description is clear enough for the agent to choose it. Check the type and glob first.

Do Cursor project rules use up my context window?

Always rules add to every request, so they consume context each turn. Auto Attached and Agent Requested rules only load when relevant, which keeps the cursor context used lower. Keep Always rules short and scope the rest.

Can Cursor rules include MCP setup?

No. Rules shape behavior; MCP servers are configured separately in a cursor mcp json file. Use rules for style and conventions, and MCP for new abilities like database access or screen context.

How do I stop the agent editing the wrong element?

Rules will not fix this, because they do not know your visual intent. Point at the element and speak so the agent gets a resolved, named target instead of guessing from a description or a screenshot.