The Complete .cursorrules Guide: Make Cursor Do Exactly What You Want

Cursor is built on top of large language models — Claude, GPT-4o, and others depending on your plan. By default, these models have no idea you're building a Next.js 14 app with TypeScript strict mode, that you hate semicolons, or that you always use Zustand instead of Redux. Every chat session starts cold. .cursorrules is a project-level configuration file that injects persistent instructions into every AI interaction inside that project. The moment Cursor opens your project, it reads this file and uses it as background context. You write it once, and it shapes every autocomplete suggestion, every chat response, and every code generation for as long as you work in that folder. Here's a concrete example of why this matters: without .cursorrules, if you ask Cursor to add authentication, it might scaffold a basic username/password system. With a .cursorrules file that says 'This project uses Clerk for authentication — never suggest custom auth implementations,' you get Clerk-specific code every time, no back-and-forth needed. The file lives at the root of your project: /your-project/.cursorrules. It's plain text. No special syntax required, though some people write it in markdown-style with headers for organization.

A good .cursorrules file has five distinct components. Skip any of them and you'll leave value on the table. **1. Project Identity (2-4 sentences)** Tell Cursor what you're building, the tech stack, and the stage of development. Example: 'This is a SaaS dashboard for freelance designers built with Next.js 14 App Router, TypeScript, Tailwind CSS, and Supabase. We are in active development — MVP not yet launched.' **2. Technology Constraints** Be explicit about what's in and what's out. This is where most people underinvest. Don't just list your stack — also list what you're NOT using and why. Example: - State management: Zustand only. Never suggest Redux, Context API for global state, or Jotai. - Styling: Tailwind CSS only. Never write custom CSS files or use inline styles except for dynamic values. - Data fetching: TanStack Query v5. Never use SWR or raw useEffect for data fetching. - Database access: Supabase client only. Never use raw SQL or Prisma. **3. Code Style Preferences** This section saves you from style-related edit cycles. Include: - TypeScript strictness (always define return types? avoid 'any'?) - Function style (arrow functions vs. named functions) - File naming conventions (kebab-case, PascalCase for components) - Comment style (JSDoc? inline only? no comments at all?) - Error handling approach (try/catch everywhere? Result types?) Example: 'Always use named exports. Never use default exports except for Next.js page files where required. Use TypeScript interfaces over types for objects. Always handle errors explicitly — no silent failures.' **4. Architecture Rules** Help Cursor understand your folder structure and where things live. Example: - Components go in /components, organized by feature - Server actions go in /app/actions - Utility functions go in /lib - All API calls go through /services, never directly in components - Custom hooks go in /hooks **5. Behavioral Instructions** This is where you control how Cursor communicates with you, not just what code it writes. Example: - When suggesting a solution with tradeoffs, list them explicitly - Always explain WHY you're suggesting an approach, not just HOW - If you're unsure about something, say so rather than guessing - When writing a new component, always include TypeScript props interface first - Don't refactor code I haven't asked you to refactor

Here's a production-ready .cursorrules file for a Next.js SaaS project. This took about 45 minutes to write and has saved dozens of hours of correction over a 3-month project: --- You are an expert Next.js 14 developer working on a B2B SaaS project management tool called 'Stackplan.' The target users are small engineering teams (5-20 people). TECH STACK: - Framework: Next.js 14 with App Router (NOT Pages Router) - Language: TypeScript with strict mode enabled - Styling: Tailwind CSS + shadcn/ui components - Database: Supabase (PostgreSQL) - Auth: Clerk - State: Zustand for global state, TanStack Query v5 for server state - Payments: Stripe - Deployment: Vercel NEVER USE: - Redux or any other state management - Custom CSS files - Class components - useEffect for data fetching - Default exports (except Next.js page/layout files) - the 'any' TypeScript type CODE STYLE: - All functions should be arrow functions stored in const - All TypeScript interfaces should be prefixed with 'I' (e.g., IUser, IProject) - File names use kebab-case - Component names use PascalCase - Always add explicit return types to functions - Error boundaries should wrap each major feature section FOLDER STRUCTURE: /app — Next.js App Router pages and layouts /components/ui — shadcn/ui base components (don't modify these) /components/features — feature-specific components /components/shared — reusable components used across features /lib — utility functions and configurations /hooks — custom React hooks /services — all external API calls (Supabase, Stripe, etc.) /store — Zustand stores /types — shared TypeScript types and interfaces BEHAVIOR: - Always show me the complete file when editing, not just the changed section - When writing a new component, define the props interface before the component - If my request is ambiguous, ask one clarifying question before proceeding - Point out potential performance issues when you see them - If I ask for something that conflicts with these rules, tell me before implementing --- Notice what this file doesn't do: it doesn't try to explain your entire business logic. .cursorrules is for technical constraints and behavioral preferences, not product specifications. Keep product context in separate documentation files that you can @mention in chat when relevant.

