The Cursor Rules File I Wish I Had on Day One

Cursor is good out of the box. But out of the box means it knows nothing about you, your stack, your patterns, or how you like code written. It's just guessing.

A .cursorrules file fixes that. It's a plain text file that sits in your project root and gives Cursor persistent context. Every conversation, every suggestion, every inline edit, it starts from that foundation instead of from zero.

I didn't set one up properly until a few months in. That was a mistake. Here's what I know now.

What the File Actually Does

Think of it as a system prompt that loads automatically every time you open the project. You're not re-explaining your stack on every prompt. You're not correcting the same wrong patterns over and over. You write it once, and it carries.

Cursor reads the file at the start of each session. It shapes how the model interprets your requests, what it suggests, and how it structures code before you've typed a single word.

Without it, you're training from scratch every chat. With it, you're extending a baseline that already knows your project.

The Sections That Actually Matter

A lot of people dump everything into this file and end up with 800 lines of noise. Keep it lean. These are the sections I actually use.

Stack and Environment

Start with the basics. What are you running? What version? What doesn't exist in this project?

Stack: Next.js 14 (App Router), TypeScript, Tailwind, Supabase
No Redux. No class components. No barrel files.

That last line matters as much as the first. Telling Cursor what you're NOT using stops it from reaching for patterns that don't fit.

Code Style Preferences

Be specific here. Vague rules produce vague results.

- Prefer named exports over default exports
- Always use async/await, never .then chains
- Keep components under 150 lines, extract if larger
- Use early returns instead of nested conditionals

These are the things you'd tell a new hire on day one. Write them down.

File Structure

If you have a naming convention or folder structure, document it. Cursor will follow it when generating new files.

- Components live in /components/{feature}/
- Hooks go in /hooks/ with use prefix
- Server actions in /actions/ with action suffix
- Types in /types/ as .types.ts files

What Not to Touch

This one gets skipped constantly and it's a pain when it's missing. Flag the files or patterns Cursor should leave alone.

Do not modify:
- /lib/db.ts (production schema, locked)
- Any file ending in .generated.ts
- The auth middleware in /middleware.ts

One wrong AI edit to a file like that and you're spending an hour tracing a bug that didn't exist before.

Project Context

A short paragraph on what the project actually does. Not for SEO. For the model.

This is a B2B SaaS dashboard for HVAC companies. 
Users manage service tickets, technician schedules, and invoices. 
Multi-tenant. Each company has isolated data. Performance is priority over elegance.

When Cursor knows what you're building, suggestions fit the domain. It stops recommending patterns that make sense generically but not for your actual product.

Common Mistakes

A few things I see people do that undercut the whole file.

Making it too long. If your rules file is longer than 200 lines, you've probably buried the important stuff in noise. Cursor reads it but doesn't weight everything equally. Keep signal high.

Writing vague rules. "Write clean code" does nothing. "Functions should do one thing and be named as verbs" does something. Specific beats general every time.

Never updating it. Your stack changes. Your patterns evolve. Review the file when you start a new phase of the project. A stale rules file is almost as bad as none.

Treating it like documentation. It's not a README. It's a prompt. Write it like you're instructing someone, not explaining to them.

How to Build Yours Without Starting From Scratch

Open a chat with Claude or ChatGPT. Paste in your package.json, a sample component, and a sample API route. Then say:

"Based on this code, write a .cursorrules file that captures my stack, coding style, and structure. Keep it under 150 lines. Format it for readability."

You'll get a solid first draft in 30 seconds. Then edit it. Remove what doesn't fit. Add the things it missed. Commit it to your repo so it travels with the project.

Takes about 15 minutes to set up something that pays back on every single session after.

One More Thing on Context

The rules file is static. It's good for baseline context. But it doesn't help with dynamic context, what you're working on right now, what decisions you made yesterday, what's temporarily off limits.

That's where you supplement with inline context in your prompts. The rules file sets the floor. Your prompts build on top of it.

A tight rules file plus disciplined prompting is a different tool than either one alone. Cursor starts acting like a collaborator who actually knows the codebase, not just a fast typist.

The premium section above has the full annotated template we actually use, including the rotating sprint context block that most people miss. That's inside Inner Circle, along with the rest of our build tooling breakdowns.