The Complete .cursorrules Setup Guide: From Zero to Pro

.cursorrules is a plain text file you drop into your project root that tells Cursor's AI how to behave -- what coding style to follow, which frameworks you're using, what patterns to avoid. Think of it as a project-specific system prompt that gets injected into every AI interaction.

If you've spent any time on the Cursor Forum, you've seen the same question pop up weekly: "How do I set up .cursorrules properly?" The official docs cover the basics, but there's a lot of nuance that only comes from actually using it day to day. This guide distills what the community has figured out so far.

Three Types of Rules: Which One Do You Need?

This is the #1 source of confusion on the forum. Cursor actually has three different rule mechanisms, and they serve different purposes. Here's the breakdown:

Rules for AI (Global)

Found at Settings > General > Rules for AI. These are global rules that apply to every project you open in Cursor. They live in your local settings, not in any project directory.

Good for:

• Personal preferences ("always use TypeScript strict mode")
• Universal conventions you follow across all projects
• Model behavior tweaks ("respond concisely, no explanations unless asked")

Rules for AI (Global)

Always use functional components with TypeScript.
Prefer named exports over default exports.
When fixing bugs, explain the root cause briefly before showing the fix.

.cursorrules (Project-Level)

A file named .cursorrules placed in your project root directory. This is the classic approach -- one file, plain text or markdown, that describes how AI should work within this specific project.

Good for:

• Project-specific tech stack and conventions
• Team-shared rules (commit it to git)
• Framework-specific patterns (Next.js, Django, Rails, etc.)

.mdc Rules (Modern, Scoped)

The newer format. You place .mdc files inside the .cursor/rules/ directory. Each file can be scoped to specific file patterns, and you can toggle individual rules on/off from the UI.

Good for:

• Fine-grained control over when rules apply
• Large projects where different directories have different conventions
• Teams that want to selectively enable/disable rules

Project structure with .mdc rules

.cursor/
  rules/
    react-components.mdc
    api-endpoints.mdc
    database.mdc
    testing.mdc

Comparison Table

Feature	Rules for AI	.cursorrules	.mdc Rules
Scope	Global (all projects)	Single project	Single project
Location	Cursor settings	Project root	.cursor/rules/
File pattern	N/A	N/A	Per-rule scoping
Toggle in UI	Yes	No	Yes
Share via git	No	Yes	Yes
Multiple files	No	No (single file)	Yes
Status	Stable	Stable (legacy)	Recommended

تلميح

You can use all three at the same time. Rules for AI sets your personal baseline, .cursorrules or .mdc files handle project specifics. When they conflict, project-level rules take precedence.

Writing an Effective .cursorrules File

Most tutorials tell you to write your .cursorrules in markdown. That works, but forum user razbakov made a strong case for using structured JSON instead. The reasoning: LLMs parse structured data more reliably than prose, so your rules get followed more consistently.

Here's a real .cursorrules file for a Next.js + TypeScript project using the JSON approach:

.cursorrules

{
  "project": {
    "name": "My SaaS App",
    "stack": ["Next.js 14", "TypeScript", "Tailwind CSS", "Prisma"],
    "packageManager": "pnpm"
  },
  "conventions": {
    "naming": {
      "components": "PascalCase",
      "functions": "camelCase",
      "files": "kebab-case",
      "constants": "SCREAMING_SNAKE_CASE"
    },
    "imports": {
      "order": ["react", "next", "lib/*", "components/*", "relative paths"],
      "noCircularImports": true,
      "alias": "@/ for src/"
    },
    "components": {
      "preferFunctional": true,
      "folderByFeature": true,
      "colocateStyles": true
    }
  },
  "rules": [
    "Always define TypeScript interfaces for component props",
    "Use 'use client' directive only when component needs interactivity or hooks",
    "Prefer server components by default in Next.js app router",
    "No default exports -- use named exports for everything",
    "API routes go in app/api/ following REST conventions",
    "Database queries use Prisma client from lib/db.ts only",
    "Error handling: use try/catch with proper error types, never swallow errors",
    "Environment variables must be validated with zod in env.ts"
  ],
  "antiPatterns": [
    "Never use 'any' type -- use 'unknown' and narrow with type guards",
    "Never put business logic in page.tsx files",
    "Never use inline styles -- use Tailwind classes or CSS modules",
    "Never import from relative paths like '../../' -- use @/ alias"
  ]
}

Why This Works Better Than Plain Text

When you write rules as natural language paragraphs, the AI has to interpret what you mean. With structured JSON:

• Each rule is a discrete, unambiguous instruction
• The AI doesn't have to guess which parts are rules vs. context
• You can organize by category, making it easier to maintain
• Adding or removing rules doesn't break the format

Note: If you prefer markdown, that's fine too. The key insight is structure over prose. Even in markdown, use bullet points and clear headings rather than long paragraphs.

A Markdown Alternative

If JSON feels too rigid, here's a well-structured markdown version that still avoids the "wall of text" problem:

.cursorrules (Markdown version)

# Project Rules

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM

## Naming
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- Files: kebab-case (user-profile.tsx)

## Hard Rules
- Always use named exports
- Every component needs TypeScript prop types
- Server components by default, add 'use client' only when necessary
- No `any` type, ever
- All env vars validated with zod

