What Are Cursor Rules? How to Control What Your AI Codes

Why AI Coders Need to Know This

If you have been vibe coding with Cursor for more than a week, you have almost certainly hit this wall: the AI writes perfectly functional code, but it keeps doing things in the wrong way. Wrong for your project, your stack, your style.

You tell it "build me a login form" and it generates a React class component — but you are using React 18 with functional components and hooks. You ask it to style something and it writes inline CSS — but your entire project uses Tailwind. You request an API endpoint and it scaffolds an Express server — when your project already has Next.js API routes.

So you correct it. It fixes that one file. Next message, same problem. You are stuck in a loop of correction and regeneration that kills the flow state that makes vibe coding so productive in the first place.

Cursor Rules eliminate this loop entirely. Instead of correcting the AI after every generation, you define your rules once. Cursor reads them at the start of every interaction and applies them automatically — no nagging required.

If you are serious about using Cursor effectively, rules are the single highest-leverage thing you can set up. Everything else you learn about Cursor builds on this foundation.

What Are Cursor Rules, Exactly?

Cursor Rules are plain text instructions — written in normal English — that you give to Cursor's AI model. They live in a file called .cursorrules in your project root, or in a special directory called .cursor/rules/.

When you open Cursor in a project that has rules, the AI reads them before doing anything else. Every chat message, every inline edit, every agentic task runs with your rules loaded into the model's context. The AI treats them as constraints it must follow.

There is nothing technical about creating them. A rule looks like this:

Use functional React components with hooks. Never generate class components.
Always use Tailwind CSS for styling — do not write custom CSS.
Use TypeScript for all new files. Avoid 'any' types.

That is it. Plain English, one rule per line (or paragraph). No special syntax, no configuration format to learn. The AI reads natural language and understands what you mean.

Think of it as writing a brief for a contractor before they start work. "Here are the standards I expect. Follow these on every task." The difference is that you write it once, and it applies automatically forever.

The .cursorrules File

The original and still most widely used approach is a single file named .cursorrules placed in your project root — alongside package.json, README.md, and .gitignore.

To create one: open your project root in any text editor or in Cursor itself, create a new file named exactly .cursorrules (no extension), and start writing your rules. Cursor picks it up automatically — no configuration needed.

A complete, real-world .cursorrules file looks like this:

# Project Rules for Cursor AI

## Framework & Stack
- This is a Next.js 15 project using the App Router (not Pages Router)
- TypeScript is required for all files — no plain JavaScript
- Use Tailwind CSS for all styling — never write custom CSS files or inline styles
- Database: PostgreSQL via Prisma — use Prisma Client for all queries
- Auth: NextAuth.js v5 — do not implement custom session logic

## React Conventions
- Use functional components with hooks — never class components
- Use named exports for all components (not default exports)
- Keep components small — extract logic into custom hooks in src/hooks/
- Server Components by default; add 'use client' only when interactivity is required

## TypeScript
- Strict mode is enabled — respect it
- Define interfaces for all data shapes — no 'any' types
- Use Zod for runtime validation at API boundaries

## File Structure
- Pages: src/app/[route]/page.tsx
- Components: src/components/[ComponentName].tsx
- Hooks: src/hooks/use[HookName].ts
- Server actions: src/actions/[domain].ts
- Utilities: src/lib/[utility].ts

## Code Style
- Use async/await — never .then()/.catch() chains
- Always handle errors with try/catch in server actions
- No console.log in production code — use the logger in src/lib/logger.ts
- Prefer early returns over nested conditionals

Commit this file to Git. It is project documentation — it should travel with your codebase.

The .cursor/rules/ Directory (2025 Evolution)

In 2025, Cursor introduced a more powerful system alongside .cursorrules: the .cursor/rules/ directory. Instead of one big file, you can now create multiple rule files organized by topic, file type, or workflow.

The directory structure looks like this:

.cursor/
  rules/
    general.mdc         - Global rules for the whole project
    react-components.mdc - Rules that apply only to .tsx files
    api-routes.mdc      - Rules for files in src/app/api/
    testing.mdc         - Rules that activate when writing tests

