Cursor AI Rules: Project Rules, .mdc Files and AGENTS.md
Cursor rules are standing instructions that Cursor adds to the start of the Agent's context, so you do not have to repeat them in chat. Project rules are .mdc files in .cursor/rules/ whose frontmatter decides when each one applies, and AGENTS.md is a plain markdown alternative.
Last updated By Gizmolab
Create your first project rule
- Type
/create-rulein Agent chat and describe the rule. Or run New Cursor Rule from the command palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows and Linux), or open Customize, then Rules, then Add Rule. - Write the instructions as short markdown bullets.
- Choose when it applies: Always Apply, Apply Intelligently, Apply to Specific Files or Apply Manually.
- Save it. The rule is stored as an
.mdcfile in.cursor/rules/. Commit it so your team gets it too.
The four kinds of Cursor rules
Project rules
.mdc files in .cursor/rules/. Version-controlled with the repo and scoped to that codebase. The main subject of this page.
User rules
Your own preferences, set in Customize under Rules. They apply in every project and sync with your Cursor account.
Team rules
Set by admins in the Cursor dashboard on Team and Enterprise plans. Admins can enforce them, and they support glob patterns.
AGENTS.md
Plain markdown in the project root or any subfolder, with no frontmatter. A simpler alternative to .cursor/rules.
Rule types and .mdc frontmatter
Each project rule starts with a frontmatter block. Three fields, alwaysApply, globs and description, decide which of the four rule types it is:
| Rule type | Frontmatter | When it is included |
|---|---|---|
| Always Apply | alwaysApply: true | In every chat session. globs and description are ignored. |
| Apply to Specific Files | globs set, alwaysApply: false | When a file matching the pattern is in context. |
| Apply Intelligently | description set, no globs | When the Agent reads the description and decides the rule is relevant. |
| Apply Manually | alwaysApply: false, nothing else | Only when you @-mention it in chat, for example @db-migrations. |
Separate several glob patterns with commas, as in docs/**/*.md, docs/**/*.mdx. Rules can sit in subfolders of .cursor/rules/, but a flat folder is easier to manage.
Cursor rule templates
Six .mdc rules that cover all four ways a rule can apply. Copy one into .cursor/rules/ and change the paths and conventions to match your project.
project-basics.mdc
Always ApplyBaseline habits for every chat. Keep it short, because it is in context all the time.
---
alwaysApply: true
---
- Read the relevant files before proposing changes. Do not guess at code you have not opened.
- Keep changes as small as the task allows. Do not refactor unrelated code.
- Follow the naming, folder structure and patterns already used nearby.
- Never edit generated files in dist/, build/ or .next/.
- If a command, file or behavior cannot be verified, say so instead of guessing.react-components.mdc
Apply to Specific FilesAttached only when a component file is in context.
---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports.
- Put the props interface at the top of the file, named after the component.
- Style with Tailwind classes. Do not add new CSS files.
- Keep components under 200 lines. Extract subcomponents into the same folder.tests.mdc
Apply to Specific FilesSeveral patterns, separated by commas.
---
globs: src/**/*.test.ts, src/**/*.test.tsx
alwaysApply: false
---
- One behavior per test, named for the behavior ("returns 404 when the user is missing").
- Use the factories in @src/test/factories.ts instead of building objects by hand.
- Never weaken or delete an assertion to make a failing test pass.
- Mock the network at the fetch layer, not inside the code under test.api-errors.mdc
Apply IntelligentlyThe Agent pulls this in when the description matches the work.
---
description: Error handling and response conventions for API route handlers
alwaysApply: false
---
- Validate input at the top of each handler with zod before using it.
- Return errors as JSON with a code and a message, never a raw string.
- Never send stack traces or internal error messages to the client.
- Log the full error on the server, including the request id.db-migrations.mdc
Apply ManuallyUsed only when you type @db-migrations in chat.
---
alwaysApply: false
---
- Every migration needs both an up and a down step, so it can be reversed.
- Never change a column type in place. Add a new column, backfill it, then drop the old one in a separate migration.
- Read @db/migrations/template.sql before writing a new migration.solidity.mdc
Apply to Specific FilesFor smart contract repositories. Adjust the folder to where your contracts live.
---
globs: contracts/**/*.sol, src/**/*.sol
alwaysApply: false
---
- Keep the pragma and compiler version set in foundry.toml or hardhat.config. Do not change them.
- Follow checks-effects-interactions: update state before any external call.
- Every state-changing function needs an access check, or a comment saying why it is open.
- Emit an event for each state change that off-chain code relies on.
- Add or update a test for every behavior change and run the suite before finishing.AGENTS.md: plain markdown instructions
AGENTS.md is a markdown file in your project root with no frontmatter, and Cursor picks it up automatically. Use it when you want simple, readable instructions; use .cursor/rules/ when you need control over when a rule applies.
# Project instructions
## Stack
- Next.js app router, TypeScript and Tailwind.
- Package manager: pnpm. Run tests with `pnpm test`.
## Code style
- TypeScript for all new files. No `any` without a comment explaining why.
- Server components by default. Add "use client" only when a component needs state or browser APIs.
## Before you finish
- Run `pnpm lint` and `pnpm test` and fix anything you broke.
- Summarize what changed and anything you could not verify.project/
AGENTS.md # applies everywhere
frontend/
AGENTS.md # adds frontend instructions
backend/
AGENTS.md # adds backend instructionsAn AGENTS.md in a subfolder applies when the Agent works on files in that folder or below it. Its instructions combine with the parent folders', and the more specific file wins. Cursor also reads CLAUDE.md the same way, so the instructions in a project set up for Claude Code reach Cursor's Agent too.
Migrate from .cursorrules
A .cursorrules file in the project root is legacy and will be deprecated. To move it to a project rule:
- Run New Cursor Rule from the command palette.
- Paste the contents of
.cursorrulesinto the new rule. - Set the rule type to Always Apply, which matches the old behavior.
- Delete
.cursorrulesfrom the project root.
While you are at it, split the old file by concern, and move any step-by-step workflows into skills. See Cursor skills.
How to write rules that work
- Keep each rule under 500 lines. Split a large rule into several focused ones.
- One concern per file, with a descriptive name such as react-patterns.mdc.
- Point to files with @path instead of pasting code. The Agent reads the file when it needs it; the contents are not inlined, so anything that must always be in context belongs in the rule body.
- Start small. Add a rule when you see the Agent make the same mistake more than once.
- Skip what the Agent already knows: whole style guides (use a linter), common commands like npm or git, and rare edge cases.
- Commit rules to git so the whole team gets them, and update a rule when the Agent gets something wrong.
Which rules apply, and in what order
Cursor merges every rule that applies. When two conflict, Team Rules come first, then Project Rules, then User Rules.
Rules only shape the Agent. Tab completions and Bugbot reviews do not use them.
A rule that is not being applied usually has the wrong type, a missing description or a glob that does not match. How to reload Cursor skills walks through the checks.
FAQ
What is the difference between alwaysApply, globs and description in a Cursor rule?
Why is my .md file in .cursor/rules ignored?
Do Cursor rules affect Tab completions?
Which rule wins when Team, Project and User rules conflict?
Does Cursor read CLAUDE.md?
Is .cursorrules still supported?
Related guides
- Cursor skills
What a Cursor skill is, where Cursor looks for SKILL.md files, and how the Agent uses them.
- How to create a Cursor skill
Build a skill step by step, from the folder and frontmatter to testing it in Agent chat.
- Cursor skill examples
Complete SKILL.md files for edits, debugging, refactors, reviews and planning.
- How to reload Cursor skills
What to check when a skill or rule does not load, and how to reload Cursor safely.
- Cursor skills for Web3 developers
SKILL.md examples for wallet flows, Solidity reviews, testnet deploys and Anchor programs.
Using a different tool? See Claude Code skills, OpenClaw skills or the AI skills hub.
Sources
This guide was checked against the official documentation on 5 November 2026. Cursor changes quickly, so when something here differs from the docs, the docs win.