Cursor rules are persistent, project specific instructions that tell the AI in Cursor how your codebase works: the stack you use, the conventions you follow, and the patterns you want it to prefer or avoid. Instead of re-explaining your standards in every chat, you write them down once, commit them to the repository, and let the editor apply them automatically to completions, edits, and agent runs. This guide explains what the .cursorrules file is, why rules matter, and how to write good ones, including a worked example and a table of common rule categories. Because Cursor evolves quickly, we teach the durable method and point you to the official documentation for the exact, current file formats.
What are Cursor rules?
A rule is a piece of guidance the model reads as context before it suggests or writes code. Historically many teams kept this guidance in a single .cursorrules file at the root of the repository, a plain text file describing how the AI should behave in that project. Cursor has since expanded this into a more structured system of project rules (often stored under a dedicated rules folder) that can be scoped, named, and toggled, while still supporting the legacy single file approach for backward compatibility. The underlying idea is unchanged: rules are durable, versioned instructions that travel with your code so every contributor and every AI action shares the same expectations.
Think of rules as the onboarding document you would hand a new teammate, written for the model. They are not prompts you type once and lose; they persist across sessions and apply automatically. That persistence is what makes them powerful, and it is also why writing them carefully matters.
Why Cursor rules matter
Context quality is the single biggest lever on AI output, and good cursor rules are context you do not have to retype. Without rules, the model guesses at your conventions and you spend time correcting the same mistakes: the wrong package manager, a deprecated API, an inconsistent file layout, or a testing style your team abandoned. With rules in place, suggestions arrive already aligned with how your project is built, which means fewer corrections, more consistent code, and a smoother experience for everyone on the team.
- Consistency: every contributor gets suggestions that follow the same standards, not whatever each person happens to prompt.
- Less repetition: you stop re-explaining your stack and conventions in every conversation.
- Fewer regressions: rules can steer the AI away from deprecated libraries, risky patterns, or banned APIs.
- Shared knowledge: rules live in version control, so they review, evolve, and roll back like any other code.
How to write good rules
The best rules read like clear, specific instructions a careful engineer could follow without asking questions. Vague guidance produces vague results, so prefer concrete statements over aspirations. "Write clean code" helps no one; "use named exports, group imports by standard, internal, then relative, and never import from a barrel file" gives the model something it can actually apply.
- Start from real pain. Capture the conventions you keep restating, not a wish list of everything you could imagine.
- Be specific and actionable. Name the libraries, patterns, and commands you prefer, and say what to avoid.
- Keep each rule short. Several focused rules beat one sprawling document the model has to wade through.
- Scope where you can. If your project supports scoped or path based rules, attach guidance to the files it applies to so it only activates where relevant.
- Commit and review. Treat rules like code: put them in version control, review changes, and prune anything stale.
A simple do and don't structure works well because it tells the model both the target and the boundary. Pair a positive instruction ("prefer the native fetch API") with its negative counterpart ("do not add axios or other HTTP client dependencies") so there is no ambiguity about intent.
An example rules block
Here is an illustrative .cursorrules style block for a TypeScript and React project. Treat it as a starting shape to adapt, not a fixed standard, and check the official docs for the current recommended file location and format in your version of Cursor.
# Project: Web app (TypeScript + React)
## Stack
- Use TypeScript in strict mode. No "any" unless justified with a comment.
- Use React function components and hooks. No class components.
- Use the project package manager (pnpm). Do not introduce npm or yarn lockfiles.
## Conventions
- Prefer named exports over default exports.
- Co-locate component, styles, and test in the same folder.
- Use the existing UI components in src/components before adding new ones.
## Style
- Match the configured Prettier and ESLint setup. Do not reformat unrelated code.
- Write descriptive names. Avoid one-letter variables outside short loops.
## Do
- Add or update a test when you change behavior.
- Handle loading and error states for any data fetching.
## Don't
- Do not add new dependencies without asking first.
- Do not call external APIs from UI components; use the data layer.
- Do not commit secrets, tokens, or hard-coded credentials.Common rule categories
Most effective rule sets cover a handful of recurring categories. The table below is a planning checklist: you rarely need all of it on day one, so start with the categories where your team disagrees most or corrects the AI most often.
| Category | What it covers | Example rule |
|---|---|---|
| Stack and tooling | Languages, frameworks, package manager, runtime | Use pnpm and Node 20; do not add a different package manager. |
| Code style | Naming, formatting, imports, file structure | Use named exports and group imports standard, internal, relative. |
| Architecture | Layers, boundaries, where logic belongs | Keep data fetching in the service layer, not in components. |
| Dependencies | Libraries to prefer, avoid, or never add | Prefer the built-in fetch; do not add a new HTTP client. |
| Testing | Framework, coverage expectations, patterns | Add a test for any behavior change using the existing test setup. |
| Security and safety | Secrets, input handling, dangerous operations | Never hard-code credentials; validate and sanitize external input. |
Keeping rules effective over time
Rules are not a set and forget artifact. As your stack changes, old guidance can quietly steer the model wrong, telling it to prefer a library you have since dropped or a pattern you have replaced. Treat rules like documentation that ships with the code: revisit them when you make a significant architectural change, prune anything that no longer reflects reality, and keep each rule earning its place. A short, accurate rule set beats a long, stale one every time.
It also helps to pair rules with good habits at the prompt level. Rules set the defaults, but precise context and clear requests still matter for any individual task. For more on that, see our companion guide to Cursor tips and tricks, which covers context selection, picking the right AI surface, and running the agent carefully.
Bottom line and how to stay current
Well written cursor rules are one of the highest leverage investments you can make in an AI assisted codebase. Capture your stack, conventions, style, and do and don't guidance once, commit it, and every suggestion gets a little more aligned with how you actually build. Because Cursor ships quickly and the rule system continues to evolve, the smartest move is to learn the method here and watch the official changelog for format changes rather than memorizing any single file layout. If you would rather get the highlights without combing through release notes, Cursor Drops summarizes new releases for you, and the in-app changelog keeps a running history. You can grab the app on the App Store, then bookmark the documentation for authoritative details whenever rules change.
Sources
Maintainer, Claude Drops
Ian builds Claude Drops and reads every Claude Code release so you don't have to. He writes plain-English guides to Claude Code's features, drawing directly from the official changelog and documentation.