What are Cursor rules? How to write them

Create a rule

The fastest route is /create-rule in Agent chat. Say what the rule should do, and Agent writes the file with the right frontmatter and saves it in .cursor/rules. The Add Rule button under Customize, then Rules, creates the same file. To set each field yourself, use the command palette:

1. Open the command palette with Ctrl+Shift+P, or Cmd+Shift+P on a Mac, and run "New Cursor Rule".
2. Name it for one concern, such as react-patterns or api-validation.
3. Write the instructions as plain markdown, a few short lines to start.
4. Choose a type from the dropdown. For Apply to Specific Files, add the pattern, such as *.tsx. For Apply Intelligently, write the description.
5. Save. The file lands in .cursor/rules/, ready to commit.

Cursor's help page advises a flat .cursor/rules folder as simpler to manage, though its reference groups rules in subfolders, and both work. The screenshot, X's own embed of a reply and the post above it, dates from April 2025, when Cursor 0.49 called its rule command "/Generate Cursor Rules". The docs now describe /create-rule.

The four ways a project rule applies

Whatever you pick in the dropdown is saved as frontmatter, a short block at the top of the .mdc file with three fields: alwaysApply, description and globs.

An applied rule's text goes in at the start of the model's context, and Cursor's ring chart of a chat's tokens draws Rules as one slice beside skills and MCP. An always-on rule takes that slice in every conversation, and the cost adds up. Save alwaysApply: true for the few lines every task needs, such as the test command, and let a react-patterns rule wait behind a *.tsx glob.

Always Apply loads the rule into every chat, and Cursor ignores any globs or description beside it. A file rule waits until a file matching its globs pattern is in context, and an Apply Intelligently rule until Agent judges its description relevant. A manual rule does nothing until you type its name after an @.

What to put in a rule, with a sample to copy

Cursor's agent best-practices post says to start with no rules and add one only when Agent makes the same mistake more than once. Say it keeps throwing raw strings from your API handlers. The sample below asks for { code, message } error objects instead.

Save it as .cursor/rules/api-handlers.mdc, and set alwaysApply: true if you want it on in every chat.

Cursor describes rules as persistent context at the prompt level, not checks that run in your code, so the mistake can still come back. Then check that the rule loads and rewrite the line Agent ignores, or tag @cursor on a GitHub issue or pull request and Agent edits it for you. For anything security-related, Cursor's docs warn against making AI guidance your only control.

---
globs: src/api/**/*.ts
alwaysApply: false
---

- Validate every request body with the zod schema in `src/api/schemas/` before it reaches a service.
- Return errors as `{ code, message }` objects from `src/lib/errors.ts`. Never throw a raw string.
- Put a test beside each handler. Copy the layout of @src/api/handlers/users.test.ts.
- Never edit `src/generated/`. Change the schema and run `npm run generate`.

• Cursor's own list of what to leave out starts with whole style guides. A linter does that job, and Agent already knows common conventions.
• No list of every command. Agent knows npm, git and pytest, so name only the ones that are yours.
• Skip edge cases that rarely come up.
• Don't paste code that already sits in your repository. Point to a canonical example instead.

When a rule doesn't fire

Look at the file name before anything else. Cursor ignores plain .md files in .cursor/rules because they have no frontmatter, so a rule saved as .md never fires until you rename it to .mdc. If the name is right, look at the type you picked:

• Apply Intelligently with an empty description. Agent judges relevance from that one line, so write when the rule matters, not what it contains.
• Apply to Specific Files with a pattern that misses. Test it against a real path Agent is working with. *.ts skips every subfolder.
• Apply Manually. Nothing happens until you type @ and the rule's name in chat.

Cursor rules next to AGENTS.md, CLAUDE.md and skills

AGENTS.md is the plain version of a rule: markdown with no frontmatter and no types. Cursor reads it from the project root and from subfolders, where a nested file's instructions combine with its parents' and the more specific one wins.

Cursor reads CLAUDE.md, Claude Code's file, the same way, except that it applies to every conversation whatever any alwaysApply setting says.

From version 2.1.277, Claude Code reads AGENTS.md when no CLAUDE.md sits in or above the working folder, and a CLAUDE.md can pull the file in with an @AGENTS.md import, so one AGENTS.md serves both tools. Only what needs a glob, a description or a manual switch has to live in .cursor/rules.

Skills stay out of context until their description fits the task or you type /skill-name. For how-to steps and context that changes with the task, Cursor's 2.4 changelog prefers them to always-on rules. Only an Apply Intelligently rule converts with /migrate-to-skills. Skill folders you already keep for Claude Code or Codex need no copy, because Cursor reads those folders as well.

