Cursor AI rules

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

  1. Type /create-rule in 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.
  2. Write the instructions as short markdown bullets.
  3. Choose when it applies: Always Apply, Apply Intelligently, Apply to Specific Files or Apply Manually.
  4. Save it. The rule is stored as an .mdc file 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:

Cursor rule types and the frontmatter behind them
Rule typeFrontmatterWhen it is included
Always ApplyalwaysApply: trueIn every chat session. globs and description are ignored.
Apply to Specific Filesglobs set, alwaysApply: falseWhen a file matching the pattern is in context.
Apply Intelligentlydescription set, no globsWhen the Agent reads the description and decides the rule is relevant.
Apply ManuallyalwaysApply: false, nothing elseOnly 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 Apply

Baseline habits for every chat. Keep it short, because it is in context all the time.

.cursor/rules/project-basics.mdc
---
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 Files

Attached only when a component file is in context.

.cursor/rules/react-components.mdc
---
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 Files

Several patterns, separated by commas.

.cursor/rules/tests.mdc
---
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 Intelligently

The Agent pulls this in when the description matches the work.

.cursor/rules/api-errors.mdc
---
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 Manually

Used only when you type @db-migrations in chat.

.cursor/rules/db-migrations.mdc
---
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 Files

For smart contract repositories. Adjust the folder to where your contracts live.

.cursor/rules/solidity.mdc
---
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.

AGENTS.md
# 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.
Nested AGENTS.md files
project/
  AGENTS.md          # applies everywhere
  frontend/
    AGENTS.md        # adds frontend instructions
  backend/
    AGENTS.md        # adds backend instructions

An 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:

  1. Run New Cursor Rule from the command palette.
  2. Paste the contents of .cursorrules into the new rule.
  3. Set the rule type to Always Apply, which matches the old behavior.
  4. Delete .cursorrules from 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?

They decide when a rule is included. alwaysApply: true includes the rule in every chat. With alwaysApply: false, globs attaches the rule when a matching file is in context, a description lets the Agent pull the rule in when it judges it relevant, and with neither the rule is only used when you @-mention it.

Why is my .md file in .cursor/rules ignored?

Project rules must use the .mdc extension. A plain .md file in .cursor/rules has no frontmatter for description, globs and alwaysApply, so the rules system skips it. Rename it to .mdc and add frontmatter, or move plain markdown instructions into AGENTS.md.

Do Cursor rules affect Tab completions?

No. Rules only apply to the Agent (chat). They do not change Tab completions or Bugbot pull request reviews.

Which rule wins when Team, Project and User rules conflict?

Cursor merges every rule that applies. When guidance conflicts, earlier sources win in this order: Team Rules, then Project Rules, then User Rules.

Does Cursor read CLAUDE.md?

Yes. Cursor reads a CLAUDE.md file the same way it reads AGENTS.md, so a project set up for Claude Code also works in Cursor. CLAUDE.md is applied to every conversation whatever its frontmatter says, so use project rules in .cursor/rules/ when you need a rule to apply conditionally.

Is .cursorrules still supported?

A .cursorrules file in the project root is legacy, and Cursor's help center says it will be deprecated. Move its contents into a project rule set to Always Apply, which matches the old behavior, then delete the file.

Related guides

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.