Why Cursor Doesn't Follow Rules AI: Complete Troubleshooting Guide | Pro Cursor Rules

# ❌ Wrong locations where Cursor can't find rules
~/Documents/my-rules.cursor-rules
/random/folder/.cursorrules
project-folder/configs/cursor.rules

# ✅ Correct locations where Cursor looks for rules
project-root/.cursorrules
project-root/.cursor-rules
~/.cursorrules (global rules)

# ❌ Incorrect file names
.cursor_rules
cursor-rules.txt
cursorrules.md
.cursor-config

# ✅ Correct file names
.cursorrules
.cursor-rules

# ❌ Poor rule formatting that Cursor ignores
Use TypeScript
Make it work with React
Add some error handling

# ✅ Clear, actionable rule formatting
- Always use TypeScript for all new files
- Import React components using named imports: `import { ComponentName } from 'library'`
- Wrap all async operations in try-catch blocks with proper error logging
- Use interface declarations instead of type aliases for object shapes

# ❌ Vague rules without context
Write good code
Follow best practices
Make it clean

# ✅ Specific, contextual rules
- For React components: Always use functional components with TypeScript interfaces for props
- For API routes: Return consistent response objects with { data, error, message } structure
- For styling: Use Tailwind CSS classes, avoid inline styles, group related classes together
- For imports: Group imports in this order: React/Next.js, third-party libraries, local components, utilities

# ❌ Conflicting rules that confuse the AI
- Always use semicolons at the end of statements
- Never use semicolons, follow Prettier's defaults
- Use single quotes for strings
- Use double quotes for all strings
- Prefer arrow functions
- Always use function declarations

# ✅ Consistent, non-conflicting rules
- Use TypeScript strict mode settings
- Follow Prettier formatting: no semicolons, single quotes, trailing commas
- Prefer arrow functions for inline callbacks, function declarations for named functions
- Use const assertions for immutable data structures

# Check if rule file exists in correct location
ls -la .cursorrules
ls -la .cursor-rules
ls -la ~/.cursorrules

# Display rule file contents
cat .cursorrules

# Verify file permissions
ls -la .cursorrules | grep cursorrules

# ✅ Well-structured rule file template
# Project: [Your Project Name]
# Updated: [Date]

## Code Style
- Use TypeScript for all new files
- Follow ESLint configuration in .eslintrc.js
- Use Prettier for code formatting

## Component Patterns
- React components should use functional syntax with TypeScript
- Props interfaces should be defined above the component
- Use default exports for main components, named exports for utilities

## Import Organization
1. React and Next.js imports
2. Third-party library imports  
3. Local component imports
4. Utility and helper imports
5. Type-only imports last

## Error Handling
- Wrap all async operations in try-catch blocks
- Use custom error types defined in types/errors.ts
- Log errors using the logger utility from lib/logger.ts

## Testing
- Write unit tests for all utility functions
- Use React Testing Library for component tests
- Mock external dependencies in tests

# ❌ Rules that exceed context limits
[... 2000 lines of detailed rules ...]

# ✅ Concise, prioritized rules
## TOP PRIORITY RULES
1. Use TypeScript interfaces for all prop definitions
2. Implement error boundaries for all route components
3. Use Tailwind CSS for styling, avoid CSS modules

## SECONDARY RULES
[Additional, less critical rules...]

## REFERENCE PATTERNS
[Code examples and templates...]

// Test prompt: "Create a React component for user profile"
// Expected behavior based on rules:

// ✅ What you should see if rules are working:
interface UserProfileProps {
  user: {
    id: string
    name: string
    email: string
  }
  onEdit: () => void
}

export default function UserProfile({ user, onEdit }: UserProfileProps) {
  return (
    <div className="bg-white rounded-lg shadow-md p-6">
      <h2 className="text-xl font-semibold mb-4">{user.name}</h2>
      <p className="text-gray-600 mb-4">{user.email}</p>
      <button 
        onClick={onEdit}
        className="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2 rounded"
      >
        Edit Profile
      </button>
    </div>
  )
}

// ❌ What you might see if rules are being ignored:
function UserProfile(props) {
  return React.createElement('div', {style: {backgroundColor: 'white'}}, 
    React.createElement('h2', null, props.user.name)
  )
}

# Navigate to your project root
cd /path/to/your/project

# Create the rule file with correct name
touch .cursorrules