## File Structure
- Components in src/components/[feature]/
- Hooks in src/hooks/
- API utils in src/lib/
- Types in src/types/

Let AI Write Your .cursorrules for You

Here's a trick from forum user tomredman that's genuinely useful: instead of writing rules from scratch, use Cursor's Agent mode to analyze your codebase and generate them automatically.

The Method

1. Open Cursor's chat panel
2. Switch to Agent mode
3. Give it this prompt:

Analyze this codebase and generate a comprehensive .cursorrules file.
Look at:
- Existing files and directory structure
- Package.json dependencies
- Config files (tsconfig, eslint, prettier, etc.)
- Existing code patterns and conventions

Output a .cursorrules file that captures the actual conventions
already used in this project. Use JSON format with clear categories
for tech stack, naming conventions, coding rules, and anti-patterns.

4. Review the output carefully -- the AI will catch patterns you didn't even realize you were following
5. Edit the generated file to remove anything inaccurate and add anything it missed
6. Save it to your project root as .cursorrules

معلومات

This works best on projects that have been around for a while with consistent patterns. For brand new projects, you're better off writing rules manually or starting from a template.

Iterating on Generated Rules

Don't expect a perfect result on the first try. Here's my workflow:

1. Generate with Agent mode
2. Test it by asking Cursor to write a new component -- does it follow the rules?
3. Note where it deviates and add explicit rules for those cases
4. Repeat for a few iterations until the output is consistently correct

The whole process takes about 15-20 minutes and saves hours of "fix that, no not like that" back-and-forth later.

Community Resources

You don't have to start from scratch. The community has built several rule libraries worth browsing:

cursor.directory

cursor.directory is a curated collection of .cursorrules files organized by framework and language. It's the most popular resource on the forum for finding starter rules.

cursorrules.agnt.one

cursorrules.agnt.one focuses on agent-specific rules. If you're heavy on Agent mode, this is worth checking out.

GitHub Collections

Search GitHub for .cursorrules and you'll find thousands of real-world examples:

GitHub search query

filename:.cursorrules stars:>5

Filter by language or framework to find rules from projects similar to yours.

Forum Thread: Share Your .cursorrules

There's a pinned thread on the Cursor Forum called "Share your .cursorrules" where users post their configurations with explanations. It's gold for seeing what works in production.

warning

Never copy a .cursorrules file verbatim into your project. Always adapt it to your actual stack and conventions. A React Native rules file will cause more harm than good in a Django project.

Common Pitfalls

After reading through dozens of forum threads, these are the problems that come up most often:

1. Rules Too Long = Worse Performance

There's a persistent myth that more rules = better AI behavior. It's the opposite. Cursor injects your rules into the context window alongside your code and the conversation. Longer rules mean less room for actual code context.

Keep it under 2000 characters if possible. If you're pushing 5000+, you need to cut ruthlessly.

Bad: Too verbose

When you are writing React components in this project, you should always make sure
to use functional components instead of class components, and you should define
your prop types using TypeScript interfaces rather than PropTypes, and you should...

Good: Concise and direct

- Use functional React components only
- TypeScript interfaces for all props
- Named exports, no defaults

2. Conflicting Rules

When you have Rules for AI set globally AND a .cursorrules file in your project, conflicts are inevitable. For example:

• Global rule: "Use 2-space indentation"
• Project rule: "Use 4-space indentation"

Cursor resolves this by giving project-level rules higher priority, but the AI can still get confused when both are present. The fix: keep global rules minimal and generic, put specifics in project files.

3. Rules That Tell the AI What It Already Knows

Don't waste your rule budget on things the model already does well:

Unnecessary rules to avoid

- Write clean, readable code          # The model does this by default
- Follow best practices               # Too vague to be useful
- Use proper error handling          # Already default behavior
- Comment your code                  # Often unnecessary noise

Instead, focus on what makes your project different from the model's defaults:

Rules that actually add value

- Use Zod schemas for all API input validation
- All database queries go through the repository pattern
- GraphQL resolvers must have @authenticated directive
- Use pnpm workspaces for monorepo package management

4. Forgetting to Commit .cursorrules

If you're on a team and the .cursorrules file isn't in version control, you're the only one benefiting from it. Add it to git and make it part of your onboarding process.

Add .cursorrules to git

git add .cursorrules
git commit -m "Add project AI rules for Cursor"

Note: Some teams prefer to keep .cursorrules out of git if different developers have different preferences. In that case, use .cursorrules.example as a template and add .cursorrules to .gitignore.

5. Not Testing Your Rules

Write your rules, then immediately test them. Ask Cursor to:

• Generate a new component
• Refactor an existing function
• Fix a bug

If the output doesn't match your expectations, your rules need adjustment. Don't wait until you're deep in a feature to discover your rules aren't working.

Quick Start Checklist

If you're setting up .cursorrules for the first time, here's the minimal path:

• Decide between .cursorrules (single file) or .mdc (multiple files)
• Use Agent mode to analyze your codebase and generate a first draft
• Trim it down to under 2000 characters
• Focus on project-specific rules, not generic advice
• Test by having Cursor generate a component or function
• Iterate until output is consistent
• Commit to version control
• Share with your team

Related Articles

• Best Practices for .cursor/rules
• MDC Rules Best Practices
• Using Cursor Rules Effectively
• How to Ignore Sensitive Files in Cursor