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

.cursorrules is a project-level instruction file that Cursor reads automatically every time you open a chat or use Composer in that project. Think of it as a system prompt that runs before every single conversation — except you write it once and forget it. Without it, Cursor treats every project the same. It doesn't know you're using Tailwind instead of CSS modules, that your team hates semicolons, or that you always use Zod for validation. With it, every suggestion is pre-filtered through your preferences. Here's what actually happens under the hood: when you open Cursor Chat or Composer in a project that has a .cursorrules file, Cursor prepends the contents of that file to the system context before sending your message to the model. This means the AI sees your rules before it sees your question. The model then weighs your instructions when generating a response. The practical payoff is real. Developers who use .cursorrules report spending 30–40% less time editing AI suggestions because the output already matches their stack and style. One freelancer on Reddit shared that after adding a 47-line .cursorrules file to his SaaS project, he stopped getting suggestions that used the Pages Router when he was on App Router — a change that saved him 10–15 minutes of re-prompting per session. The file lives in your project root directory alongside your package.json or README. It's just a text file with no special formatting required — though structure helps.

There's no official schema for .cursorrules, but through trial and error the community has landed on a structure that actually works. Here's what a solid file includes: **1. Tech Stack Declaration** List every major technology you're using. Be specific. Don't say 'React' — say 'React 18 with Next.js 14 App Router, TypeScript 5, Tailwind CSS 3.4, Shadcn/ui components.' The more specific you are, the less the model has to guess. **2. Code Style Rules** This is where you kill the back-and-forth. Examples of what to include: - 'Use arrow functions for all components' - 'No semicolons' - 'Single quotes only' - 'Always use const, never let or var' - 'Max line length 100 characters' - 'Use named exports, never default exports' **3. File and Folder Conventions** Tell Cursor how your project is organized: - 'Components live in /src/components/[ComponentName]/index.tsx' - 'API routes follow /app/api/[resource]/route.ts pattern' - 'All hooks are in /src/hooks and prefixed with use' **4. Libraries and Preferred Patterns** Cursor will often suggest multiple valid approaches. Narrow it down: - 'Use React Query for all data fetching, never useEffect for API calls' - 'Use Zod for all input validation' - 'Use next/image for all images, never raw img tags' - 'State management is Zustand, not Redux' **5. Things to Never Do** Negative instructions are underrated. A short 'never do X' list prevents a whole category of bad suggestions: - 'Never use any as a TypeScript type' - 'Never write inline styles' - 'Never use console.log in production code — use the custom logger at /src/lib/logger.ts' **6. Persona or Tone (Optional)** If you want Cursor to explain code a certain way in comments or communicate in a specific style: 'Write comments for a junior developer audience. Keep explanations short and practical.'

Here's a production-ready example for a Next.js SaaS project. Copy it, edit the specifics, and drop it in your root: --- You are an expert full-stack developer working on a Next.js 14 SaaS application. TECH STACK: - Next.js 14 with App Router (not Pages Router) - TypeScript 5 (strict mode enabled) - Tailwind CSS 3.4 with Shadcn/ui - Prisma ORM with PostgreSQL - NextAuth.js v5 for authentication - React Query (TanStack Query v5) for data fetching - Zod for all validation schemas - Zustand for client state - Resend for transactional email CODE STYLE: - Single quotes, no semicolons - Arrow functions for all components and utilities - Named exports only — never default exports - Explicit return types on all functions - No 'any' types — use 'unknown' and narrow types properly - Max 80 chars per line FILE STRUCTURE: - Components: /src/components/[ComponentName]/index.tsx - Server actions: /src/actions/[resource].ts - API routes: /app/api/[resource]/route.ts - Utilities: /src/lib/[utility].ts - Hooks: /src/hooks/use[HookName].ts - Types: /src/types/[domain].ts PATTERNS TO FOLLOW: - Use Server Components by default, add 'use client' only when needed - Use Server Actions for all form mutations - Fetch data in Server Components, not in client components with useEffect - All database queries go through Prisma — no raw SQL - All env variables validated at startup with Zod in /src/lib/env.ts NEVER DO: - Never use the Pages Router or getServerSideProps - Never use default exports - Never use inline styles - Never use console.log — use the logger at /src/lib/logger.ts - Never write Prisma queries directly in components - Never store sensitive data in client-side state When suggesting code, match existing patterns in the codebase. If you're unsure about a convention, ask before generating. --- This file is 47 lines. It takes 20 minutes to write once and saves hours of re-prompting across weeks of development.

