A Cursor rules template you can copy (.mdc)

Cursor rules are the instructions Cursor's agent reads before it writes code in your project. They live in .cursor/rules/ as .mdc files, and the frontmatter at the top of each file decides when the rule is used. This article gives you a Cursor rules template set you can copy: one always-on rule, one rule scoped to your source files, and one rule you call by name. It also explains the four rule types and the mistakes that make Cursor skip a rule.

Checked on 28 Oct 2026 against Cursor's rules docs (cursor.com/docs/context/rules).

Where the files go

your-project/
  .cursor/
    rules/
      00-core.mdc          # always on
      10-vite-react.mdc    # attached to src/** files
      20-new-feature.mdc   # only when you @-mention it
  AGENTS.md                # optional, read by Cursor too

The extension matters. Cursor's docs say project rules must use .mdc, and a plain .md file in .cursor/rules/ is ignored, because it has no frontmatter. If you would rather write plain markdown, use AGENTS.md instead. You can also type /create-rule in the agent and describe the rule, and Cursor writes the file with the frontmatter for you.

Template 1: an always-on core rule

This is the rule every chat gets. Keep it to behaviour that applies to every task.

---
description: Core working rules for the AI agent in this repository
alwaysApply: true
---
# Working agreement

- Read the files you are about to change, and the files that import them.
  Do not edit from memory.
- For anything bigger than a one-file fix, write a short plan first and
  wait for "go".
- One task, one focused diff. Do not refactor, rename or reformat code the
  task does not need.
- Check the installed version in package.json before using a framework API.
- Do not invent package names, config keys, CLI flags or env variables.
  If you are not sure something exists, look it up and say what you checked.
- You are done only when typecheck, lint and tests pass. Say what you ran.
- Never make a test pass by weakening, skipping or deleting it.
- If the same fix fails twice, stop and summarise what you tried.
- Never print or commit secrets or .env files.

## Project commands
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Test: `npm test`
- Build: `npm run build`

With alwaysApply: true, Cursor includes the rule in every chat and ignores globs and description.

Template 2: a stack rule scoped with globs

Stack rules only matter when the agent touches matching files, so attach them by pattern. This one is for a Vite, React and TypeScript app.

---
description: Rules for a client-side Vite, React and TypeScript app
globs: src/**, index.html, vite.config.*
alwaysApply: false
---
# Vite + React + TypeScript

- Function components and hooks only.
- `useEffect` is for syncing with something outside React. Do not use it
  to derive state from props. Every effect that subscribes, starts a timer
  or fetches must clean up.
- Components never call `fetch` directly. Use the API module in
  `src/lib/api.ts` and validate responses with a schema.
- Show loading, empty and error states for every request.
- Only `VITE_` variables reach the browser, and everything in them is
  public. Never put a secret in a `VITE_` variable.
- Run `npm run build` and `npm run preview` before saying a change works.
  The dev server and the build behave differently.
- TypeScript strict stays on. No `any`, no `@ts-ignore`.

Separate glob patterns with commas. src/** matches everything under src/, and **/*.ts matches .ts files in any folder. With alwaysApply: false and globs set, the rule is attached when a matching file is in context.

Template 3: a rule you call by name

Some rules are workflows you only want sometimes, such as "plan a new feature". Leave out both globs and description, and the rule is only used when you @-mention it in chat, for example @20-new-feature.

---
alwaysApply: false
---
# New feature workflow

1. Restate the feature in two sentences and list open questions.
2. List the files you expect to create or change, in order.
3. Name the test you will write first.
4. Wait for "go" before writing code.
5. After each step, run the checks and report the result.

The four rule types, and the frontmatter behind them

Rule type in Cursor	Frontmatter	When it is used
Always Apply	alwaysApply: true	Every chat session
Apply to Specific Files	alwaysApply: false + globs	When a matching file is in context
Apply Intelligently	alwaysApply: false + description, no globs	When the agent decides the description is relevant
Apply Manually	alwaysApply: false, no globs, no description	Only when you @-mention it

For an "Apply Intelligently" rule, the description is the only thing the agent sees when deciding, so write it like a search query: "Conventions for Supabase migrations and RLS policies", not "DB stuff".

Why Cursor ignores a rule

• Wrong extension. A .md file in .cursor/rules/ is ignored. Rename it to .mdc.
• Globs that never match. *.ts only matches files in the project root. You probably want **/*.ts or src/**.
• Vague lines. "Write clean code" gives the agent nothing to do. "Never call the database from a client component" does.
• Too long. Cursor recommends keeping rules under 500 lines and splitting large rules into smaller ones.
• Expecting file mentions to be inlined. An @file mention in a rule tells the agent where to look. The file's contents are not pasted in. Put anything that must always be in context in the rule body.
• A higher rule wins. Cursor applies Team Rules, then Project Rules, then User Rules. If your team has rules set in the dashboard, check them for conflicts.

If the agent is already looping or rewriting files, the prompts in When your AI agent keeps breaking your code will help.

Cursor rules, AGENTS.md or CLAUDE.md?

Use .cursor/rules/*.mdc when you need scoping by file pattern. Use AGENTS.md for plain shared rules that other tools can read too. If you also use Claude Code, it reads CLAUDE.md. The comparison is in Cursor rules vs CLAUDE.md vs AGENTS.md. If your app is Next.js with Supabase, there is a stack-specific set in Cursor rules for Next.js and Supabase.

FAQ

Where do Cursor rules go?

In .cursor/rules/ at the root of your project, as .mdc files. You can organise them in subfolders. Commit them to git so everyone on the project gets them.

Is .cursorrules still supported?

Cursor's current docs describe project rules in .cursor/rules/ and AGENTS.md. If you still have a single .cursorrules file, move its contents into .mdc rules so you can scope them.

What is the difference between globs and description?

globs attaches the rule when a matching file is in context. description lets the agent decide whether the rule is relevant. If alwaysApply is true, both are ignored.

How long should a Cursor rule be?

Under 500 lines, according to Cursor's docs, and shorter is better. Split by topic: one core rule, one per stack, one per workflow.

Can I use the same rules in Claude Code?

Yes, if you keep them in one source. Put shared rules in AGENTS.md, which Cursor reads, and import it from CLAUDE.md with @AGENTS.md. See the CLAUDE.md example.