Complete Guide to Cursor Rules: Making AI Generate Spec-Compliant Code (With Practical Setup)

1 AM. I’m staring at the code Cursor just generated, my finger hovering over the Enter key—for the third time.

First attempt, it used var to declare variables. Second attempt, it switched to class components. This time? It straight-up deleted all my TypeScript types and helpfully added a bunch of any annotations. I took a deep breath, deleted the code, and decided to write it myself.

That’s when it hit me: the AI isn’t dumb—I just never told it “my rules.”

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

Honestly, when I first started using Cursor, I assumed the AI would “just know” what good code looks like. It wasn’t until a teammate complained, “Why does the component Cursor generated for you look nothing like our style?” that I realized: AI needs explicit guidelines.

This article will help you solve this problem. Spend 5 minutes configuring Cursor Rules, and from then on, AI will generate code that perfectly matches your project standards—no more wrong tech stacks, no more style violations, no more existential crises.

What Are Cursor Rules? Why Do You Need Them?

The Essence of Cursor Rules: Setting Ground Rules for AI

Simply put, Cursor Rules are configuration files that tell the AI your coding standards.

Think of it like a company giving new employees a “development handbook” that outlines: what tech stack we use, how to name code, how to organize files. Cursor Rules does exactly that—it’s the “onboarding manual” for AI.

The mechanism is straightforward: when you chat with Cursor, the content from your rules files is automatically appended to the prompt. When the AI sees these rules, it knows “oh, this project uses React Hooks, not class components” and generates code accordingly.

What Happens Without Rules? My Painful Lessons

The first time I used Cursor on a project, I thought I’d struck gold—AI writes code blazingly fast. But three days later, I discovered a huge problem:

Code style was a complete mess. Some files used camelCase naming, others used PascalCase, and a few even used snake_case. I couldn’t even remember which was which.

Wrong tech stack. I clearly wanted functional components, but Cursor generated a bunch of class Component extends React.Component. I tried telling it “use Hooks,” but the next file went right back to classes.

Violated project standards. The team required all functions to have comments, but Cursor’s code was pristine—not a single comment. And error handling? The spec required try-catch, but the AI just raw-dogged API calls.

After that, I spent two days refactoring code until my hands ached.

After Configuring Rules? Sweet Success

Later, I spent 5 minutes setting up a .cursorrules file, making clear:

• Tech stack is React 18 + TypeScript
• Use only functional components and Hooks
• Naming uniformly uses camelCase
• Must write type definitions, no any

Guess what happened?

From that day forward, every component Cursor generated matched the spec. Code consistency improved by at least 80%, and my code review time was cut in half. Teammates asked, “How did you make Cursor so obedient?”

Sweet.

The data doesn’t lie: According to community best practices, properly configured Rules can significantly improve code consistency and reduce later refactoring costs. The awesome-cursorrules repository on GitHub has over 2000 stars, showing this is a real developer need.

Cursor Rules Configuration Methods (2026 Latest)

The Key Point: Old vs New Configuration Methods

If you search for Cursor Rules tutorials online, you might see two different approaches—some say use a .cursorrules file, others say use a .cursor/rules directory. Don’t panic, both are correct, just from different time periods.

Old method (before 2025):
Create a single .cursorrules file directly in the project root directory and write all rules there. Simple and brutal.

New method (2026 recommended):
Create a .cursor/rules directory in the project root, then place multiple .mdc files inside. Each file can handle different rule categories.

The official recommendation is to migrate to the new method because it’s more flexible—you can split rules by function and set different activation scopes. The old method still works, but will be deprecated in a future version.

My suggestion? If it’s a new project, go straight to the new method. For old projects, migrate when you have time, no rush.

Two Rule Levels: Global vs Project

Cursor supports two levels of rules—understanding their differences is crucial.

User Rules (Global Rules)

These are your personal coding preferences that apply to all projects.

Settings path: File → Preferences → Cursor Settings → Rules → User Rules

Use cases: Cross-project universal standards. For example:

• “All my projects use TypeScript”
• “I hate var, use only const or let”
• “All async operations use async/await, not .then()”