# Or alternative naming
touch .cursor-rules

# Make sure the file is visible
ls -la | grep cursor

# Check file permissions
chmod 644 .cursorrules

# Add this minimal test rule to .cursorrules
When creating React components, always use TypeScript interfaces for props.

I want you to write good React code that follows our team standards and makes sure everything works properly with TypeScript and includes proper error handling.

## React Component Standards

### Component Definition
- Use functional components with TypeScript
- Define props interface above component
- Use default export for main component

### Example Pattern:
```typescript
interface ComponentProps {
  title: string
  onClick: () => void
}

export default function Component({ title, onClick }: ComponentProps) {
  return (
    <button onClick={onClick} className="btn">
      {title}
    </button>
  )
}


### Solution 3: Optimize for Context Window

**Prioritized Rule Structure:**

```markdown
# CURSOR RULES - [Project Name]

## 🔥 CRITICAL RULES (Always Apply)
1. TypeScript for all new files (.ts/.tsx extensions)
2. Functional React components with interface props
3. Tailwind CSS for styling (no inline styles)

## 📋 COMPONENT PATTERNS
```typescript
// Standard component template
interface Props {
  // Define props here
}

export default function ComponentName({ prop }: Props) {
  // Component logic
  return <div className="tailwind-classes">{/* JSX */}</div>
}

import React from 'react'
import { NextPage } from 'next'
import { ComponentName } from '@/components'
import { utilityFunction } from '@/lib/utils'


### Solution 4: Test and Validate Rules

**Create a test workflow:**

```markdown
## Rule Testing Checklist

### Test 1: Component Creation
Prompt: "Create a user card component"
Expected: TypeScript interface, functional component, Tailwind classes

### Test 2: API Route
Prompt: "Create an API route for user data"
Expected: TypeScript, error handling, consistent response format

### Test 3: Form Handling
Prompt: "Create a contact form"
Expected: Form validation, error states, TypeScript types

### Test 4: Import Organization
Prompt: "Add imports for React, axios, and Button component"
Expected: Grouped imports in correct order

# Global Cursor Rules - Apply to all projects

## Universal Standards
- Use TypeScript when possible
- Prefer functional programming patterns
- Write descriptive variable names
- Include error handling for async operations

## Code Quality
- Add JSDoc comments for public functions
- Use const assertions for immutable data
- Prefer named exports for utilities

# Project-Specific Rules - Override global when needed

## This Project Uses
- Next.js App Router (not Pages Router)
- Shadcn/UI components (not custom CSS)
- Prisma for database operations
- BetterAuth for authentication

## Project Patterns
[Specific patterns that override global rules]

## Context-Aware Rules

### For React Components (.tsx files)
- Always use functional components
- Define TypeScript interfaces for props
- Use Tailwind for styling

### For API Routes (app/api/**/route.ts)
- Return NextResponse.json() objects
- Include try-catch error handling
- Validate request data with Zod schemas

### For Database Operations (lib/db/*.ts)
- Use Prisma client instance
- Handle connection errors gracefully
- Use transactions for multi-step operations

### For Utility Functions (lib/utils/*.ts)
- Export as named exports
- Include JSDoc documentation
- Add unit tests in adjacent .test.ts files

# Main Cursor Rules

## Project Overview
This is a Next.js e-commerce application with the following key areas:
- Authentication (uses BetterAuth)
- Product catalog (with search and filtering)
- Shopping cart and checkout
- Admin dashboard
- User profiles

## Core Standards
[Universal rules that apply everywhere]

## Feature-Specific Rules
When working on authentication features, follow auth-specific patterns.
When working on product features, use the catalog data structures.
When working on admin features, implement proper role-based access.

## Rule Compliance Checklist

### Daily Review Questions
- Are new components following the TypeScript interface pattern?
- Do API routes include proper error handling?
- Are imports organized according to the specified order?
- Is Tailwind being used instead of inline styles?

### Weekly Rule Audit
- Review recent commits for rule compliance
- Update rules based on new project requirements
- Remove or modify rules that are consistently ignored
- Add new rules for emerging patterns

## Rule Maintenance Schedule

### Monthly Tasks
- Review rule effectiveness
- Remove outdated rules
- Add rules for new technologies or patterns
- Test rules with common development scenarios

### Quarterly Tasks
- Major rule restructuring if needed
- Performance optimization of rule files
- Team review of rule compliance
- Documentation updates

