How to Write Cursor Rules in 2026: .cursor/rules (MDC) vs .cursorrules, Templates Inside

TL;DR

If you use Cursor, Windsurf, Cline, Claude Code, or Copilot, you know the problem: every new session starts with zero project context, and the AI guesses at your conventions. The fix is a project rules file.

Important 2026 change: Cursor deprecated the single-file .cursorrules in favor of the .cursor/rules/*.mdc directory format. More critically, .cursorrules is silently ignored in Cursor's Agent mode — if you've switched to agentic workflows, your rules file isn't loading at all. New projects should use .mdc files.

Everything else still works: Windsurf uses .windsurfrules, Cline uses .clinerules, Claude Code uses CLAUDE.md, Copilot uses .github/copilot-instructions.md, Aider uses CONVENTIONS.md.

Use our free AI Coding Config Generator to generate a tailored file for your project in seconds.

What Are AI Coding Rules Files?

Rules files are configuration documents placed in your project root (or a rules directory) that your AI editor reads on every interaction. They define your tech stack, coding conventions, architecture constraints, and testing requirements. Without one, the AI guesses. With one, it knows.

The 2025 Stack Overflow survey found 84% of developers use AI tools, but only 33% trust their accuracy. Well-crafted rules are the single highest-leverage fix for "AI is almost right, but not quite" — they turn a blank-slate model into a project-aware one.

Format Comparison Table (2026)

1. Cursor — .cursor/rules/*.mdc (the 2026 standard)

Cursor standardized on the MDC format (Markdown with Configuration) in late 2024 and it remains the recommended approach in 2026. Instead of one flat file, you keep a directory of modular rule files, each with YAML frontmatter that controls when it loads:

your-project/
├── .cursor/
│   └── rules/
│       ├── base.mdc        # always applies
│       ├── react.mdc       # applies to .tsx/.jsx files
│       ├── api.mdc         # applies to API routes
│       └── testing.mdc     # applies to test files
└── src/

The four activation modes

• Always apply — alwaysApply: true. Loads in every Chat, Composer, and Agent session. Use for foundational rules (language version, naming, commit format). Keep the combined content under ~2,000 tokens — these rules consume context before your code is analyzed.
• Auto-attach by glob — globs: ["**/*.tsx"]. Loads only when a matching file appears in context. React conventions load for component work, not for API work. This is the "no token tax" win over legacy .cursorrules.
• AI-decided — alwaysApply: false with only a description. Cursor's agent decides relevance from the description.
• Manual — no frontmatter. Loaded only when you @-mention the rule name in chat.

Example: always-applied base rules

---
alwaysApply: true
description: "Core TypeScript and project conventions"
---
- TypeScript strict mode — never use `any`; use `unknown` or a defined type.
- Named exports only. No default exports.
- All async functions handle errors with try/catch.
- pnpm is the package manager — not npm or yarn.
- Tests live next to components: Button.test.tsx

Example: glob-scoped React rules

---
globs: ["**/*.tsx", "**/*.jsx"]
description: "React component conventions"
---
- Functional components with hooks only. No class components.
- Use React Server Components by default; add "use client" only for interactivity.
- Keep one component per file, one responsibility.
- Use cn() utility for conditional Tailwind classes.

Rule precedence: Team Rules > Project Rules > User Rules. User Rules live in Cursor settings and apply globally (Chat/Agent only, not inline autocomplete).

