What Are .cursorrules Files? (And How to Write One)

Some links may be affiliate links. We may earn a commission at no extra cost to you.

You've seen .cursorrules mentioned in tutorials, Reddit threads, and GitHub repos. But if you search for how to write one today, most of what you'll find is already outdated. Cursor moved on — and your project should too.

This article covers what .cursorrules files are, why Cursor deprecated them, and exactly how to write rules the new way, with three copy-paste starter templates.

What Is a .cursorrules File?

The plain-English version: instructions you give Cursor before it writes any code

A .cursorrules file is a plain text file you place in your project root. Every time Cursor's AI generates a response, it reads this file first. Think of it as a standing brief: "here's what kind of code I write, what conventions I follow, and what I never want you to do."

Without rules, Cursor makes its best guess at your stack, style, and preferences from context alone. With rules, it gets a head start — and it stops repeating mistakes you've already corrected.

Where it lives and how Cursor reads it

The old .cursorrules file sits at the root of your project — the same folder as your package.json or requirements.txt. Cursor automatically picks it up when you open the project. No settings, no imports, no linking required.

The file has no strict format. Plain English works. Most developers write it as a bulleted list of instructions.

Why .cursorrules Was Deprecated (and What Replaced It)

Cursor 0.45 introduced .mdc rules in .cursor/rules/

Cursor deprecated .cursorrules starting in version 0.45. The replacement is a folder-based system: you create a .cursor/rules/ directory in your project root and put one or more .mdc files inside it.

The motivation was flexibility. A single .cursorrules file applied globally to every prompt. The new system lets you create separate rule files for different parts of your project and scope each one to specific file patterns.

Key differences: multiple files, scoping by file pattern, file referencing with @

With .mdc rules you can have frontend.mdc that only applies when Cursor is editing files in src/components/, and api.mdc that only applies to src/api/. You can also reference real files from your codebase using @filename syntax inside a rule — Cursor will pull that file's content into context when the rule applies.

A single .cursorrules file couldn't do any of that.

Does .cursorrules still work in 2026?

As of Cursor 3.x (verified May 2026), .cursorrules is still read as a legacy fallback — it has not been fully removed. That said, the Cursor team has signaled it will eventually be dropped, and Agent mode does not load it at all. New features (scoping, file referencing, multiple files) are only available in the .mdc system. If you're starting a project today, go straight to .cursor/rules/.

How to Write Cursor Rules (the New Way)

Step 1: Create the .cursor/rules/ folder in your project root

mkdir -p .cursor/rules

That's it. Cursor will detect this folder automatically.

Step 2: Create a .mdc file (e.g., general.mdc)

touch .cursor/rules/general.mdc

.mdc files use YAML frontmatter to control scoping and behavior. The frontmatter supports three fields: description (shown in the UI), globs (file patterns that trigger the rule), and alwaysApply (set to true to load the rule on every prompt). If you omit the frontmatter block entirely, the rule will not load reliably — always include at minimum the opening and closing --- markers. To scope a rule to specific files, use the globs field:

---
description: Component style rules
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Always use named exports. Never use default exports in component files.

Step 3: Write your rules in plain English

The body of the file is plain text. You can use markdown formatting — bullet lists, headers, code fences — but you don't have to. Cursor reads the whole file as context.

Keep each rule to one or two sentences. Vague rules ("write clean code") do nothing. Specific rules ("always add a JSDoc comment to exported functions") work.

What to put in your rules: the five most useful rule types

• Stack definition — tell Cursor what you're using: "This project uses React 18, TypeScript 5, and Tailwind CSS."
• Style constraints — naming conventions, formatting preferences, things ESLint doesn't catch
• Anti-patterns to avoid — "never use any in TypeScript", "never install a new package without asking first"
• Output format preferences — "always show me the full file, not a diff", "keep explanations short"
• Workflow conventions — "when I ask you to fix a bug, explain the root cause before showing the fix"

Three Starter Templates You Can Copy Right Now

Template 1: React + TypeScript project

Save as .cursor/rules/general.mdc:

This is a React 18 + TypeScript project using Vite and Tailwind CSS.