Each file uses the .mdc extension (Markdown with Cursor metadata) and can include a frontmatter header that tells Cursor when to apply it:

---
description: Rules for React component files
globs: src/components/**/*.tsx, src/app/**/*.tsx
alwaysApply: false
---

Use functional components with hooks only. Keep components under 150 lines.
Extract all data-fetching logic into server components or custom hooks.
Never use useEffect for data fetching — use React Server Components instead.

The globs field lets you scope rules to specific file patterns. Rules in a file with globs: src/app/api/**/*.ts only activate when Cursor is working on API route files. This means less noise and more precision.

For most vibe coders just getting started, a single .cursorrules file is perfectly fine and easier to manage. Reach for the .cursor/rules/ directory when your project is large enough that global rules start conflicting with each other, or when you want different AI behavior for different parts of the codebase.

6 Practical Rules Every Vibe Coder Should Set

Here are the rule categories that make the biggest difference in day-to-day use, with copy-paste examples for each.

1. Framework and Library Preferences

This is the most important category. Without it, your AI makes assumptions — and they are often wrong.

## Framework Preferences
- This project uses Next.js 15 App Router — never suggest Pages Router patterns
- Use React Query (TanStack Query) for client-side data fetching
- Use Zod for all schema validation and type inference
- Use Radix UI primitives for accessible components — not Material UI or Ant Design
- State management: Zustand only — do not suggest Redux or Context API for global state

2. Coding Style and Patterns

The difference between code you recognize as yours and code that feels foreign.

## Code Style
- Prefer async/await over Promise chains
- Use early returns to avoid deep nesting — max 2 levels of indentation preferred
- Arrow functions for callbacks and utility functions
- Named function declarations for React components and exported utilities
- No magic numbers — extract constants with descriptive names
- Prefer explicit over implicit — be verbose about intent

3. File and Directory Structure

Without this, the AI creates files wherever it wants. With it, new files always land in the right place.

## File Structure
- New components go in src/components/[ComponentName]/index.tsx
- New pages go in src/app/[route]/page.tsx
- Shared types go in src/types/[domain].ts — never inline types in component files
- API helpers go in src/lib/ — not in component files
- Database queries go in src/lib/queries/ — never directly in components or pages
- Test files: [filename].test.ts next to the file they test

4. Error Handling Patterns

AI-generated code often has no error handling. Define your pattern and it will always include it.

## Error Handling
- Always wrap server actions in try/catch
- Use a Result type pattern for functions that can fail: return { data, error }
- Log errors to the logger (src/lib/logger.ts) — never console.error in production
- Show user-facing error messages from a centralized error map — never expose raw error messages
- API routes must always return proper HTTP status codes (400 for validation, 500 for server errors)

5. Comment and Documentation Style

Determines whether AI-generated code is readable or cluttered with noise.

## Comments
- Do not add comments that restate what the code does — only comment on WHY
- Add JSDoc comments to all exported functions and components
- Mark temporary workarounds with TODO: [reason] comments
- Do not comment out old code — delete it (we have Git for history)
- Complex algorithms or business logic should have a brief explanation comment above them

6. TypeScript Strictness

Without explicit TypeScript rules, the AI will take the easy path and reach for any.

## TypeScript
- Strict mode is enabled — honor all strict checks
- Never use 'any' type — use 'unknown' and narrow it, or define a proper interface
- Prefer interface over type alias for object shapes
- Use discriminated unions for state that has multiple variants
- Generics are fine — use them when they improve reusability without obscuring intent
- All API responses must have a typed interface defined in src/types/

How This Compares to CLAUDE.md and Copilot Instructions

If you use multiple AI coding tools (which most serious builders do), it helps to know how the systems compare. The concept is identical across tools — a project-level instructions file — but the format and capabilities differ slightly.

The key difference between Cursor's system and CLAUDE.md is scope. CLAUDE.md is designed to give context about your project — architecture, commands, current work status — in addition to coding conventions. .cursorrules tends to be more focused on coding style and behavior constraints.