2. Cursor legacy — .cursorrules (when it's still fine)

Is .cursorrules deprecated? Yes — Cursor deprecated it around version 0.43, and it's silently ignored in Agent mode. Cursor still reads it for Chat and Composer, so nothing breaks overnight, but it receives no new features.

Use legacy .cursorrules only if: your project is under ~5 packages, you want zero configuration overhead, and rules apply uniformly. Otherwise, migrate to .mdc.

Here's a working legacy template if you need one (React + TypeScript):

# Project: SaaS Dashboard
# Stack: React 19, TypeScript 5.5, Next.js 15, Tailwind CSS v4, Prisma, PostgreSQL

## Core Conventions
- Use functional components with hooks. No class components.
- Prefer named exports over default exports.
- Use React Server Components by default. Only add "use client" when interactivity is needed.
- Keep components small — one file, one component, one responsibility.

## State Management
- Server state: TanStack Query.
- Global client state: Zustand stores in src/stores/.
- Never use useEffect for data fetching. Use React Query.

## Styling
- Tailwind CSS only. No CSS Modules, no styled-components.
- Use cn() utility for conditional classes.

## Testing
- Vitest + React Testing Library.
- Tests co-located with components: Button.test.tsx.

## Architecture
- Feature-based folder structure: src/features/auth/, src/features/dashboard/.
- Business logic in src/lib/, not in components.
- Database queries through Prisma client in src/lib/db.ts only.

To migrate: split each section into its own .mdc file with appropriate frontmatter (base conventions → alwaysApply; React rules → globs on **/*.tsx; API rules → globs on **/api/**).

3. Windsurf — .windsurfrules

Windsurf's Cascade reads .windsurfrules from the project root. Format is plain Markdown — same content structure as Cursor's legacy file. Windsurf also supports AGENTS.md as an alternative entry point.

# Project: API Service
# Stack: FastAPI, Python 3.12, PostgreSQL, Docker

## Conventions
- Use async/await, never .then().
- Type hints on all function signatures.
- Pydantic models for all request/response schemas in schemas/.
- Alembic for migrations — never hand-write DDL.

## Architecture
- Layered: routes → services → repositories.
- No business logic in route handlers.
- All external calls go through service layer with retry logic.

4. Cline — .clinerules

Cline (the open-source VS Code agent) reads .clinerules from the project root. Cline supports both a project-level file and .clinerules/ directory with per-task files — the directory variant lets you scope rules to specific workflow types (e.g., code-review.md, debugging.md).

5. Claude Code — CLAUDE.md

Claude Code reads CLAUDE.md from the project root, plus optional CLAUDE.local.md for personal overrides (gitignored). It also supports a CLAUDE/ directory (like Cursor's rules dir) for scoped rules by glob. Format is plain Markdown:

# Project: Billing Platform
# Stack: TypeScript, Node.js 22, PostgreSQL, Stripe, Vitest

## Conventions
- TypeScript strict mode. Never use `any`.
- Use zod for all runtime validation.
- Money: store cents as integers. Never use floats for currency.
- Idempotency keys required on all billing endpoints.

## Testing
- Vitest. All billing logic must have unit tests.
- Mock Stripe via stripe-mock, never real API in tests.

6. GitHub Copilot — copilot-instructions.md

Copilot reads .github/copilot-instructions.md (plus optional .github/instructions/*.instructions.md for scoped files). Content is plain Markdown injected into chat and agent context. Important: Copilot's inline completions don't read these files — they're for chat/agent workflows only.

7. Aider — CONVENTIONS.md

Aider (terminal agent) reads CONVENTIONS.md from the repo root, and you can add --read files for extra context. Because Aider is git-native, conventions are auto-included in commits and easy to review in PRs. Format: plain Markdown with your stack and rules.

Common Anti-Patterns to Avoid

• Still using .cursorrules for Agent mode. It's silently ignored. Migrate to .cursor/rules/*.mdc.
• One giant rule file. Everything loads every time — the "token tax." Split by concern and scope with globs.
• Rules without the stack line. Always open with a one-line tech stack so the AI never suggests incompatible alternatives.
• Abstract descriptions instead of examples. Show your error-handling pattern; don't just say "handle errors."
• Forgetting the anti-patterns gallery. Explicitly forbidding common AI mistakes is more reliable than describing what you want.
• Rules that fight the tool. Copilot instructions don't affect inline completions; CLAUDE.md doesn't apply to Cursor. Use the right file per tool.

Get Started in 30 Seconds

1. Open our AI Coding Config Generator and pick your stack (React, Next.js, FastAPI, etc.).
2. Copy the generated rules into .cursor/rules/base.mdc (or the matching file for your tool).
3. Commit it. Rules are team assets — review them in PRs like code.
4. Run a real task, then tighten the rules based on what the AI still gets wrong.

Rules files are living documents. Start small, iterate with real work, and your AI output quality will climb fast.

How we wrote this

This is a major update of our July 24, 2026 guide, revised August 7, 2026 to correct a significant change: Cursor deprecated .cursorrules and ignores it in Agent mode, so the guide now leads with .cursor/rules/*.mdc. Sources:

• Cursor's official documentation and changelog (MDC format, activation modes)
• Independent 2026 format guides (thepromptshelf, vibecodingacademy, agentrulegen, cursor.fan) — all confirm the same deprecation and migration path
• Tool-specific docs for Windsurf, Cline, Claude Code, Copilot, and Aider rules files

Format details are current as of August 7, 2026 and can change with editor releases. The core principle — project context beats prompts — hasn't changed since 2024.