Think of it as your personal “code cleanliness” settings.

Project Rules

Project-specific standards that apply only to the current project.

Setup method:

1. Create a .cursor folder in the project root
2. Create a rules folder under .cursor
3. Create .mdc files in rules, like frontend.mdc or typescript-rules.mdc

Use cases: Project-specific tech stacks and standards. For example:

• “This is a Next.js 14 + TypeScript + Tailwind CSS project”
• “APIs uniformly use RESTful standards”
• “Component files go in components/ directory, use PascalCase naming”

The priority is clear: project rules > global rules. If there’s a conflict, the project wins.

Rule Activation Scope: Don’t Let Rules Be Too Broad

This is an important feature in the 2026 version—you can control when rules activate.

In .mdc files, you can set activation scope:

Always: No matter what you’re doing, this rule applies. Good for core standards like “no var”. But use sparingly—too many Always rules will clutter the AI’s context.

Auto Attached: Triggers automatically based on file type. For example, you can set “.tsx files automatically apply React rules”, “.py files automatically apply Python rules”. This is my most recommended approach.

Agent Requested: Let the AI decide based on conversation content whether it needs this rule. Good for optional auxiliary rules.

Manual: Only activates when you explicitly tell Cursor to use this rule. Good for special scenarios like “performance optimization rules” or “test code rules”.

My practical experience: 80% Auto Attached, 10% Always, remaining 10% case-by-case.

January 2026 New Feature: /rules Command

Just recently (January 8, 2026), Cursor released a CLI update adding a super useful command: /rules.

Now you can type /rules directly in Cursor’s terminal to quickly create and edit rule files, no need to manually hunt for folders. For people who frequently adjust rules, this feature saves a lot of time.

For specific usage, check the Cursor official forum update announcement.

How to Write Effective Cursor Rules?

This is the most critical part. How well you write rules directly determines whether Cursor will obey.

Three Categories of Rule Content

When configuring rules, I suggest writing on three levels:

A. Tech Stack and Architecture

First, tell the AI what kind of project this is.

Tech Stack:
- Frontend: React 18 + TypeScript 5.3
- State Management: Zustand
- Styling: Tailwind CSS 3.4
- Build Tool: Vite 5.0
- Node.js Version: 18+

Also clarify architecture standards:

Architecture Standards:
- Frontend-backend separation
- API uses RESTful style
- Folder structure:
  - components/ for reusable components
  - pages/ for page components
  - utils/ for utility functions
  - hooks/ for custom Hooks

Why so detailed?

I learned this the hard way. I used to just write “use React”, and Cursor would sometimes generate React 16 patterns, sometimes React 18 patterns. After I specified version numbers, the problem vanished.

B. Code Standards

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

This part is key to unifying code style.

Code Standards:

Naming Rules:
- Component names: PascalCase (e.g., UserProfile)
- File names: kebab-case (e.g., user-profile.tsx)
- Variables and functions: camelCase (e.g., getUserData)
- Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRY_COUNT)

Code Style:
- Use only functional components, no class components
- Prefer const, then let, forbid var
- Use arrow functions, not function keyword (unless you need this)
- All components must have TypeScript type definitions

File Length:
- Single file max 300 lines
- Single function max 50 lines

Comment Requirements:
- Key functions must have JSDoc comments
- Complex logic must have inline comments
- Comments explain "why", not "what"

C. Quality and Testing

Error Handling:
- All async operations must have try-catch
- API call failures need user-friendly error messages
- Don't swallow errors, at minimum console.error

Performance Optimization:
- List rendering must have keys
- Large lists use virtual scrolling
- Images must specify width and height to avoid layout shift

Testing Requirements:
- Utility functions must have unit tests
- Critical business logic must have test coverage

Golden Principles for Writing Rules

Principle 1: Specific, Executable, Verifiable

This is the most important principle.

❌ Bad examples: “Write good code” “Follow best practices” “Pay attention to performance”

These rules are meaningless. When AI sees “best practices”, how does it know which practice you mean?

✅ Good examples:

• “Use functional components, no class components”
• “Define Props with interface, not type”
• “Async operations must use async/await, not .then()”