In practice, the content overlaps heavily. If you move between Cursor and Claude Code, your rules translate almost directly. The conventions section of your CLAUDE.md becomes your .cursorrules. You are maintaining the same ideas in two slightly different formats.

GitHub Copilot's .github/copilot-instructions.md is the most limited — it only supports plain Markdown and cannot be scoped to specific file types the way Cursor's .cursor/rules/ can. But it works well for basic style preferences.

If you want a deeper dive into how these tools compare overall, the Cursor vs Windsurf comparison covers the full picture of where each tool excels.

What AI Gets Wrong With Rules

Rules are powerful, but they only work if you write them well. Here are the most common mistakes vibe coders make — and how to avoid them.

Rules that are too vague

"Write clean code" is not a rule. "Write good TypeScript" tells the AI nothing it doesn't already believe it's doing. Vague rules get ignored in practice because the AI has no concrete behavior to change.

Bad: Write maintainable code with good error handling.
Good: All server actions must be wrapped in try/catch. Return { data: null, error: message } on failure.

Conflicting rules

If you tell the AI to "keep functions small" and also "avoid splitting logic across too many files," you will get inconsistent results depending on which rule the AI weights more heavily on a given generation. Audit your rules for contradictions — especially when you have added rules incrementally over time.

Rules that over-constrain the AI

It is tempting to add a rule for everything. Resist. If your rules file is 500 lines long and covers every micro-decision, you are not getting AI assistance anymore — you are writing the code via rules and having the AI transcribe it. Leave room for the AI to make reasonable choices within your constraints. Rules should set the guardrails, not micromanage every line.

A good prompt paired with good rules beats elaborate rules alone. The AI prompting guide for coders covers how to write prompts that work with your rules to get the output you want.

Rules you never update

Your rules were written for your project at a specific point in time. When you switch from REST to tRPC, update your rules. When you upgrade from Next.js 14 to 15 App Router, update your rules. Stale rules cause the same problem as no rules — the AI follows instructions that no longer match your codebase.

Piling on rules to compensate for bad prompting

If you find yourself adding a rule every time the AI does something you don't like, stop and ask whether the problem is a rules gap or a prompting gap. Some things are better handled with a clear prompt in the moment than baked into permanent rules. Rules are for conventions that apply every time — not for one-off preferences on a specific task.

For deeper techniques on getting consistent results from AI code generation, see the guide to agentic coding — the principles apply directly to how Cursor uses your rules in autonomous mode.

Getting Started in 10 Minutes

If you have an existing Cursor project, here is the fastest path to a useful .cursorrules file:

1. Open your project root in Cursor or any text editor.
2. Create a new file named .cursorrules (no extension).
3. Write a single section: your framework and library stack. Be specific — include versions.
4. Add a second section: your React or language conventions (functional vs class, naming conventions).
5. Save the file and open a Cursor chat. Ask it to build something small and watch it follow your rules.
6. Add sections over the next week as you notice the AI making decisions you want to correct.

Start with 20–30 lines. A focused rules file beats a sprawling one. You will learn what actually needs to be specified by watching what the AI gets wrong — add rules reactively for the first few weeks, then consolidate.

What to Learn Next

• Cursor Beginner's Guide — Full walkthrough of Cursor's interface, modes, and core features. Start here if you are new to the editor.
• What Is a CLAUDE.md File? — Claude Code's equivalent to .cursorrules, with examples and a full template.
• What Is Agentic Coding? — How AI tools like Cursor operate autonomously on multi-step tasks, and how rules shape that behavior.
• AI Prompting Guide for Coders — Write better prompts that work with your rules to get consistent, high-quality code generation.
• Cursor vs Windsurf — Full comparison of both editors, including how their rules systems compare.
• AI Pair Programming Guide — Rules set the foundation; pair programming is the workflow that makes them pay off.
• What Is Testing? — You can add testing conventions to your rules so AI generates the right test patterns automatically.

FAQ