How to Write a .cursorrules File That Actually Works

What a .cursorrules File Does

A .cursorrules file is the config Cursor reads to steer its AI inside your project. It carries the conventions to follow, the patterns to avoid, and the stack-specific rules that keep generated code looking like the rest of the codebase. The editor's agent treats it as standing context on every request in that repo.

Knowing how to write a .cursorrules file well is mostly about restraint. The popular sources push in two directions. Trigger.dev's piece on great Cursor rules is solid best-practice prose. The awesome-cursorrules repo is a giant collection of example files. The Cursor forum best-practices thread is community lore.

The best-practice writing is fine. The example dumps are the trap. Grabbing a 600-line rules file written for someone else's stack gives the agent a pile of rules that don't match your code, no curation, and no verification step. The agent then half-follows them, which is worse than no rules at all.

Why Copy-Pasted Rules Backfire

A borrowed .cursorrules file feels productive. You paste 500 lines, the agent now has "rules," done. Then it starts enforcing a state-management pattern you don't use and ignoring the one you do, because the file was written for a React app and yours is Vue.

Two things break with copy-paste. The rules don't match reality, so the agent applies conventions your codebase doesn't follow. And the sheer length means the model skims. A focused 80-line file the agent reads in full beats a 600-line file it samples. Past a few hundred lines, every extra rule competes for attention with the ones that matter.

There's a third miss that even the good prose guides underplay: no verification step. A rules file should tell the agent how to check its own work before claiming done. Most don't, so the agent declares victory on code that never ran the test.

What a Working Rules File Contains

• Stack facts. The actual language, framework, and versions, so rules reference real tooling.
• The conventions that matter. Import order, naming, the state pattern you use, the error-handling shape reviewers expect.
• The anti-patterns. What the agent must not produce: the deprecated API, the banned library, the pattern your team killed.
• A verification block. The check the agent runs before claiming done: run {{test_command}}, confirm the lint is clean, confirm the change is in scope.
• The scope. What this rules file governs, especially in a repo with more than one app.

Keep it tight. A rule that doesn't change the agent's behavior is just noise that crowds out the rules that do.

A Rules-Authoring Prompt You Can Copy

Instead of borrowing a dump, generate a focused file from your facts.

You write a .cursorrules file for this project.

Stack facts: {{stack_facts}}
Conventions reviewers enforce: {{conventions}}
Patterns to ban: {{anti_patterns}}

Produce a .cursorrules file under 200 lines with these sections:
- Stack: the versions and tooling, stated plainly.
- Conventions: one rule per line, imperative.
- Avoid: the banned patterns, one per line.
- Verify before done: run {{test_command}}, lint clean, scope check.

Use only the facts provided. Don't pad with generic advice.
Cut any rule that wouldn't change the agent's output.

The "cut any rule that wouldn't change the output" line is the whole trick. It forces the file to stay a policy, not a wish list. Every rule has to earn its line by changing behavior.

Watch for contradictions, too. Borrowed dumps often carry rules that quietly fight each other: one section says "prefer named exports," another pasted block says "default-export every component." When the agent hits a conflict, it picks one more or less at random, and you get inconsistent code that technically follows the rules. A generated file derived from one source of facts doesn't have this problem, because the conventions came from the same place. If you must merge two reference files, read them for conflicts first. The agent won't flag the contradiction. It'll just pick a side per file and leave you wondering why the codebase drifted.

How the Rules File Reads Across the Stack

A generated .cursorrules file holds up because it's derived, not borrowed. The verification block in particular changes how reliably the agent finishes a task.

The verification block is the one to never omit. Without it, the agent's idea of "done" is "the code looks plausible." With it, "done" means the test command ran. That single section is the difference between a rules file that improves quality and one that just sets a vibe.

Variables You'll Set

Getting Started

1. Write down your real stack: language, framework, versions, tooling.
2. List the conventions reviewers enforce, one rule each.
3. List the patterns the agent must never produce.
4. Run the authoring prompt to generate a focused file under 200 lines.
5. Add the verification block: test command, lint, scope check.
6. Drop the file in at the repo root and watch a real task run against it.
7. For a policy-grade rules body, start with the Code Review Policy System Prompt.

A .cursorrules file sets the standard; a review pass checks the agent met it. The Code Review Policy System Prompt shares the same DNA as a good rules file, a focused policy with a verification step, which is why the two compose well: the rules guide the writing, the policy grades the result.

A .cursorrules file works when it's short, derived from your real stack, and ends with a step that checks the agent's work. Borrowed dumps do the opposite. For the larger config that agents outside Cursor read, see how to write an AGENTS.md file with AI. And when a single rules file isn't enough because the repo holds many packages, Cursor rules for large monorepos covers scoping rules per package.