Codex reads CLAUDE.md only if you list that name in project_doc_fallback_filenames. The screenshot shows Cursor's post without its video.

Project, user and team rules: who gets which

An admin's team rule, a project rule from the repository and your own user rule can all apply to one chat. When they disagree, Cursor merges what applies and lets the earlier one win: team first, then project, then user.

Two rules with the same file name in different folders don't collide. Cursor tells rules apart by their full path, so both apply whenever their conditions match.

The old .cursorrules file in a project's root is legacy, and Cursor's help page says it will be deprecated. To migrate, create a new rule, paste the old file into it, set the type to Always Apply, which matches the old behavior, and delete .cursorrules.

Share rules with a team or another project

Rules from another GitHub repository don't import by themselves. Cursor's route is a plugin: the .mdc files go in the plugin's rules/ folder, and the plugin is published through a marketplace. In Customize, From GitHub Repository then imports it, provided the repository has a .cursor-plugin/marketplace.json.

Other people publish their rules in public repositories. On 3 November, GitHub's repository search for "cursorrules", sorted by stars, put PatrickJS/awesome-cursorrules first and grapeot/devin.cursorrules second.

We read every page cited here on 3 November and tried no rule hands-on, the sample included.

Reference: frontmatter for each rule type, and glob patterns

globs takes patterns separated by commas, and two stars cross folders:

*.ts                           .ts files in the root only
**/*.ts                        .ts files in any folder
src/**                         everything under src
docs/**/*.md, docs/**/*.mdx    two extensions, comma-separated

Frequently asked questions

Sources

1. Cursor docs: Rules (read November 3, 2026)https://cursor.com/docs/rules
2. Cursor Help: Rules (read November 3, 2026)https://cursor.com/help/customization/rules
3. Cursor docs: Agent Skills (read November 3, 2026)https://cursor.com/docs/skills
4. Cursor Help: Skills (read November 3, 2026)https://cursor.com/help/customization/skills
5. Cursor docs: Using Agent in CLI (read November 3, 2026)https://cursor.com/docs/cli/using
6. Cursor docs: Plugins (read November 3, 2026)https://cursor.com/docs/plugins
7. Cursor docs: Cloud Agent best practices (read November 3, 2026)https://cursor.com/docs/cloud-agent/best-practices
8. Cursor docs: Prompting Agent (read November 3, 2026)https://cursor.com/docs/agent/prompting
9. Cursor docs: Bugbot (read November 3, 2026)https://cursor.com/docs/bugbot
10. Cursor blog: Best practices for coding with agents (read November 3, 2026)https://cursor.com/blog/agent-best-practices
11. Cursor Learn: Customizing agents (read November 3, 2026)https://cursor.com/learn/customizing-agents
12. Cursor changelog: 2.4, Subagents, Skills, and Image Generation (read November 3, 2026)https://cursor.com/changelog/2-4
13. Claude Code docs: How Claude remembers your project (read November 3, 2026)https://code.claude.com/docs/en/memory
14. Cursor changelog: 0.45.x, .cursor/rules, Better Codebase Understanding, New Tab Model (read November 3, 2026)https://cursor.com/changelog/0-45-x
15. Cursor changelog: 0.49, Rules generation, improved agent terminal and MCP images (read November 3, 2026)https://cursor.com/changelog/0-49
16. Cursor changelog: 1.7, Browser Controls, Plan Mode, and Hooks (read November 3, 2026)https://cursor.com/changelog/1-7
17. Cursor changelog: 2.5, Plugins, Sandbox Access Controls, and Async Subagents (read November 3, 2026)https://cursor.com/changelog/2-5
18. Claude Code docs: Extend Claude with skills (read November 3, 2026)https://code.claude.com/docs/en/skills
19. ChatGPT Learn: Custom instructions with AGENTS.md (read November 3, 2026)https://learn.chatgpt.com/docs/agent-configuration/agents-md
20. ChatGPT Learn: Build skills (read November 3, 2026)https://learn.chatgpt.com/docs/build-skills
21. GitHub: repository search for cursorrules, sorted by stars (read November 3, 2026)https://github.com/search?q=cursorrules&type=repositories&s=stars&o=desc
22. GitHub: PatrickJS/awesome-cursorrules (read November 3, 2026)https://github.com/PatrickJS/awesome-cursorrules
23. GitHub: grapeot/devin.cursorrules (read November 3, 2026)https://github.com/grapeot/devin.cursorrules
24. eric zakariasson on X: generate rules from a conversation (read November 3, 2026)https://x.com/ericzakariasson/status/1913291812762210454
25. Cursor on X: Agent Skills are now available in Cursor (read November 3, 2026)https://x.com/cursor_ai/status/2014753596223770841