Rules: Teaching Cursor Your Codebase

What Rules Are

Rules are persistent instructions that are injected into Cursor's context before every AI interaction. Without rules, Cursor knows your code but not your standards — it doesn't know you prefer Tailwind over CSS modules, that you use App Router not Pages Router, that every function should have a JSDoc comment, or that you never use console.log in production code. Rules fill that gap.

Rules are the single highest-leverage configuration in Cursor. Set them up at the start of a project, and every Chat response, every Cmd+K edit, and every Agent task starts with an accurate picture of your conventions.

The Old Format: .cursorrules

The original rules format was a single file named .cursorrules in the project root. It is still supported and still works. Its limitation: it is always loaded, it cannot be scoped to specific file types, and it counts against your context window on every single prompt regardless of relevance.

The Modern Format: .cursor/rules/*.mdc

In January 2026, Cursor replaced the single .cursorrules file with a directory-based format: .cursor/rules/, where each file is a .mdc file with YAML frontmatter. This format gives you precise control over when each rule file is loaded.

A basic rule file looks like this:

--- description: TypeScript and React conventions for this project globs: ["*.tsx", "*.ts"] alwaysApply: false --- Use TypeScript strict mode. Prefer interfaces over types for object shapes. Use React functional components. Never use class components. Import React explicitly: import React from 'react'. Tailwind CSS for all styling — no inline styles, no CSS modules.

The Four Activation Modes

• Always Apply (alwaysApply: true) — Loaded in every prompt, regardless of what file you have open. Use this for global standards: general coding principles, project-wide constraints, your team's non-negotiables.
• Auto Attached (glob patterns in frontmatter) — Automatically injected when you open a file matching the glob. Set globs to ["*.tsx"] for React rules, ["*.test.ts"] for testing rules. Token-efficient: rules are only loaded when they're relevant.
• Agent Requested (descriptive name/description, no globs) — The agent reads the rule's description and decides when to load it. Use for workflow rules: "use this rule when working on the authentication system" or "use this rule when generating database migrations".
• Manual (no auto conditions) — Reference explicitly in Chat by typing @rule-name. Use for optional reference material you want to pull in selectively.

What to Put in Rules

• Tech stack and versions (Next.js 15 App Router, TypeScript 5.4, Drizzle ORM)
• File structure and naming conventions (components in components/, API routes in app/api/)
• Import patterns (path aliases, what to import from where)
• Testing approach (Vitest, file naming: *.test.ts, where mocks live)
• What NOT to generate ("never add console.log", "never use any in TypeScript")
• Architectural constraints ("all DB access goes through the repository layer in lib/db/")

What Not to Put in Rules

Entire README files, lengthy prose explanations, or documentation that changes per task. Keep each rule file focused on actionable standards — not background context. Rules consume context window tokens on every load; a bloated rule file hurts both performance and output quality.