Cursor’s AI agent is smart, but it forgets everything between chats. It does not know that your team uses named exports, that dist/ is generated, or that every migration needs a rollback. Cursor rules fix that.
Rules are small instruction files that Cursor adds to the start of the model’s context, so the agent follows your conventions every time without you repeating them.
This guide explains every kind of Cursor rule in one place: Project Rules in .cursor/rules, the four rule types and their frontmatter, AGENTS.md, User Rules and Team Rules, how to create rules fast with /create-rule, copy-ready examples, best practices, and how to fix rules that do not apply. Everything is checked against Cursor’s official rules documentation in November 2026.
- Where: project rules live in
.cursor/rules/and must use the.mdcextension. Plain.mdfiles there are ignored. - Frontmatter: three fields,
description,globsandalwaysApply, decide when a rule loads. - Four types: Always Apply, Apply to Specific Files (globs), Apply Intelligently (description) and Apply Manually (
@rule-name). - Simple option: an
AGENTS.mdfile in the repo root (and subfolders) works with no frontmatter. - Fastest way to make one: type
/create-rulein Agent and describe what you want. - Priority: Team Rules, then Project Rules, then User Rules.
- Keep each rule under 500 lines; rules do not affect Cursor Tab autocomplete.
What Are Cursor Rules?
Large language models do not keep memory between completions. Each new chat starts from zero. Cursor rules give the agent persistent, reusable instructions. When a rule applies, Cursor places its text at the start of the model context, before your message.
That makes rules ideal for:
- Coding conventions the agent keeps getting wrong (exports, naming, error handling).
- Project facts it cannot guess (which folders are generated, which service template to copy).
- Workflows (how to add a setting, how to write a migration, how to run checks).
- Guard rails (never edit build output, always add a licence header).
Rules apply to Cursor’s Agent (chat). They do not change Cursor Tab autocomplete or other AI features.
The Four Places Rules Come From
| Source | Where it lives | Scope | Shared with team? |
|---|---|---|---|
| Project Rules | .cursor/rules/*.mdc in your repo |
That project | Yes, via git |
| AGENTS.md | AGENTS.md in repo root and subfolders |
That project or folder | Yes, via git |
| User Rules | Cursor: Customize > Rules | All your projects | No, personal |
| Team Rules | Cursor dashboard (Team and Enterprise plans) | Everyone on the team | Yes, managed by admins |
When several apply, Cursor merges them. If they conflict, the order of precedence is Team Rules > Project Rules > User Rules.
Project Rule Types and Frontmatter
Each .mdc file starts with a small frontmatter block, followed by the rule text in Markdown. Three fields control when it loads:
---
description: RPC service conventions for src/services
globs: src/services/**/*.ts
alwaysApply: false
---
- Use the template in @service-template.ts for new services.
- Validate every input with zod before calling the database.
In the Cursor editor you do not have to type these by hand. The Rule Type dropdown sets them for you. Here is how the four types map to the fields:
| Rule type (UI) | Frontmatter | When it is used | Use it for |
|---|---|---|---|
| Always Apply | alwaysApply: true |
Every chat. globs and description are ignored |
Short, universal rules |
| Apply to Specific Files | alwaysApply: false + globs |
When a matching file is in context | Language or folder conventions |
| Apply Intelligently | alwaysApply: false + description, no globs |
The agent reads the description and decides | Topic guides the agent pulls in when relevant |
| Apply Manually | alwaysApply: false, no description, no globs |
Only when you @-mention it, for example @db-migrations |
Rare workflows, checklists |
Glob patterns
**/*.tsmatches every TypeScript file in any folder.src/**/*.tsxmatches TSX files undersrc.docs/**/*.md, docs/**/*.mdxuses commas to list several patterns.
Organising rules
You can use subfolders inside .cursor/rules, for example .cursor/rules/frontend/components.mdc. One topic per file keeps rules easy to find and easy to review in pull requests.
Referencing files
You can mention a file in a rule, such as @service-template.ts. Cursor does not paste that file into the prompt automatically. The agent reads it with its tools when needed. If something must always be in context, write it in the rule itself.
How to Create a Cursor Rule
Option 1: let the agent write it
- Open Agent (chat) in your project.
- Type
/create-ruleand describe the rule, for example: “React components must use named exports and stay under 200 lines. Apply to src/components.” - Review the file. Cursor generates the frontmatter and saves it in
.cursor/rules. - Commit it so your team gets the same rule.
Option 2: use Customize
- Open Customize in the sidebar.
- Go to Rules and click Add Rule.
- Name it, pick the Rule Type, add globs or a description if needed, and write the rule.
Option 3: create the file yourself
- Create the folder:
mkdir -p .cursor/rules - Add a file ending in
.mdc, for example.cursor/rules/react-components.mdc. - Paste the frontmatter and rule text (see the examples below), save, and start a new chat to test.
You can also simply ask the agent in chat to “turn what we just agreed into a rule”. It works well after you have corrected it a few times.
Copy-Ready Rule Examples
1. Always apply: guard rails
---
alwaysApply: true
---
- Never edit files in dist/ or build/. They are generated.
- Add the standard copyright header to every new source file.
- Ask before adding a new dependency.
2. Specific files: React components
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports.
- Keep components under 200 lines; split larger ones.
- Style with Tailwind classes; no inline style objects.
- Put prop types in the same file as the component.
3. Apply intelligently: API services
---
description: Conventions for writing RPC services in src/services
alwaysApply: false
---
- Start from @service-template.ts.
- Validate inputs with zod schemas from src/schemas.
- Return typed errors; never throw raw strings.
4. Manual: database migrations
---
alwaysApply: false
---
Every migration must export both up() and down().
down() must fully reverse up(). Test both locally before committing.
Save that last one as db-migrations.mdc and call it with @db-migrations only when you are writing a migration.
5. Python project
---
globs: **/*.py
alwaysApply: false
---
- Target Python 3.12. Use type hints on all public functions.
- Use pathlib, not os.path.
- Tests go in tests/ and use pytest fixtures, not unittest classes.
AGENTS.md: The Simple Alternative
If you do not need rule types or globs, put plain Markdown instructions in an AGENTS.md file. Cursor’s docs describe it as a simple alternative to .cursor/rules.
- Place it in the project root for project-wide guidance.
- Add more
AGENTS.mdfiles in subfolders, such asfrontend/AGENTS.md. They apply automatically when the agent works in that folder or below. - Nested files combine with their parents, and the more specific (deeper) instructions win on conflicts.
A big plus: AGENTS.md is also read by other coding agents, so one file can guide both Cursor and OpenAI Codex (see our Codex CLI guide).
Terminal tools that do not read it automatically, such as Aider, can load it as a read-only file; our Aider guide shows how. Claude users get a similar system through Skills; see our Claude Skills guide.
| Choose | When |
|---|---|
AGENTS.md |
Small project, a handful of rules, several AI tools on the same repo |
.cursor/rules/*.mdc |
Many rules, file-type specific rules, rules you only want sometimes |
| Both | Shared basics in AGENTS.md, Cursor-specific detail in .mdc files |
User Rules and Team Rules
User Rules
User Rules are your personal preferences across every project, such as “keep answers short” or “explain changes before making them”. Set them in Customize > Rules. They are not stored in the repo, so teammates do not see them.
Team Rules
On Team and Enterprise plans, admins create rules in the Cursor dashboard:
- Enable this rule immediately: if unticked, the rule is saved as a draft.
- Enforce this rule: enforced rules cannot be switched off by members in Customize. Non-enforced rules can be toggled off.
- Team Rules are free text and can use glob patterns. Without a glob they apply to every conversation.
Cursor’s docs add a sensible warning: AI guidance should not be your only security control. Keep real checks (CI, code review, secret scanning) in place.
Sharing rules across repos
Rules are not imported from another repo on their own. To share a set, package them in a Cursor plugin with a .cursor-plugin/marketplace.json file, then import it through Customize > From GitHub Repository, or add a team marketplace.
Best Practices
- Start small. Add a rule only when the agent repeats the same mistake.
- Keep each rule under 500 lines. Split big ones into focused, composable files.
- Give concrete examples or point to a real file to copy, rather than abstract advice.
- Reference, do not copy. Link to
@template.tsinstead of pasting it, so the rule never goes stale. - Skip what tools already enforce. Do not paste a whole style guide; use a linter or formatter.
- Do not document obvious commands or rare edge cases. Every always-on line costs context.
- Prefer globs or descriptions over Always Apply so only relevant rules load.
- Check rules into git and review them like code. On GitHub you can tag
@cursoron an issue or PR to have the agent update a rule.
Running Cursor with a local model? Smaller models follow fewer instructions reliably, so keep rules extra short. Our Cursor local models guide covers that setup.
Migrating From .cursorrules
Older projects often have a single .cursorrules file in the root. That is the legacy format: Cursor’s current rules documentation only covers .cursor/rules, AGENTS.md, User Rules and Team Rules. To move over:
- Copy the contents of
.cursorrulesinto a newAGENTS.md(quickest) or split it into topic files in.cursor/rules/. - For each
.mdcfile, choose a Rule Type: universal lines become Always Apply, language-specific lines get globs. - Test in a fresh chat, then delete
.cursorrulesso there is one source of truth.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| Rule never applies | File ends in .md, not .mdc |
Rename to .mdc and add frontmatter |
| Apply Intelligently rule ignored | Missing or vague description |
Write a clear one-line description of when it is relevant |
| File-specific rule ignored | Glob does not match the path, or no matching file is in context | Check the pattern (for example src/**/*.tsx) and add a matching file to the chat |
| Manual rule not used | It only loads when mentioned | Type @rule-name in your message |
| Agent ignores part of a long rule | Too long or too many always-on rules | Split it, cut filler, switch some to globs |
| Rule conflicts with a teammate’s setting | Precedence: Team > Project > User | Move the guidance to the right level or remove the conflict |
| Tab autocomplete ignores rules | Rules only affect Agent | Expected behaviour |
| Referenced file content not used | @-mentioned files are read on demand, not inlined | Put must-know facts in the rule text |
FAQ
Where do I put Cursor rules?
In a .cursor/rules folder at the root of your project, as .mdc files. Subfolders are allowed.
What is the difference between .mdc and .md?
Cursor requires .mdc for project rules because the file carries frontmatter (description, globs, alwaysApply). A plain .md file in .cursor/rules is ignored.
Does Cursor read AGENTS.md?
Yes. Cursor supports AGENTS.md in the project root and in subfolders, with deeper files taking precedence.
Is .cursorrules still supported?
It is the legacy format and is not covered in Cursor’s current rules docs. Move its contents into AGENTS.md or .cursor/rules to be safe.
How long should a Cursor rule be?
Cursor recommends under 500 lines per rule. In practice, a focused rule of 5 to 30 lines works best.
Do rules cost extra tokens?
Yes. Applied rules are added to the context of each request, so long always-on rules use more of your usage and leave less room for code. Use globs and descriptions to load rules only when needed.
Can I share rules across all my repos?
For personal preferences, use User Rules. For teams, use Team Rules or package rules as a plugin in a marketplace.



