Why Your Cursor Rules Don't Work in Agent Mode (And How to Fix It)

You added a .cursorrules file to your Next.js project. You wrote detailed instructions about your stack, your conventions, your preferences.

And then you opened Cursor in Agent Mode and... Cursor ignored all of it.

Sound familiar?

The Silent Problem Nobody Talks About

Here's what's happening: .cursorrules is a legacy format that Cursor stopped reading in Agent Mode.

When you use Chat or Composer, it works (sometimes). But Agent Mode — which is now the primary way most developers use Cursor — loads a completely different context system.

Your carefully written .cursorrules file? Silently ignored.

This means every Agent Mode session, you're starting from scratch:

• "Use Next.js App Router, not Pages Router"
• "We use Clerk for auth, not NextAuth"
• "Always validate with Zod"
• "Use server components by default"

You're not forgetting to write rules. The format you're using is just outdated.

The Solution: .mdc Rules

Cursor's new rule system uses .mdc files inside a .cursor/rules/ directory.

Here's what makes .mdc different:

1. They work in ALL modes
Chat, Composer, and Agent Mode — your rules load consistently everywhere.

2. Modular scoping
Each .mdc file has frontmatter that controls exactly when it activates:

---
description: Next.js App Router conventions
globs: ["app/**/*.tsx", "app/**/*.ts"]
alwaysApply: false
---

With globs, this rule only activates when you're working in the app/ directory. No context bloat on unrelated files.

3. alwaysApply: true for critical context
Some rules should always load — like your project's core stack declaration:

---
description: Core project context and stack
alwaysApply: true
---

# Project Context

- Framework: Next.js 15 (App Router)
- Auth: Clerk (NOT NextAuth)
- Database: Supabase + Prisma
- Payments: Stripe
- UI: shadcn/ui + Tailwind CSS

This fires on every single session, in every mode.

Setting It Up For Next.js

Create this folder structure in your project root:

your-project/
├── .cursor/
│   └── rules/
│       ├── 001-project-context.mdc    ← alwaysApply: true
│       ├── 010-typescript.mdc         ← alwaysApply: true
│       ├── 020-nextjs-app-router.mdc  ← glob: app/**
│       ├── 030-supabase.mdc           ← glob: lib/supabase/**
│       └── 040-stripe.mdc             ← glob: lib/stripe/**

Here's a starter 001-project-context.mdc you can copy:

---
description: Core project stack and conventions
alwaysApply: true
---

# Project Context

## Stack
- Framework: Next.js 15 (App Router ONLY)
- Language: TypeScript strict mode
- Auth: Clerk
- Database: Supabase (PostgreSQL)
- Payments: Stripe
- UI: shadcn/ui + Tailwind CSS
- AI: Vercel AI SDK

## Core Rules
- ALWAYS use App Router — never Pages Router
- ALWAYS default to server components
- ONLY add "use client" when strictly necessary
- ALWAYS validate with Zod before processing data

Save that file, restart Cursor, open Agent Mode, and ask: "What stack are we using?"

Cursor will answer correctly. No re-explaining.

How Many Rules Should You Have?

For a typical Next.js SaaS project, I recommend separating rules by concern:

File	Scope	Purpose
001-project-context.mdc	Always	Stack declaration
010-typescript.mdc	Always	TS standards
020-nextjs-app-router.mdc	app/**	Routing conventions
030-react-components.mdc	components/**	Component patterns
040-server-actions.mdc	actions/**	Server action patterns
050-api-routes.mdc	app/api/**	API conventions
060-supabase.mdc	lib/supabase/**	DB patterns
070-clerk.mdc	middleware.ts	Auth patterns
080-stripe.mdc	lib/stripe/**	Payment patterns

Each file stays focused. Cursor loads only what's relevant to the files you're editing.

The Result

After setting this up properly, your Agent Mode sessions become dramatically more consistent:

• ✅ No more "use NextAuth" when you're using Clerk
• ✅ No more useEffect fetches when you should use server components
• ✅ No more missing Zod validation
• ✅ No more any types slipping through

Your AI pair programmer finally knows your project as well as you do.

---

I spent the last week writing 15 battle-tested .mdc rules specifically for the Next.js AI SaaS stack (Supabase + Clerk + Stripe + Vercel AI SDK + shadcn/ui).

3 of them are free on GitHub if you want to start immediately:
👉 github.com/irsyad-aulia/nextjs-ai-saas-cursor-rules

The full pack of 15 rules is available for $49 if you want the complete setup:
👉 Next.js AI SaaS Cursor Rules Pack

Drop a comment if you have questions — building in public from Indonesia 🇮🇩 @irsyadbuilds