See the difference? Good rules are direct instructions that can be executed, not vague suggestions.

Principle 2: Keep Length Under 500 Lines

This is a community best practice. Rules that are too long are hard for AI to understand and occupy lots of context space.

If your rules file exceeds 500 lines, it’s time to split:

• frontend.mdc - Frontend rules
• backend.mdc - Backend rules
• typescript.mdc - TypeScript rules
• testing.mdc - Testing rules

Principle 3: Use Example Code, Don’t Just Talk

AI loves examples.

❌ Just talk, no action:

Components should be functional with type definitions

✅ Provide examples:

Component example:

interface UserCardProps {
  name: string;
  email: string;
}

export const UserCard = ({ name, email }: UserCardProps) => {
  return (
    <div className="user-card">
      <h3>{name}</h3>
      <p>{email}</p>
    </div>
  );
};

With examples, Cursor knows exactly what kind of code you want. This trick is super effective.

Principle 4: Put Most Important Rules First

AI prioritizes content at the top. So:

First priority: Tech stack and versions
Second priority: Code style
Third priority: File organization
Last: Optional optimization suggestions

Common Mistakes to Avoid

Mistake 1: Rules too vague

“Follow React best practices”—which best practices? From 2016 or 2024?

Change to: “Use React Hooks, prefer useState and useEffect, use useReducer for complex state”

Mistake 2: Rules conflict with each other

“Must use TypeScript” but also “allow any type”—isn’t that contradictory?

When AI sees conflicting rules, it gets confused and might ignore both.

Mistake 3: Forgetting to specify versions

React 16 class component syntax and React 18 Hooks syntax are vastly different. If you just write “use React”, AI might randomly pick a version’s syntax.

Be explicit: React 18.2+, TypeScript 5.3+, Node.js 18+.

Mistake 4: Writing rules like an academic paper

Some people like to write lengthy explanations about why we should do things this way, listing various theoretical justifications.

Don’t do this. AI doesn’t need you to convince it, it just needs to know “what to do”.

❌ “We chose TypeScript because it provides static type checking, can find errors at compile time, improve code quality…” (followed by 300 more words)

✅ “Use TypeScript, forbid any type”

Concise and powerful.

Practical Example: Configuring Rules for React + TypeScript Project

Theory is nice, but let’s see a real example.

Suppose you’re building a React + TypeScript project with this tech stack:

• React 18
• TypeScript 5.x
• Tailwind CSS 3.x
• Vite 5.x

Team standards require:

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

• Use only functional components
• Strict types, no any
• Unified file and naming conventions
• Must have error handling

Let’s configure the rules file step by step.

Step 1: Create Rules File

In the project root:

mkdir -p .cursor/rules
cd .cursor/rules
touch react-typescript.mdc

Step 2: Define Tech Stack

Open react-typescript.mdc and clarify the tech stack:

# React + TypeScript Project Rules

## Tech Stack

- React 18.2+
- TypeScript 5.3+
- Tailwind CSS 3.4+
- Vite 5.0+
- Node.js 18+

## Dependency Management

- Package manager: pnpm
- Don't use npm or yarn

Step 3: Code Style Standards

Next, define how code should be written:

## Code Standards

### Component Standards

- Use only functional components, forbid class components
- Component names use PascalCase
- File names use kebab-case
- Use named exports, not default exports

Example:

// ❌ Wrong
export default function userProfile() { }

// ✅ Correct
export const UserProfile = () => { }

### TypeScript Standards

- All components must have type definitions
- Props use interface, not type
- Forbid any, use unknown or specific types
- Function return types must be explicitly declared

Example:

// ✅ Correct component definition
interface UserCardProps {
  name: string;
  email: string;
  age?: number;
}

export const UserCard = ({ name, email, age }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded">
      <h3 className="text-lg font-bold">{name}</h3>
      <p className="text-gray-600">{email}</p>
      {age && <p>Age: {age}</p>}
    </div>
  );
};

### Naming Conventions

- Variables and functions: camelCase
- Components: PascalCase
- Constants: UPPER_SNAKE_CASE
- File names: kebab-case
- CSS class names: Tailwind atomic classes, no custom CSS

