A rules file is the single highest-leverage thing you can add to a Cursor project — it's the difference between re-explaining your conventions every session and having the AI just already know them. Cursor supports both a legacy .cursorrules file and the newer .cursor/rules/*.mdc format with scoped, per-directory rules, and most people either skip this entirely or write one bloated file that nothing actually reads carefully.
Why Rules Files Matter (and When They Don't)
Without rules, every AI suggestion is generated from the model's generic defaults plus whatever it can infer from surrounding code — which means it'll happily suggest class components in a hooks-only codebase, or axios when you standardized on fetch. A rules file front-loads that context so it doesn't have to be re-derived, and re-litigated, every single prompt.
Skip a rules file if your project is small enough (a script, a one-off prototype) that conventions don't matter yet — writing one for a throwaway project is pure overhead.
Getting Started with Cursor Rules
The modern approach is .cursor/rules/*.mdc — multiple scoped files instead of one giant blob:
.cursor/rules/
general.mdc # applies everywhere
api-routes.mdc # globs: src/app/api/**
components.mdc # globs: src/components/**
---
description: API route conventions
globs: src/app/api/**/*.ts
---
- Validate all input with Zod before touching the database
- Return NextResponse.json with explicit status codes, never bare objects
- Wrap DB calls in try/catch and log the error before returning 500
Scoped rules only load when Cursor is working in matching files, which keeps the model's context focused instead of dumping every rule into every prompt.
Core Concepts Every Developer Should Know
1. Be specific, not aspirational. "Write clean code" does nothing — the model has no shared definition of clean. "Use named exports, not default exports" is a rule it can actually follow.
2. Show, don't just tell. A short code snippet of the pattern you want beats three sentences describing it. Models pattern-match on examples better than on abstract instructions.
3. Scope aggressively. A rule about API error handling shouldn't load when you're editing a CSS file — glob patterns keep rules relevant and keep the context window from filling with irrelevant instructions.
4. Keep it short. Rules compete for the model's attention with your actual prompt. Ten precise, high-signal rules beat fifty vague ones that get skimmed and ignored.
Common Mistakes and How to Fix Them
Mistake 1: One giant unscoped file. Dumping every convention — frontend, backend, testing, deployment — into a single global file means most of it is irrelevant noise for any given edit. Split by directory glob.
Mistake 2: Rules that contradict the actual codebase. If your rule says "use Zustand for state" but half your components still use Context, the model gets mixed signals from the rule versus the code it can see. Fix the code or fix the rule — don't leave both.
Mistake 3: Never updating them. Rules files rot exactly like documentation. Revisit them when you change a major convention (a new state library, a new API pattern) or the AI starts confidently suggesting the old way.
When Should You Invest in Rules?
The moment a project has more than one contributor — human or AI — writing consistent code, rules pay for themselves. They matter most on long-lived codebases where "how we do things here" isn't obvious from any single file.
In Production
On suhailroushan.com I keep scoped rules for API routes, MongoDB access patterns, and component structure — each under 15 lines, each tied to a glob. New AI-generated code matches the existing style closely enough that review is about logic, not formatting nits.
Start with one rules file covering your three most-violated conventions, then split it by directory once it grows past a screen's worth of text.