Cursor project rules are .mdc files in .cursor/rules/. Each one starts with frontmatter that decides when it loads: in every chat, when a file matches a glob, when the agent thinks it's relevant, or when you @-mention it.
Cursor also reads AGENTS.md, at the root and in any subfolder. So a folder's rules can live in that folder's AGENTS.md, where Codex, Copilot and the other agents read them too. Below: the .mdc format, Next.js globs, a template, when to pick .mdc over AGENTS.md, real rules from a generated repo, and Cursor's hooks, subagents and MCP.
Where Cursor rules live
| Type | Where | Applies to |
|---|---|---|
| Project rules | .cursor/rules/*.mdc, committed to git | This repo |
| User rules | Cursor settings | Every project you open |
| Team rules | The Cursor dashboard | Every repo on the team |
| AGENTS.md | The repo root and any subfolder | This repo, as plain markdown |
| CLAUDE.md | The repo root | This repo, always on |
When more than one applies, Cursor's order is Team Rules, then Project Rules, then User Rules.
Things worth knowing before you write one:
- Folders work.
.cursor/rules/frontend/components.mdcis fine. - Plain
.mdis ignored. A.mdfile in.cursor/rules/has no frontmatter, so the rules system skips it. - Rules are for Agent (Chat). User Rules don't apply to Inline Edit (Cmd/Ctrl+K). No rule affects Cursor Tab.
.cursorrulesis legacy. Cursor says the root.cursorrulesfile "is legacy and will be deprecated." Move it into.cursor/rules/.
The .mdc file format
An .mdc file is markdown with a frontmatter block on top. Three fields:
| Field | Value | What it does |
|---|---|---|
description | A sentence | Tells the agent what the rule is for. Cursor uses it to decide relevance |
globs | File patterns, comma-separated | Attaches the rule when a file you're working on matches |
alwaysApply | true or false | true puts the rule in every chat |
Then the body: plain markdown. Bullets, headings, code samples. A minimal file-scoped rule for Next.js route handlers:
---
description: Route handler rules for the App Router
globs: src/app/api/**/route.ts
alwaysApply: false
---
- Parse every body, query and route param with Zod before you use it.
- Check the session inside the handler. The proxy is not the boundary.
- Return typed JSON with a real status code. Never return a stack trace.
The four rule types
Which type a rule is depends on its frontmatter.
| Type | Frontmatter | Loads | Next.js use |
|---|---|---|---|
| Always Apply | alwaysApply: true | Every chat session | Code style, git, security |
| Apply to Specific Files | alwaysApply: false plus globs | When a file matches | Webhooks, schema, components |
| Apply Intelligently | alwaysApply: false plus description | When the agent decides it's relevant | Procedures: add a page, run a migration |
| Apply Manually | alwaysApply: false, no description, no globs | When you @-mention it, like @my-rule | One-off checklists |
Default to file-scoped. An Always Apply rule rides along in every chat, even one about a CSS tweak. Save it for the few rules that really apply everywhere.
Cursor rules globs for Next.js
Globs go on one globs: line, separated by commas. ** matches any depth. Patterns that fit a Next.js App Router repo:
| Glob | Matches |
|---|---|
src/app/**/page.tsx | Every page |
src/app/**/route.ts | Every route handler |
src/app/api/webhooks/stripe/** | The Stripe webhook route |
src/components/** | Every component |
src/db/** | Schema and queries |
tests/**,src/**/*.test.ts,src/**/*.test.tsx | Unit and end-to-end tests |
next.config.ts,src/proxy.ts | Build config and the request proxy |
One Next.js 16 detail. The middleware file convention is deprecated and renamed to proxy. A rule scoped to middleware.ts in a Next.js 16 repo guards a file that shouldn't exist.
Here is every rule in the generated example repo and the files it applies to. In that repo, most of them reach Cursor through nested AGENTS.md files, not .mdc. More on why below.
admin-access:src/app/(admin)/**,src/components/admin/**,src/lib/admin/actions.ts,src/app/api/admin/**admin-mutations:src/lib/admin/**,src/components/admin/**,scripts/admin/**app-shell:src/app/(app)/**,src/components/app/**,src/components/ui/sidebar.tsx,src/lib/app-shell.ts,src/lib/nav.tsauth-server-boundary:src/lib/auth/**,src/app/api/auth/**,src/app/(better-auth)/**,src/components/auth/**billing-core:src/lib/pricing.ts,src/lib/billing/**,src/app/pricing/**,src/app/(app)/billing/**,src/components/billing/**blog-content:content/**blog-rendering:src/app/blog/**,src/app/sitemap.ts,src/lib/blog/**,src/components/blog/**,src/mdx-components.tsxcode-style: every filedeployment:next.config.ts,vercel.json,package.json,src/proxy.ts,src/app/**/route.ts,.env.exampledrizzle-migrations:src/db/**,drizzle/**,drizzle.config.tsdrizzle-schema:src/db/**email-sending-discipline:src/lib/email/**,src/app/api/webhooks/resend/**,src/lib/auth/**,src/lib/billing/**event-naming:src/lib/analytics/**,src/app/**,src/components/**git: every fileidentify-timing:src/lib/analytics/**,src/app/**,src/components/**landing-and-legal:src/lib/site.ts,src/lib/llms.ts,src/app/page.tsx,src/app/(legal)/**,src/app/llms.txt/**,src/components/marketing/**,src/components/site/**neon-connections:src/db/**,src/app/api/**neon-migrations:src/db/**roles-are-server-side:src/app/**,src/components/**,src/lib/auth/**security: every filesentry-capture:src/**,sentry.server.config.ts,sentry.edge.config.tssentry-no-pii: every fileserver-truth-and-pii:src/lib/analytics/**,src/app/**,src/components/**stripe-billing-store:src/lib/billing/**,scripts/billing/**stripe-pricing-source-of-truth:src/lib/pricing.ts,src/lib/billing/**,scripts/billing/**stripe-server-boundary:src/lib/billing/**,src/app/api/webhooks/stripe/**,src/app/**stripe-webhook-integrity:src/app/api/webhooks/stripe/**,src/lib/billing/provider.ts,src/lib/billing/webhook.tstesting:tests/**,src/**/*.test.ts,src/**/*.test.tsxtokens-only:src/components/**,src/app/**ui-kit:src/components/**,src/app/**
Notice the spread. Auth rules cover src/lib/auth/**. Billing rules cover src/lib/billing/**. The design rule covers components and pages. Each rule loads for the folders it governs, not for the whole repo.
Cursor rules template for Next.js (copy this)
Two starter rules. We wrote them as skeletons for this page, not from a real project. Swap in your own paths and commands.
.cursor/rules/nextjs.mdc, on in every chat:
---
description: Next.js App Router conventions for this repo
alwaysApply: true
---
- App Router only. Do not add a `pages/` directory.
- Server Components by default. Add "use client" only for state, effects, refs or browser APIs.
- Fetch data in Server Components or route handlers, not in a client effect.
- Import with `@/`. Never `../../../`.
- Before you finish: `pnpm typecheck` and `pnpm lint` pass.
.cursor/rules/components.mdc, scoped to UI files:
---
description: Component rules
globs: src/components/**,src/app/**/*.tsx
alwaysApply: false
---
- Build from the components in `src/components/ui/`. No one-off buttons.
- Colors and spacing come from design tokens. No hex values, no raw palette classes.
- Every interactive element has an accessible name.
@src/components/ui/button.tsx
The last line references a real file instead of pasting it. Cursor pulls the file into context with the rule, so the example never goes stale.
Nested AGENTS.md or .mdc?
Cursor reads both, and a rule in both places loads twice. Give each rule one home.
| Nested AGENTS.md | .cursor/rules/*.mdc | |
|---|---|---|
| Scope | The folder it sits in, and below | Any glob, anywhere |
| Read by | Cursor, Codex, Copilot, Antigravity and more | Cursor only |
| Best for | Folder rules every agent needs | Rules that cut across folders, root files, manual rules |
The generator puts AGENTS.md first. A rule becomes an .mdc file only when it didn't fit. Codex reads at most 32 KiB per chain of AGENTS.md files, so the generator keeps every chain under 30 KiB. When a folder's chain is full, its AGENTS.md links to the rule's full text instead of copying it, and Cursor gets an .mdc scoped to exactly the globs where that happened. In this big preset, that's 20 of 30 rules.
Real Cursor rules from a generated Next.js repo
The files below come from a real generate run of the Indie SaaS preset: Next.js with Better Auth, Neon, Drizzle, Stripe, Resend, PostHog, Sentry, an admin panel and an MDX blog.
A folder rule, as Cursor reads it
This is the Stripe webhook rule in its folder's AGENTS.md. Cursor applies it when you work in src/app/api/webhooks/stripe/. No .mdc needed.
# src/app/api/webhooks/stripe
Rules for files under `src/app/api/webhooks/stripe`. The root `AGENTS.md` and every
`AGENTS.md` between it and this folder apply here too.
## Verify every Stripe webhook, keep every handler idempotent
Applies to: `src/app/api/webhooks/stripe/**`, `src/lib/billing/provider.ts`, `src/lib/billing/webhook.ts`
Source: `stripe`
The webhook route is an unauthenticated public endpoint. The signature is the
only thing between a Stripe event and a forged POST that grants a lifetime
plan.
First 13 of 72 lines of src/app/api/webhooks/stripe/AGENTS.md.
A file-scoped .mdc rule
The same rule also covers two files in src/lib/billing/. That folder's chain was full, so its AGENTS.md only links to the rule. Cursor gets an .mdc for exactly those two files:
---
alwaysApply: false
description: Verify every Stripe webhook, keep every handler idempotent
globs: src/lib/billing/provider.ts,src/lib/billing/webhook.ts
---
# Verify every Stripe webhook, keep every handler idempotent
The webhook route is an unauthenticated public endpoint. The signature is the
only thing between a Stripe event and a forged POST that grants a lifetime
plan.
The route is three lines: `processWebhook(billingProvider, request)`. The
pipeline in `src/lib/billing/webhook.ts` is shared by every provider, and the
Stripe parts are `verifyWebhook` and `translate` in `provider.ts`. Keep it that
way: nothing Stripe-specific in the route.
**Read the body as text.** `processWebhook` calls `request.text()` and hands
First 18 of 70 lines of .cursor/rules/stripe-webhook-integrity.mdc.
It names real functions and tells the agent exactly what breaks (request.json() reorders keys). A reviewer can check the agent followed it. The full Stripe battery: /with/stripe.
An Always Apply rule
---
alwaysApply: true
description: No personal data in breadcrumbs, tags or extra
---
# No personal data in breadcrumbs, tags or extra
Sentry receives everything you attach to an event and stores it in a system
with a wider access list than your database, in a jurisdiction you did not
choose, for a retention period you did not set. Treat every field as
"published to a third party", because that is what it is.
## Never send
First 13 of 75 lines of .cursor/rules/sentry-no-pii.mdc.
alwaysApply: true, no globs. This rule applies to every file, and it was too long to copy into the root AGENTS.md, so the root links to it and Cursor gets it as an always-on rule.
Skills don't need rules
Cursor reads Agent Skills from .agents/skills/ and .claude/skills/, so the generator writes no rule per skill. The 29 skills, and which agent reads which folder: Agent Skills in every agent.
Cursor hooks, subagents and MCP
Rules are instructions. Cursor reads three more kinds of project config, and a generated repo fills all three.
Hooks: .cursor/hooks.json. Scripts that run around the agent's actions. A hook on beforeShellExecution can refuse a command before it runs. This is the top of the generated file:
{
"version": 1,
"hooks": {
"beforeReadFile": [
{
"command": "bun .agents/hooks/run.mjs env-leak-detector --from cursor",
"timeout": 60
}
],
"beforeShellExecution": [
{
"command": "bun .agents/hooks/run.mjs block-destructive --from cursor",
"timeout": 60
},
{
"command": "bun .agents/hooks/run.mjs enforce-typecheck --from cursor",
"timeout": 60
},
{
"command": "bun .agents/hooks/run.mjs env-leak-detector --from cursor",
"timeout": 60
},
{
"command": "bun .agents/hooks/run.mjs guard-neon-sql --from cursor",
"timeout": 60
}
],
First 27 of 53 lines of .cursor/hooks.json.
Each entry runs a guard from .agents/hooks/ through a launcher, run.mjs, which reads Cursor's payload and answers with permission: "deny" and a reason when a guard blocks. Cursor also loads Claude Code's hooks from .claude/settings.json by default. The launcher sees Cursor's payload there and steps aside, so each guard runs once. All of it: guard hooks in every agent.
Subagents: .cursor/agents/<id>.md. One file per subagent, with readonly: true on the reviewers. Cursor also reads .claude/agents/. On a name clash, the .cursor one wins.
MCP: .cursor/mcp.json. The same servers as every other agent's config:
{
"mcpServers": {
"better-auth": {
"url": "https://mcp.better-auth.com/mcp"
},
"neon": {
"url": "https://mcp.neon.tech/mcp?readonly=true"
},
"posthog": {
"url": "https://mcp.posthog.com/mcp?readonly=true"
},
"sentry": {
"url": "https://mcp.sentry.dev/mcp"
},
"stripe": {
"url": "https://mcp.stripe.com"
}
}
}
.cursor/mcp.json, as generated.
Turn each server on, and sign in, in Cursor's MCP settings. A server that needs a key reads it with ${env:VAR} from the environment Cursor runs in. Cursor never reads .env.local.
Cursor loads project hooks, MCP and subagents only after you trust the folder.
Cursor rules best practices
| Practice | Why |
|---|---|
| Keep each rule under 500 lines | Cursor's own guidance. Every rule in the example repo fits |
| One topic per file, named for it | stripe-webhook-integrity.mdc beats rules2.mdc |
| Put folder rules in that folder's AGENTS.md | Every agent reads it, not only Cursor |
| Scope with globs before you reach for alwaysApply | Always-on rules load in every chat |
| Write the description as a trigger | The agent decides relevance from it |
Reference files with @ | Don't paste code that will drift |
| Show a wrong and a right example | One snippet beats three adjectives |
| Write checkable statements | "Read the body with request.text()" can be verified. "Handle webhooks carefully" can't |
Commit .cursor/ | Rules, hooks, subagents and MCP config are version-controlled, so the whole team gets them |
Common Cursor rules mistakes
- Plain
.mdfiles in.cursor/rules/. Ignored. Use.mdcwith frontmatter. - The same rule in AGENTS.md and an
.mdc. Cursor loads it twice. - Everything on
alwaysApply: true. Every chat pays for every rule. globs: "**"on a narrow rule. It matches every file, so a billing rule shows up for a CSS fix.- No description and no globs. That's a manual rule. It loads only when you @-mention it, and you'll forget.
- A leftover
.cursorrules. Create an Always Apply rule, paste the content in, then delete the old file. Zed also reads.cursorrulesbefore AGENTS.md. - Expecting rules in Cursor Tab. Rules don't touch it, and User Rules skip Inline Edit too.
- Old Next.js advice. Rules copied from a pre-16 project mention
middleware.tsandpages/. Check them against your version. - Rules as a safety net. A rule is an instruction. It can't stop a command from running. A hook can.
Cursor rules vs AGENTS.md
Cursor reads both. AGENTS.md is plain markdown with no frontmatter, at the root or in any subfolder. Nested files combine with their parents, and the more specific one wins. Use it for anything every agent should know, because Codex, Copilot and many other tools read it too. Use .mdc rules when you need globs across folders, descriptions or manual rules. The full comparison: CLAUDE.md vs AGENTS.md. Real AGENTS.md files: AGENTS.md examples.
A Cursor rules boilerplate for Next.js
You can write all of this by hand. Or pick your agents at /build (all 10 are on by default) and get a Next.js repo with AGENTS.md, .cursor/rules/, .cursor/hooks.json, .cursor/agents/ and .cursor/mcp.json already filled in for your stack. The same rules compile to .claude/rules/ for Claude Code and nested AGENTS.md for everyone else, so nothing drifts. Batteries bring their own rules: Better Auth adds auth boundaries, Stripe adds webhook and pricing rules. $99 once, with lifetime updates.
What each agent gets: the agentic layer. The bugs these rules prevent, written up: the cookbook. Other agents: Codex setup, GitHub Copilot setup, Claude Code setup for Next.js.
FAQ
Where do Cursor rules go?
In .cursor/rules/ at the repo root, as .mdc files you commit. Subfolders inside .cursor/rules/ work for keeping them organized. Folder rules can also go in that folder's AGENTS.md, which Cursor reads.
What is an .mdc file?
A markdown file with a frontmatter block on top. The frontmatter holds description, globs and alwaysApply, which decide when Cursor loads the rule.
How do globs work in Cursor rules?
globs lists file patterns separated by commas, like src/app/api/**,src/lib/billing/**. With alwaysApply: false, the rule attaches when a file you're working on matches one of them.
What does alwaysApply do in Cursor rules?
alwaysApply: true puts the rule in every Agent chat. Set it to false to load the rule by glob, by description, or only when you @-mention it.
Is .cursorrules deprecated?
Cursor calls the root .cursorrules file legacy and says it will be deprecated. Move its content into an Always Apply rule in .cursor/rules/, then delete the old file.
Does Cursor read AGENTS.md?
Yes. Cursor reads AGENTS.md at the root and in any subfolder, as plain markdown. Nested files combine with their parents, and the more specific instruction wins.
Does Cursor support hooks?
Yes. Project hooks live in .cursor/hooks.json, on events like beforeShellExecution, beforeReadFile, preToolUse and postToolUse. A hook can deny a command before it runs. Cursor also loads Claude Code hooks from .claude/settings.json by default.
Sources
Tool behavior is from the official docs, checked on October 8, 2026. Tools change. The docs win.
Keep reading
- CLAUDE.md template for Next.js, with real examplesA CLAUDE.md template for Next.js you can copy, where the file goes, what belongs in it, and how a repo shared with other agents loads AGENTS.md instead.
- AGENTS.md examples, from a real Next.js repoWhat AGENTS.md is, a template to copy, real root and nested files from a generated Next.js repo, and how Codex, Cursor, Copilot and Claude Code load them.
- CLAUDE.md vs AGENTS.md: which one you needCLAUDE.md is Claude Code's file. AGENTS.md is the one Codex, Cursor, Copilot and most other agents read. Who reads what, and how to keep both in sync.
- Claude Code skills, with 29 real examplesA Claude Code skill is a SKILL.md file that becomes a slash command Claude can also load on its own. How to write one, what to avoid, and 29 real examples.