### Async Handling

- All async operations use async/await
- Forbid .then() chaining
- Must have try-catch error handling

Example:

// ✅ Correct
const fetchUserData = async (userId: string): Promise<User> => {
  try {
    const response = await fetch(`/api/users/${userId}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
};

Step 4: File Organization Standards

## File Organization

### Directory Structure

src/
├── components/     # Reusable components
├── pages/          # Page components
├── hooks/          # Custom Hooks
├── utils/          # Utility functions
├── types/          # TypeScript type definitions
├── services/       # API calls
└── constants/      # Constant definitions

### File Naming

- Component files: user-card.tsx
- Utility files: format-date.ts
- Type files: user.types.ts
- Hook files: use-user-data.ts

### Import Order

1. React related
2. Third-party libraries
3. Internal project components
4. Utility functions
5. Type definitions
6. Styles

Step 5: Quality Requirements

## Quality Requirements

### Error Handling

- API calls must have try-catch
- Error messages should be user-friendly
- Log errors

### Performance Optimization

- List rendering must have key attribute
- Avoid creating new objects or functions in render functions
- Use React.memo to optimize unnecessary re-renders
- Images must specify width and height

### Code Quality

- Single file max 300 lines
- Single function max 50 lines
- Complex logic must have comments
- Key functions must have JSDoc comments

Step 6: Complete Rules File

Putting the above together, you have a complete .cursor/rules/react-typescript.mdc file.

You can adjust based on project needs. For example:

• If using Redux, add Redux standards
• If using React Query, add data fetching standards
• Add any special business rules

Testing the Results

After configuration, try having Cursor generate a user card component:

Your prompt: “Create a user card component showing username, email, and avatar”

Before configuring rules, Cursor might generate:

export default function UserCard(props) {
  return <div>...</div>
}

After configuring rules, Cursor generates:

interface UserCardProps {
  name: string;
  email: string;
  avatarUrl: string;
}

export const UserCard = ({ name, email, avatarUrl }: UserCardProps): JSX.Element => {
  return (
    <div className="p-4 border rounded shadow">
      <img src={avatarUrl} alt={name} className="w-16 h-16 rounded-full" width="64" height="64" />
      <h3 className="text-lg font-bold mt-2">{name}</h3>
      <p className="text-gray-600">{email}</p>
    </div>
  );
};

Look, perfectly spec-compliant:

• ✅ Functional component
• ✅ TypeScript type definitions
• ✅ Named export
• ✅ Tailwind styles
• ✅ Image has width/height attributes

One and done, no rework needed.

Advanced Techniques and Common Issues

Rule Priority: Who’s in Charge?

When you have multiple rule layers, you might encounter conflicts. Cursor’s priority rules work like this:

Project rules > global rules

If your global rules say “use single quotes” but project rules say “use double quotes”, Cursor listens to the project.

Subdirectory rules > parent directory rules

Suppose your project structure is:

project/
├── .cursor/rules/general.mdc
└── frontend/
    └── .cursor/rules/react.mdc

When working in the frontend/ directory, react.mdc has higher priority.

Manual invocation > automatic triggering

If you explicitly mention a specific rule in conversation, that rule gets priority consideration, even if its activation scope is set to Manual.

Managing Multiple Rule Files: The Art of Splitting

When projects get complex, one rules file might not be enough. Here’s how I split them:

.cursor/rules/
├── core.mdc              # Core tech stack (Always)
├── frontend.mdc          # Frontend rules (Auto Attached: *.tsx, *.ts)
├── backend.mdc           # Backend rules (Auto Attached: *.py, *.go)
├── testing.mdc           # Test rules (Auto Attached: *.test.*)
└── performance.mdc       # Performance optimization (Manual)

Each file handles a different domain, clear and organized.

Debugging Techniques: What If Rules Don’t Work?

Problem 1: Don’t know if rules are active

Open Cursor’s Composer or Chat and ask: “What rules do you see?”

Cursor will tell you which rules files are currently loaded. If your rule doesn’t appear, it means:

• Path might be wrong
• Activation scope setting might be wrong
• File format might have issues

Problem 2: Rules conflict

If two rules contradict each other, Cursor might “go on strike” and ignore both.

Solutions:

1. Check rule files, find conflict points
2. Clarify priorities, delete lower priority rules
3. Or explicitly state in higher priority rule “override other rules”

Problem 3: AI doesn’t follow rules

Sometimes you clearly wrote rules, but Cursor does its own thing anyway.

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

Possible reasons:

1. Rules too vague: Change to specific instructions
2. Rules too long: AI might ignore later content, put important rules first
3. Rules conflict with your prompt: If you say “use class components” in conversation but rules say “use functional components”, AI will prioritize your conversation content

Solutions:

• Rewrite rules, add example code
• Explicitly say in conversation “follow project rules”
• Change rule from Auto Attached to Always

Getting Ready-Made Rules: Standing on Giants’ Shoulders

Don’t want to write rules from scratch? The community has tons of ready resources.

awesome-cursorrules

The hottest Cursor Rules repository on GitHub, 2000+ stars. Covers:

• Frontend frameworks like React, Vue, Angular
• Backend languages like Python, Go, Java
• Full-stack frameworks like Next.js, Astro, Nuxt
• Plus TypeScript, testing, Docker specialized rules

Copy the rules file you need, tweak slightly, and you’re good.

awesome-cursorrules-zh

Rules library optimized for Chinese developers. Especially nice is it provides “merged rules” examples—like combining React and FastAPI rules into one full-stack project rule.

cursor.directory

Online rules library, web version, supports online preview and copy. Covers 30+ mainstream frameworks.

dotcursorrules.com

Another online resource site with lots of practical cases and best practice sharing.

My suggestion: Start with community rules, use them for a while, then adjust based on project needs. Don’t waste time writing from scratch.

Team Collaboration: Making Rules a Team Asset

If you’re doing team development, putting rules under version control is a good idea.

1. Commit to Git

Commit the .cursor/rules directory to the code repository:

git add .cursor/rules
git commit -m "Add Cursor rules for project standards"

This way when team members pull code, Cursor automatically loads project rules, keeping everyone’s AI behavior consistent.

2. New Member Onboarding

Add this section to the project README:

## Developing with Cursor

This project has Cursor Rules configured in the `.cursor/rules` directory.

When using Cursor, AI will automatically follow these standards:
- React 18 + TypeScript
- Functional components + Hooks
- Tailwind CSS styles
- Strict type definitions

To adjust rules, please discuss with the team first.

3. Regular Reviews

Tech stacks update, standards evolve. Recommend reviewing rules files quarterly:

• Are there outdated rules?
• Are there new best practices to add?
• What feedback does the team have on which rules need adjusting?

Treat rules as living documentation, not one-time configuration.

Conclusion

After all this, it really boils down to one thing: Set clear rules for AI, and it’ll work properly.

Think back to when you first started using Cursor, did you also experience:

• Asking it to write a component, result was stylistically chaotic
• Wanting it to use TypeScript, it sneakily added any
• Code looked very AI-generated, nothing like human writing

This isn’t Cursor’s fault—we just never told it “our rules”.

Now you know what to do:

1. Create rules file — New projects use .cursor/rules, old projects start with .cursorrules
2. Clarify tech stack — Version numbers, frameworks, toolchains, the more specific the better
3. Define code standards — Naming, style, error handling, provide example code
4. Control rule length — Under 500 lines, split when necessary
5. Continuous optimization — Rules aren’t one-time config, evolve with the project

Take action now:

• If you haven’t configured rules yet, spend 5 minutes creating your first rules file
• If you already have rules, check if they’re too vague, add some example code
• If it’s a team project, commit rules to Git so everyone follows them

A month later, you’ll find:

• Code review time cut in half
• Code style unified
• New members onboard faster
• AI truly became your capable assistant

Finally, some resources so you don’t have to write rules from scratch:

• awesome-cursorrules - 2000+ star rules library
• awesome-cursorrules-zh - Chinese developer optimized version
• cursorrules.org - Online rules library

14 min read · Published on: Jan 10, 2026 · Modified on: Feb 4, 2026

Easton

Technology