In short
Cursor rules are instructions saved in your project that Cursor adds to its requests, so Agent and chat follow your conventions without being told. Modern Cursor rules are .mdc files in .cursor/rules, each with a description, the files it applies to and the rules themselves. Below: the format, a short example, and three ready-made rules: design, Next.js with Tailwind, and component reuse.
Updated
Where the file goes
Put rule files in .cursor/rules/ in your project, one topic per file, with the .mdc extension. The older single .cursorrules file in the project root still works, but split rules are easier to manage.
Cursor rules template: structure
description
What the rule is for. Cursor uses it to decide when a rule is relevant.
globs
File patterns the rule applies to, such as all .tsx files. The rule is attached when those files are involved.
alwaysApply
Set to true for rules that apply to every request; keep most rules false and scoped with globs.
Rules
Short, specific instructions. You can reference files with @ inside a rule.
A short example
--- description: Design rules for all UI work. globs: ["**/*.tsx", "**/*.css"] alwaysApply: false --- - Follow @design/template.html for every component. - Use only the colour tokens in tailwind.config. - Reuse components in components/ before creating new ones.
Writing Cursor rules, step by step
List the things you keep correcting in Cursor: wrong components, raw colours, the wrong data fetching pattern, missing loading states. Each recurring correction is a rule.
Create .cursor/rules/ and one .mdc file per topic: design.mdc, framework.mdc, testing.mdc. Give each a description that says what it is for and globs for the files it applies to, so it attaches only where it matters.
Write the rules as short commands. Reference real files with @, like @design/template.html, so Cursor reads your actual design instead of a summary of it.
Test a rule by asking Agent for a change in the matching files and checking that it follows the rule. If it does not, the rule is probably too long or too vague.
Review your rules every few weeks. Delete rules for patterns you no longer use, merge rules that overlap, and move long reference material into separate files that a rule points to with @. A small, current set of rules beats a large, stale one.
Ready-made Cursor rules files
Complete files you can copy into your project and fill in. Each one works with the BrowserMoon design templates, so what the tool builds also looks professional.
Cursor design rules template
A Cursor rules file that applies to every chat and Agent run on UI files, so Cursor follows your template, colours and spacing instead of inventing styles.
.cursor/rules/design.mdc--- description: Design rules for all UI work. Apply when creating or editing pages, components or styles. globs: ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.html", "**/*.vue", "**/*.svelte"] alwaysApply: false --- # Design rules
Next.js and Tailwind rules
A Cursor rule for Next.js App Router projects with Tailwind CSS: server components, data fetching, file structure and Tailwind conventions.
.cursor/rules/nextjs-tailwind.mdc--- description: Conventions for this Next.js (App Router) and Tailwind CSS project. Apply to all app and component files. globs: ["app/**/*.tsx", "app/**/*.ts", "components/**/*.tsx", "lib/**/*.ts"] alwaysApply: false --- # Next.js and Tailwind conventions
Component reuse rules
A Cursor rule that stops Cursor creating duplicate buttons, cards and inputs: check the components folder first, extend with variants.
.cursor/rules/components.mdc--- description: Reuse existing UI components. Apply whenever creating or editing UI. globs: ["**/*.tsx", "**/*.jsx"] alwaysApply: false --- # Reuse components
Using Cursor rules with a design template
A design rule that references @design/template.html turns your template into the default for every UI request in Cursor, in chat and in Agent.
Combine it with the component reuse rule so Cursor builds new pages from the same buttons, cards and inputs every time.
Analytics dashboard · Dark gradient hero · Pricing section · Account settings · Login page · Onboarding steps
Best practices
- ·One topic per rule file: design, framework, testing. Small rules are applied more reliably.
- ·Scope rules with globs so they only load for the files they are about.
- ·Write rules as commands and keep them short.
- ·Reference your design template with @ inside the design rule, so Cursor reads the real file.
Common mistakes and how to fix them
One huge .cursorrules file
Split into small .mdc files by topic, scoped with globs.
alwaysApply on everything
Keep most rules scoped; use alwaysApply only for truly universal rules.
Describing the design instead of linking it
Reference the template file with @ so Cursor reads the real thing.
Outdated rules
Delete rules for patterns you no longer use; stale rules confuse Agent.
Cursor rules vs CLAUDE.md vs AGENTS.md
These files tell Cursor how to work. A design template tells it what to build. Use both.
Cursor templatesFrequently asked questions
What are Cursor rules?
Saved instructions in your project that Cursor includes with relevant requests, so it follows your conventions automatically.
Where do Cursor rules go?
In .cursor/rules/ as .mdc files. The older .cursorrules file in the project root is still read for compatibility.
What is the .mdc format?
Markdown with a small header that sets the description, the file globs and whether the rule always applies.
How many Cursor rules should I have?
A few small, focused files, such as design, framework and testing, work better than one long file.
Should Cursor rules be committed to git?
Yes. Project rules in .cursor/rules belong in the repo so the whole team, and every Agent run, follows the same conventions and design.
Do Cursor rules apply to Tab completions?
Rules are aimed at chat and Agent requests. Inline completions follow your code more than your rules, which is another reason to keep components and tokens consistent in the code itself.
Do Cursor rules work in Agent mode?
Yes. Matching rules are included in Agent and chat requests.
Can I use the same rules in Claude Code?
The content transfers well. Put it in CLAUDE.md for Claude Code and in .cursor/rules for Cursor.
Are there user-level Cursor rules?
Yes, Cursor also has rules in your settings that apply to all projects. Project rules are better for anything team-specific.
How long should a Cursor rule be?
Short. A focused rule of 20 to 60 lines is followed more reliably than a long one.
Cursor templates by category
Related