# Include rule files in version control
git add .cursorrules
git commit -m "feat: update Cursor rules for new component patterns"

# Create team rule validation script
#!/bin/bash
# validate-cursor-rules.sh

echo "Validating Cursor rules..."

if [ ! -f .cursorrules ]; then
    echo "❌ Missing .cursorrules file"
    exit 1
fi

if [ ! -s .cursorrules ]; then
    echo "❌ Empty .cursorrules file"
    exit 1
fi

echo "✅ Cursor rules file validated"

// test-cursor-rules.js
const fs = require('fs')
const path = require('path')

function validateCursorRules() {
  const ruleFile = path.join(process.cwd(), '.cursorrules')
  
  if (!fs.existsSync(ruleFile)) {
    throw new Error('Missing .cursorrules file')
  }
  
  const rules = fs.readFileSync(ruleFile, 'utf8')
  
  // Check for common rule patterns
  const requiredPatterns = [
    'TypeScript',
    'interface',
    'component',
    'error handling'
  ]
  
  const missingPatterns = requiredPatterns.filter(pattern => 
    !rules.toLowerCase().includes(pattern.toLowerCase())
  )
  
  if (missingPatterns.length > 0) {
    console.warn(`⚠️ Missing rule patterns: ${missingPatterns.join(', ')}`)
  }
  
  console.log('✅ Cursor rules validation passed')
}

validateCursorRules()

# ❌ Over-specified rules
When creating a React component, make sure to use TypeScript with strict mode enabled, define interfaces for all props with proper JSDoc comments including @param tags for each property, use functional components with arrow function syntax unless you need component lifecycle methods in which case use class components but prefer hooks, implement proper error boundaries with componentDidCatch, use React.memo for performance optimization when props are stable, implement proper key props for list items, use useCallback and useMemo appropriately to prevent unnecessary re-renders...

# ✅ Right level of specification
- Use TypeScript functional components with interface props
- Implement error boundaries for route-level components
- Use React.memo, useCallback, useMemo for performance when needed

# ❌ Conflicting rules
- Always use arrow functions
- Prefer function declarations for components
- Use semicolons for consistency
- Follow Prettier settings (no semicolons)

# ✅ Consistent rules
- Use arrow functions for inline callbacks and utility functions
- Use function declarations for React components and main functions
- Follow Prettier configuration: no semicolons, single quotes, trailing commas

# ❌ Context-ignorant rules
[5000 words of detailed coding standards...]

# ✅ Context-aware rules
## PRIORITY 1 (Always Apply)
[3-5 most important rules]

## PRIORITY 2 (Apply When Relevant)
[Secondary rules]

## REFERENCE (Examples Only)
[Code examples and patterns]

## Rule Success Checklist

### ✅ Your rules are working well when:
- Cursor generates code in your preferred style consistently
- New team members' AI-generated code matches project standards
- Code reviews require fewer style-related comments
- Import statements are automatically organized correctly
- Error handling patterns are consistently applied

### ⚠️ Signs your rules need improvement:
- Inconsistent code generation across sessions
- AI ignores specific formatting preferences
- Generated code requires significant manual adjustment
- Team members report different AI behavior
- Rules are applied only sometimes

## Evolution-Ready Rule Structure

### Core Principles (Stable)
- Type safety with TypeScript
- Component-based architecture
- Error handling patterns
- Code organization standards

### Implementation Details (Flexible)
- Specific syntax preferences (may change with language updates)
- Tool-specific configurations (may change with new tools)
- Framework-specific patterns (may evolve with framework updates)

### Review Schedule
- Monthly: Check rule effectiveness
- Quarterly: Update for new tools/frameworks
- Annually: Major rule architecture review

#!/bin/sh
# .git/hooks/pre-commit

echo "Checking Cursor rule compliance..."

# Run rule validation
npm run validate-cursor-rules

if [ $? -ne 0 ]; then
    echo "❌ Cursor rules validation failed"
    exit 1
fi

echo "✅ Cursor rules validation passed"

# .github/workflows/cursor-rules.yml
name: Validate Cursor Rules

on: [push, pull_request]

jobs:
  validate-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate Cursor Rules
        run: |
          if [ ! -f .cursorrules ]; then
            echo "❌ Missing .cursorrules file"
            exit 1
          fi
          echo "✅ Cursor rules file exists"