What's actually in a good .cursorrules file? I built 10 of them — here's what I learned

Ahmed Mustafa — Mon, 25 May 2026 16:45:35 +0000

description: Most .cursorrules files are either too vague to help or too rigid to be useful. Here's what I found actually works after building rules for 10 different stacks.
tags: cursor,ai,webdev,productivity

I've spent a lot of time reading other people's .cursorrules files. Some are fantastic. Most are not.

Not because the authors didn't try — but because there's a gap between what feels like a good instruction and what actually changes how Cursor behaves. After building 10 rules files from scratch for different stacks, I want to share what I learned.

What is a .cursorrules file, and why does it matter?

If you haven't used one yet: a .cursorrules file sits in your project root and gives Cursor a set of persistent instructions. Every time the AI generates code, it uses these rules as context.

Think of it as a briefing document. Instead of re-explaining your preferences on every prompt — "use TypeScript strict mode," "don't use default exports," "we use Tailwind, not plain CSS" — you write them once and they apply automatically.

Done well, it means Cursor generates code that fits your project from the first suggestion. Done poorly, it either does nothing or actively gets in the way.

What bad rules look like

Here's a real example of the kind of rule that shows up a lot:

Always write clean, readable, maintainable code.
Follow best practices.
Use meaningful variable names.

This is useless. Not wrong — just useless. "Write clean code" is not an instruction. Cursor already tries to write clean code. You haven't told it anything it didn't already know.

A slightly better but still weak version:

Use TypeScript.
Add comments to complex functions.
Prefer async/await over callbacks.

These are real preferences, but they're still too generic. Every modern TypeScript project uses async/await. Saying it here adds no signal.

The problem with both examples is that they're stack-agnostic. They would apply equally to any project, so they don't actually help Cursor understand your project.

What good rules look like

Good rules are specific to the stack and specific to the project's conventions. Here's a before/after for a Next.js project:

Weak:

Use Next.js best practices.
Structure components properly.
Handle errors appropriately.

Strong:

This project uses Next.js 14 with the App Router. All components in /app are Server Components by default.
Only add 'use client' when the component requires interactivity (event handlers, useState, useEffect).
Do not use getServerSideProps or getStaticProps — those are Pages Router patterns.
Data fetching happens in Server Components using async/await directly. Never fetch in useEffect for initial data loads.

Notice the difference. The second version tells Cursor something it wouldn't otherwise know: that this is App Router, not Pages Router, and what the rules of that environment are. It also explicitly flags a common mistake — the Pages Router data-fetching patterns — because that's exactly the kind of thing AI models get wrong with App Router projects.

Here's another example, this time for FastAPI:

Weak:

Follow FastAPI conventions.
Use Pydantic for validation.

Strong:

This project uses FastAPI with Pydantic v2. Use model_validator and field_validator (not @validator, which is Pydantic v1).
Response models use model_config = ConfigDict(from_attributes=True), not class Config.
All database access goes through SQLAlchemy async sessions. Never use synchronous session patterns.
Route functions should be async. Dependencies go in Depends(), not imported directly into route functions.

The weak version would have Cursor defaulting to Pydantic v1 syntax half the time — because that's what's most common in its training data. The strong version explicitly says "Pydantic v2" and names the specific patterns that differ, so Cursor uses the right ones.

Three things that make rules effective

After writing rules for 10 stacks, I found a few patterns that consistently made a difference:

1. Name the version, not just the tool

"Use React" is fine. "Use React 18 with concurrent features where appropriate" is better. Version specificity matters because AI models have seen a lot of different version patterns and will default to the most common one, which may not be current.

2. Explain what to avoid, not just what to do

It's often more useful to say "do not use X" than "use Y." When Cursor knows what the wrong path looks like, it avoids generating the plausible-but-wrong code that you'd otherwise have to catch and fix. For Go projects, for example, specifying "do not use global variables for state; use dependency injection" catches a common pattern that works at small scale but creates problems in production.

3. Describe your project structure

If your project has non-obvious structure — a monorepo, a specific folder layout, a separation between domain and infrastructure layers — put it in the rules. Cursor uses the file tree as context, but a brief description of what lives where and why helps it make better decisions about where to put new code.

What to avoid in rules files

Keep them focused. A .cursorrules file that's 500 lines long is a problem — it dilutes the important instructions with noise. If everything is emphasized, nothing is.

Avoid instructions that are just philosophy: "Think carefully before writing code." "Consider edge cases." These do not change behavior.

And avoid contradictions. If you say "always add JSDoc comments" and also "keep code concise," you'll get inconsistent results because those goals conflict.

The payoff

When your rules file is doing its job, you stop noticing it — in a good way. Cursor just generates code that fits. You're not correcting the same mistakes repeatedly. You're not re-explaining your conventions every session. The suggestions match what you'd actually write.

That compounding effect is real. Over a day of coding it's maybe a few frustrations avoided and a few minutes saved. Over a month it's meaningful.

After going through this process for 10 different stacks — Next.js, React, FastAPI, Django, Node.js, Go, Vue 3, Svelte, React Native, and Full-Stack SaaS — I packaged the resulting rules files into a single pack if you want a starting point rather than building from scratch. Each file reflects the stack-specific conventions and gotchas I've described here, not just generic advice.

You can find the pack here: Stackdrop Cursor Rules Pack

What rules have you found actually make a difference in your .cursorrules files? Curious what others have figured out — especially for stacks I haven't covered. Drop your best rules in the comments.