- Use named exports only — no default exports
- All components go in src/components/, one file per component
- Use functional components and hooks — no class components
- Add JSDoc comments to all exported functions and components
- Never use `any` — use `unknown` and narrow the type instead
- When suggesting a new npm package, ask before adding it to package.json
- Keep responses concise — show only the changed file unless I ask for more

Template 2: Python/Flask backend project

Save as .cursor/rules/general.mdc:

This is a Python 3.12 Flask API project. The database is PostgreSQL, accessed via SQLAlchemy.

- Follow PEP 8 for all Python code
- All routes go in src/routes/, grouped by resource (e.g., users.py, orders.py)
- Use type hints on all function signatures
- Never use bare `except:` — always catch specific exception types
- Use environment variables for all secrets — never hardcode credentials
- When writing SQL, use SQLAlchemy ORM, not raw queries
- Add a docstring to every function that's more than 3 lines long

Template 3: General vibe coding project (no framework assumption)

Save as .cursor/rules/general.mdc:

This is a personal project. I'm a beginner-to-intermediate developer learning as I go.

- Explain what you're doing before you write code — I want to understand, not just copy-paste
- Keep code simple — prefer readable over clever
- If you see a better way to approach what I'm asking, say so before proceeding
- Never refactor code I didn't ask you to refactor
- When you're unsure what I want, ask one clarifying question instead of guessing
- Prefer built-in language features over external packages when possible

This last template is particularly useful if you're just getting started. Clear instructions about behavior ("ask one clarifying question") make more difference than technical constraints when you're still finding your feet. If you want to go deeper on getting better results from AI editors generally, see our guide on how to write better prompts for AI coding tools.

Tips for Writing Rules That Actually Work

Be specific, not generic

"Write good code" is noise. "Use const for all variables unless reassignment is required" is a rule. The more specific and testable a rule is, the more reliably Cursor follows it.

A useful test: if you read a rule back and can't imagine what failing to follow it would look like, rewrite it.

Reference real files with @ to give rules context

Inside any .mdc file you can write @src/lib/utils.ts and Cursor will pull that file into context whenever the rule applies. This is powerful for style guides — reference your existing utility file and Cursor will match its patterns automatically.

Keep rules short — Cursor reads all of them on every prompt

Every active rule file gets injected into the context window on every prompt. Long rule files eat into the space available for your actual code. Cursor enforces no hard character limit, but community best practice is to keep always-apply rules under 200 words. Aim for under 30 lines per file as a practical target. If you're writing more than that, split into multiple scoped files.

This is where the new system really earns its keep. Instead of one massive .cursorrules blob, you can have lean, focused rule files that only activate when relevant. Your frontend rules don't need to load when you're editing a migration script.

Should You Still Use .cursorrules?

If you're on Cursor 0.45 or later: switch to .mdc

If you've already got a .cursorrules file in a project, migrating takes about 60 seconds:

1. Create the .cursor/rules/ folder
2. Create general.mdc inside it
3. Copy the contents of .cursorrules into general.mdc
4. Delete .cursorrules

Done. You get the same behavior immediately, and you can start splitting and scoping rules whenever it's useful.

If you're on an older version of Cursor that predates 0.45, the old file still works — but upgrading is worth it. The .mdc system is where all new rule features will land.

The bigger picture: rules files are a lightweight spec

Rules files sit at the lightweight end of a spectrum that goes all the way to formal spec-driven development. If you want to understand the deeper practice, our explainer on spec-driven development covers why giving AI structured context before coding leads to better results than correcting it after.

If you use Claude Code instead of Cursor, the equivalent is a CLAUDE.md file in your project root — same idea, different format. Our guide on how to write a CLAUDE.md covers that in detail, and our Cursor vs Claude Code comparison breaks down which tool fits which workflow.

Once your rules are dialed in, the natural next step is adding MCP servers to extend what Cursor can actually do. See how to use MCP servers in Cursor for a beginner-friendly walkthrough.

---

Ready to try Cursor? Download it at cursor.com and start with the free Hobby tier — it includes 2,000 completions and 50 slow premium requests per month, no credit card required. You can set up your first .cursor/rules/ file before you've paid anything.