Skip to content

Cursor rules for Next.js, with real .mdc examples

How Cursor rules work: the .mdc format, globs, alwaysApply and the four rule types, when a nested AGENTS.md is enough, and real Next.js rules to copy.

Updated · 10 min read

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

TypeWhereApplies to
Project rules.cursor/rules/*.mdc, committed to gitThis repo
User rulesCursor settingsEvery project you open
Team rulesThe Cursor dashboardEvery repo on the team
AGENTS.mdThe repo root and any subfolderThis repo, as plain markdown
CLAUDE.mdThe repo rootThis 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.mdc is fine.
  • Plain .md is ignored. A .md file 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.
  • .cursorrules is legacy. Cursor says the root .cursorrules file "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:

FieldValueWhat it does
descriptionA sentenceTells the agent what the rule is for. Cursor uses it to decide relevance
globsFile patterns, comma-separatedAttaches the rule when a file you're working on matches
alwaysApplytrue or falsetrue 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.

TypeFrontmatterLoadsNext.js use
Always ApplyalwaysApply: trueEvery chat sessionCode style, git, security
Apply to Specific FilesalwaysApply: false plus globsWhen a file matchesWebhooks, schema, components
Apply IntelligentlyalwaysApply: false plus descriptionWhen the agent decides it's relevantProcedures: add a page, run a migration
Apply ManuallyalwaysApply: false, no description, no globsWhen you @-mention it, like @my-ruleOne-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:

GlobMatches
src/app/**/page.tsxEvery page
src/app/**/route.tsEvery 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.tsxUnit and end-to-end tests
next.config.ts,src/proxy.tsBuild 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.ts
  • auth-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.tsx
  • code-style: every file
  • deployment: next.config.ts, vercel.json, package.json, src/proxy.ts, src/app/**/route.ts, .env.example
  • drizzle-migrations: src/db/**, drizzle/**, drizzle.config.ts
  • drizzle-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 file
  • identify-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 file
  • sentry-capture: src/**, sentry.server.config.ts, sentry.edge.config.ts
  • sentry-no-pii: every file
  • server-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.ts
  • testing: tests/**, src/**/*.test.ts, src/**/*.test.tsx
  • tokens-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
ScopeThe folder it sits in, and belowAny glob, anywhere
Read byCursor, Codex, Copilot, Antigravity and moreCursor only
Best forFolder rules every agent needsRules 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

PracticeWhy
Keep each rule under 500 linesCursor's own guidance. Every rule in the example repo fits
One topic per file, named for itstripe-webhook-integrity.mdc beats rules2.mdc
Put folder rules in that folder's AGENTS.mdEvery agent reads it, not only Cursor
Scope with globs before you reach for alwaysApplyAlways-on rules load in every chat
Write the description as a triggerThe agent decides relevance from it
Reference files with @Don't paste code that will drift
Show a wrong and a right exampleOne 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 .md files in .cursor/rules/. Ignored. Use .mdc with 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 .cursorrules before 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.ts and pages/. 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.