The .cursorrules 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.

A Copy-Paste Starter Template

If you want a starting point instead of a blank file, here is a lean .cursorrules template you can drop into your project root today. Replace the bracketed parts and delete anything that does not apply.

# Stack
Stack: [Next.js 14 App Router / your framework], TypeScript, [Tailwind / your styling]
Database: [Postgres + Prisma / your DB]
Node version: [22.x]
Do NOT suggest: [Pages Router, CSS-in-JS, class components, or anything you have banned]

# Conventions
- File naming: [kebab-case files, PascalCase components]
- Prefer server components; mark client components explicitly
- All API input validated with [Zod]
- Error handling: [return typed results, never throw across API boundaries]

# Style
- No comments that restate the code
- Match existing patterns in the file being edited before inventing new ones
- Keep functions small; extract when a block needs a comment to explain itself

# Project context
[Two or three sentences on what the product is and who uses it.]
[Anything the model keeps getting wrong goes here.]

Keep it under 100 lines. The moment the file becomes a wiki, Cursor starts ignoring the parts that matter.

Common Questions

Where does the .cursorrules file go?

In your project root, next to your package.json. Cursor picks it up automatically, no configuration needed.

Is .cursorrules deprecated in favor of .cursor/rules?

Newer Cursor versions support a .cursor/rules directory with multiple scoped rule files (.mdc), and that is the direction the product is heading. A single .cursorrules file still works and is still the simplest setup for solo builders. If your project grows to the point where different folders need different rules, migrate to the directory format.

Should I commit it to git?

Yes. It documents your conventions for humans too, and anyone who clones the repo gets the same AI behavior you tuned. Treat it like config, not like a personal dotfile.

How is it different from a system prompt?

Functionally it plays the same role, but it is scoped to the project and loads automatically. You write it once and every session starts from it instead of from zero.

.cursorrules vs CLAUDE.md vs AGENTS.md: which rules file do you need?

All three solve the same problem: giving your AI coding tool standing instructions so you stop repeating yourself. The difference is which tool reads them.

.cursorrules is read by Cursor. It lives at the repo root and applies to every AI request in that project. Cursor has also introduced the .cursor/rules directory format for scoped rules files, but a root .cursorrules file still works and is the simplest starting point.

CLAUDE.md is read by Claude Code. Same idea: project context, conventions, and commands at the repo root. It supports imports and a home-directory version for personal defaults.

AGENTS.md is an emerging cross-tool convention supported by Codex and a growing list of agents, meant to be one rules file every tool can read.

In practice: if your team uses more than one tool, keep the real content in one file and have the others reference it. The template earlier in this post works in any of the three formats; only the filename changes.