People write .cursorrules files and then complain they don't work. Usually it's one of these problems: **Mistake 1: Being Too Vague** 'Write clean code' means nothing to a model. 'Use early returns to avoid nested conditionals' means something. Treat your rules like you're writing a style guide for a new hire who doesn't share your assumptions. **Mistake 2: Contradicting Yourself** If your rules say 'use functional components' and also 'use class components for complex state,' Cursor will pick one or average them out. Audit your file for contradictions before saving. **Mistake 3: Making the File Too Long** There's a real cost to context length. A 500-line .cursorrules file eats into the context window that should be used for your actual code and question. Keep it under 100 lines. If you have project-specific docs, link to them or summarize the key points. **Mistake 4: Forgetting to Update It** Your stack changes. You adopted a new library. You ditched Redux for Zustand. If your .cursorrules file describes a project you had six months ago, it's actively making things worse. Treat it like a living document — update it when you add a major dependency or change a core convention. **Mistake 5: Not Testing It** After writing your file, ask Cursor to 'write a new component for a user profile card.' Check if the output uses your imports, your styling system, your export convention. If it doesn't, your rules aren't landing — debug by simplifying the file and adding rules back one section at a time. **Mistake 6: Using .cursorrules for One-Off Instructions** The file is for persistent, project-wide rules. If you have a specific one-time request ('write this function in a functional style instead of OOP'), just say it in the chat. Don't bloat your rules file with things that only apply once.

Once you have the basics working, here's how to go further: **Use Multiple Projects, Multiple Files** You can have completely different .cursorrules for each project. Your React Native mobile app has different rules than your Express API. This is one of the most underused features — freelancers and agencies should have a template .cursorrules per client or per stack, then customize from there. Build a personal library of 4–5 starting templates. **Include Business Context** For freelancers and solopreneurs, adding a short business context section is surprisingly useful: 'This is a B2B SaaS for restaurant managers. Users are not technical. Prioritize simplicity over elegance. Features ship over perfect architecture.' This shapes not just syntax but the AI's overall approach to problem-solving. **Reference Your Own Utilities** If you have custom utilities, hooks, or wrappers, mention them explicitly: 'For toast notifications, always use the custom useToast hook at /src/hooks/useToast.ts, never install another library.' This prevents Cursor from suggesting you install react-hot-toast when you already have a wrapper. **Add Security Rules** For any project handling user data: 'Always sanitize user input before database operations. Never expose Prisma models directly in API responses — use DTO transform functions. Never log user PII including email addresses.' These are easy to forget in the flow of coding and great to automate. **Version Control It** Commit your .cursorrules to Git. When you onboard a collaborator, they get your AI configuration automatically. It's like committing your .eslintrc — it's part of the project's standards. **Combine with Cursor's Global Rules** Cursor also has global AI rules in Settings > AI > Rules for AI. These apply to every project. Use global rules for universal preferences ('always write unit test suggestions when creating new functions') and .cursorrules for project-specific stuff. Layer them intentionally.

You don't have to write your file from scratch. The community has built a real resource base: **cursor.directory** — A curated database of .cursorrules files organized by tech stack. You can filter by framework, language, and project type. Searching 'Next.js TypeScript' returns a dozen real-world examples with different opinions on conventions. It's the fastest starting point. **GitHub Search** — Search GitHub for filename:.cursorrules to find real files in public repos. This shows you what working developers are actually using, not just what's theoretically good. **The Cursor Discord** — The #rules channel has active discussions and people sharing what's working. Good for finding rules for newer frameworks that cursor.directory hasn't indexed yet. When you grab a template, don't use it as-is. Read every line and edit it to match your actual project. A template is a starting structure — it will have conventions that don't match yours and will be missing things that are specific to your work. Budget 20–30 minutes to customize any template before you rely on it.