**Mistake 1: Writing vague instructions** Bad: 'Write clean code.' Good: 'Functions should do one thing. No function longer than 40 lines. Extract logic into named helper functions with descriptive names.' Vague instructions get vague results. Cursor is not guessing what 'clean' means to you — it's using its training data's average definition, which may not match yours. **Mistake 2: Making the file too long** If your .cursorrules file is 500+ lines, Cursor may truncate it or weight recent instructions over earlier ones. The sweet spot is 100-250 lines. If you need more context, use Cursor's @ mentions to pull in specific documentation files on demand. **Mistake 3: Conflicting instructions** Example: 'Always use async/await' AND 'Use promise chains for readability.' Pick one. Conflicting rules confuse the model and produce inconsistent output. Before finalizing your file, read through it once specifically looking for contradictions. **Mistake 4: Never updating the file** Your project evolves. If you switched from Prisma to Drizzle in month two and never updated .cursorrules, Cursor is still suggesting Prisma code. Treat .cursorrules like a living document. Set a reminder to review it every 2-3 weeks on an active project. **Mistake 5: Using it as a documentation replacement** Some people try to put API schemas, database table structures, and business logic in .cursorrules. Don't. That's what separate .md files in a /docs folder are for — you can reference those in chat with @docs/schema.md when needed. Keep .cursorrules focused on coding behavior and technical constraints.

**Persona Stacking** You can tell Cursor to act as multiple experts simultaneously. Example: 'You are simultaneously a senior Next.js developer, a Tailwind CSS expert, and a web accessibility specialist. When writing UI components, consider all three perspectives. Always flag accessibility issues even if I haven't asked.' This works particularly well when your project spans multiple disciplines. **Conditional Instructions** You can write if/then logic in plain English: 'When I ask for a new API route, always: (1) check if it should be a server action instead, (2) add input validation with Zod, (3) add error handling, (4) suggest the corresponding client-side hook structure.' This creates a mini checklist that Cursor follows automatically. **Team .cursorrules** If you're working with others, commit .cursorrules to your repository. This means every team member and AI assistant interaction follows the same rules. It's one of the fastest ways to maintain code consistency on a team without code reviews becoming style debates. Add a comment at the top: '# Team coding standards — update via PR with team discussion.' **Per-Feature Overrides** Cursor also reads a .cursorrules file in subdirectories. If you have a /scripts folder with utility scripts that don't follow your main app's rules, drop a separate .cursorrules in that folder. It overrides the root-level file for that directory only. Useful for monorepos where different packages have different conventions. **Testing Mode Instructions** Add a specific section for test-related instructions: 'When writing tests: use Vitest, not Jest. Testing Library only — no Enzyme. Never use snapshot tests. Test behavior, not implementation. Name test files [component-name].test.tsx and place them next to the component file.' Without this, Cursor will mix testing frameworks and patterns unpredictably.

Writing your first .cursorrules from scratch can take 30-60 minutes. Here's how to shortcut it: **cursor.directory** — A community-maintained library of .cursorrules files organized by tech stack. Search for 'Next.js,' 'Python FastAPI,' 'React Native,' and hundreds of others. These are real files from real developers. Use them as a starting point, not a final answer — every project has unique requirements. **GitHub Search** — Search GitHub for 'filename:.cursorrules' and you'll find thousands of real project files. Filter by language or framework. Reading 5-10 files in your stack takes 20 minutes and teaches you patterns you wouldn't think to write yourself. **Cursor's own documentation** — Cursor publishes official guidance on .cursorrules at docs.cursor.com. Check this when Cursor gets updated, as new features sometimes change what's possible in the rules file. **Generate with AI** — Yes, use Claude or ChatGPT to write your initial .cursorrules. Give it your tech stack, a list of your preferences, and a sample of 50-100 lines of your existing code. Ask it to write a .cursorrules file. Then review and customize. You'll save 45 minutes and the AI catches categories of preferences you'd forget to include. **Honest caveat**: Community templates can be outdated. A .cursorrules for Next.js 13 (Pages Router) won't serve you well on Next.js 14 (App Router). Always check when a template was last updated and verify the conventions match your current framework version.

Most people write .cursorrules and assume it works. Verify it. **Test 1: The Stack Test** Open a new chat in Cursor. Ask: 'What tech stack are we using in this project?' Cursor should correctly list your stack from the rules file. If it doesn't, your file might have a syntax issue or be in the wrong location. **Test 2: The Violation Test** Ask Cursor to do something your rules explicitly forbid. Example: if your rules say 'never use useEffect for data fetching,' ask it to fetch some data. It should refuse or suggest TanStack Query instead. If it writes a useEffect, your constraint isn't clear enough — rewrite that section. **Test 3: The Style Test** Ask Cursor to write a simple utility function. Check that it follows your naming conventions, uses your preferred function style, and includes error handling as specified. If three out of five style rules are being followed, that's actually common — rewrite the rules that aren't landing with more specific examples. **Test 4: The Fresh Session Test** Close Cursor completely. Reopen it. Run tests 1-3 again. Sometimes rules that worked in an existing session don't persist. If results differ, there may be a caching issue — restarting Cursor usually fixes it. Expect about 80-90% adherence when your rules are well-written. The model isn't perfectly obedient — it's making probabilistic decisions. If you're getting below 70% adherence on your most important rules, those specific rules need to be rewritten more explicitly, possibly with examples.