cursor-rules

name	cursor-rules
description	This skill should be used when creating or editing Cursor rules files (.mdc format) in the .cursor/rules directory. Provides guidance on rule types, frontmatter configuration, effective rule writing patterns, and best practices for structuring AI instructions for Cursor IDE.

Cursor Rules

Guide for creating and editing Cursor rules files (.mdc format) that provide context-aware instructions to the AI in Cursor IDE.

Overview

Cursor rules are instructions that guide AI behavior in Cursor IDE. Rules use the MDC format (.mdc) with YAML frontmatter and markdown content, stored in .cursor/rules/ directories.

Key capabilities:

• Define project-specific coding standards and patterns
• Auto-attach context based on file patterns
• Create reusable instruction components
• Control when and how rules are applied

Context: All Cursor rules guidance in this skill applies to .mdc files only, not .cursorrules (deprecated) or AGENTS.md files.

When to Use This Skill

Use this skill when:

• Creating new Cursor rule files for project standards
• Editing existing rules to improve clarity or effectiveness
• Deciding which rule type to use (Always, Auto Attached, Agent Requested, Manual)
• Structuring rule content for optimal AI comprehension
• Applying AI instruction writing best practices to Cursor rules

MDC File Format

Cursor rules use MDC format combining YAML frontmatter with markdown content.

Structure

---
description: Brief explanation of rule's purpose
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
# Rule Content

Markdown instructions for the AI...

Frontmatter Options

description (string, required for Agent Requested rules)

• Explains the rule's purpose
• Used by AI to decide if rule is relevant
• Keep concise (1-2 sentences)

description: TypeScript coding standards including type safety and error handling patterns

globs (array of strings, optional)

• File patterns that trigger auto-attachment
• Uses standard glob syntax
• Applied when matching files are referenced in chat

globs: ["**/*.ts", "**/*.tsx"]  # TypeScript files
globs: ["src/api/**/*"]         # API directory
globs: ["**/*.test.ts"]         # Test files

alwaysApply (boolean, default: false)

• true: Rule always included in model context
• false: Rule applied based on type and conditions

alwaysApply: true   # For critical standards that always apply
alwaysApply: false  # For context-specific guidance

Rule Types

Cursor provides four rule types controlling when rules are applied. Choose the type based on how broadly the rule should apply.

Always

When to use: Critical standards that apply to all AI interactions in the project.

Configuration:

---
description: Core coding standards
alwaysApply: true
---

Characteristics:

• Permanently included in model context
• Use sparingly (impacts token budget)
• Best for: Project-wide standards, critical constraints, fundamental patterns

Example use cases:

• "Never commit secrets or credentials"
• "All functions must have TypeScript return types"
• "Follow company security review process before external API calls"

Auto Attached

When to use: Context-specific guidance that applies when working with certain file types or directories.

Configuration:

---
description: React component patterns
globs: ["**/*.tsx", "src/components/**/*"]
alwaysApply: false
---

Characteristics:

• Applied when glob patterns match referenced files
• Token-efficient (only loads when relevant)
• Best for: File-type standards, directory-specific patterns, framework conventions

Example use cases:

• React component patterns (attached for .tsx files)
• API endpoint standards (attached for src/api/**/*)
• Test conventions (attached for *.test.ts files)

Agent Requested

When to use: Guidance that AI should evaluate for relevance based on the task.

Configuration:

---
description: Database migration patterns for PostgreSQL schema changes
alwaysApply: false
---
# Note: No globs - AI decides based on description

Characteristics:

• AI determines if rule is relevant to current task
• Requires descriptive description field
• Best for: Specialized workflows, domain-specific patterns, optional guidance

Example use cases:

• "Database migration patterns for PostgreSQL"
• "Performance optimization techniques for React"
• "Accessibility guidelines for web components"

Manual

When to use: On-demand guidance invoked explicitly in chat.

Configuration:

---
description: Debugging workflow for production issues
alwaysApply: false
---
# Note: No globs - invoked with @ruleName

Characteristics:

• Invoked explicitly using @ruleName in chat
• Full control over when rule applies
• Best for: Workflows, checklists, specialized procedures

Example use cases:

• "@deploy-checklist" - Pre-deployment verification
• "@debug-production" - Production debugging workflow
• "@refactor-guide" - Code refactoring procedures

Usage:

@debug-production help me investigate the API timeout issue

Writing Effective Rules

Apply AI instruction writing best practices to create clear, actionable Cursor rules.

Core Principles

Keep rules under 500 lines

• Cursor's recommendation for optimal performance
• Decompose large rules into focused, composable components
• Split by domain (e.g., separate rules for testing, API, UI patterns)

Be specific and actionable

• Provide concrete patterns and examples
• Avoid vague guidance like "write good code"
• Include code snippets showing expected patterns

Use progressive disclosure

• Structure: Overview → Core patterns → Detailed guidance → Examples
• Front-load essential information
• Layer complexity for detailed edge cases

Include concrete examples

• Show input/output pairs for patterns
• Use @filename.ts syntax to reference existing project files
• Demonstrate both correct and incorrect approaches

Writing Style

Imperative/infinitive form (verb-first), not second person:

✓ Good: "Validate input before API requests"
✗ Bad: "You should validate input before you make API requests"

Consistent terminology:

✓ Good: Always use "component" for React components
✗ Bad: Mix "component", "element", "widget" interchangeably

Objective, instructional language:

✓ Good: "Return explicit error types rather than throwing exceptions"
✗ Bad: "Hey, try to return errors instead of throwing them if possible"

Using XML Tags in Rules

XML tags help structure complex rules for clearer parsing. Use them for:

Multiple examples requiring distinction:

<example type="valid">
const result = await fetchData();
if (!result) {
  return { error: "Not found" };
}
return result;
</example>

<example type="invalid">
// Don't assume success
return (await fetchData()).data;
</example>

Separating context from instructions:

<context>
This project uses Zod for runtime validation with React Query for data fetching.
</context>

<instructions>
When creating API clients:
1. Define Zod schema for response
2. Create React Query hook using the schema
3. Export both for component consumption
</instructions>

Defining templates:

<template>
export const use[EntityName] = () => {
  return useQuery({
    queryKey: ['[entity]'],
    queryFn: async () => {
      const response = await fetch('/api/[endpoint]');
      return [Schema].parse(await response.json());
    }
  });
};
</template>

Skip XML tags when markdown structure is sufficient for simple content.

Reference Project Files

Use @filename syntax to reference existing project files as examples:

## Component Patterns

Follow the patterns in @src/components/Button.tsx for all interactive components:

- Props interface with TypeScript
- Forwarded refs for accessibility
- Consistent event handler naming

This grounds the AI in actual project code rather than abstract descriptions.

Common Patterns

Project-Wide Standards (Always)

Purpose: Critical standards applying to all code.

---
description: TypeScript and code quality standards
alwaysApply: true
---
# Code Standards

## Type Safety

- All functions must have explicit return types
- No `any` types without justification comment
- Use discriminated unions for complex state

## Error Handling

- Return Result<T, E> types for operations that can fail
- Never silently catch and ignore errors
- Log errors with context before re-throwing

## Testing

- All exported functions must have unit tests
- Integration tests for all API endpoints
- Minimum 80% code coverage

Framework Patterns (Auto Attached)

Purpose: File-type or directory-specific conventions.

---
description: React component patterns and conventions
globs: ["**/*.tsx", "src/components/**/*"]
alwaysApply: false
---

# React Component Standards

## Component Structure

<template>
interface [ComponentName]Props {
  // Props definition
}

export const [ComponentName] = forwardRef<
  HTMLElement,
  [ComponentName]Props
>((props, ref) => {
  // Implementation
});

[ComponentName].displayName = '[ComponentName]';
</template>

## Examples

<example type="valid">
// Interactive component with forwarded ref
interface ButtonProps {
  onClick: () => void;
  children: React.ReactNode;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ onClick, children }, ref) => (
    <button ref={ref} onClick={onClick}>
      {children}
    </button>
  )
);

Button.displayName = 'Button';
</example>

<example type="invalid">
// Missing ref forwarding and display name
export const Button = ({ onClick, children }) => (
  <button onClick={onClick}>{children}</button>
);
</example>

Workflow Procedures (Manual)

Purpose: Step-by-step procedures invoked on-demand.

---
description: Pre-deployment verification checklist
alwaysApply: false
---

# Deployment Checklist

Invoke with: @deploy-checklist

## Pre-Deployment Verification

### 1. Code Quality

- [ ] All tests passing (`npm run test`)
- [ ] No TypeScript errors (`npm run type-check`)
- [ ] Linter passing (`npm run lint`)
- [ ] No console.log or debugger statements

**Validation:** Check CI pipeline status

### 2. Security Review

- [ ] No hardcoded secrets or API keys
- [ ] Environment variables properly configured
- [ ] Dependencies updated (no critical vulnerabilities)

**Validation:** Run `npm audit` and review results

### 3. Database Migrations

- [ ] Migrations tested locally
- [ ] Rollback plan documented
- [ ] Backup completed

**Validation:** Verify migration scripts in `db/migrations/`

### 4. Deployment

Follow standard deployment process:
1. Deploy to staging
2. Run smoke tests
3. Get approval from lead
4. Deploy to production
5. Monitor for 15 minutes

Specialized Guidance (Agent Requested)

Purpose: Domain-specific patterns AI loads when relevant.

---
description: Performance optimization patterns for React applications
alwaysApply: false
---

# React Performance Optimization

## When to Optimize

Optimize when:
- Components re-render unnecessarily (use React DevTools Profiler)
- User interactions feel laggy (>100ms response)
- Large lists without virtualization

## Optimization Techniques

### Memoization

<instructions>
Use `useMemo` for expensive computations:
- Complex filtering/sorting operations
- Derived state calculations
- Object/array creation in render
</instructions>

<example type="valid">
const filteredItems = useMemo(
  () => items.filter(item => item.category === selectedCategory),
  [items, selectedCategory]
);
</example>

<example type="invalid">
// Recreates array on every render
const filteredItems = items.filter(item =>
  item.category === selectedCategory
);
</example>

### Component Memoization

<instructions>
Use `React.memo` for expensive presentational components:
- Complex rendering logic
- Large component trees
- Components receiving stable props
</instructions>

Refer to @src/components/DataTable.tsx for production example.

Anti-Patterns to Avoid

❌ Vague, high-level guidance

✗ Bad: "Write clean, maintainable code following best practices"
✓ Good: "Extract functions exceeding 50 lines into smaller units with single responsibilities"

❌ Overly broad Always rules

✗ Bad: 500-line rule with alwaysApply: true covering all coding standards
✓ Good: Focused 100-line rule for critical standards + separate Auto Attached rules for context-specific patterns

❌ Missing concrete examples

✗ Bad: "Use proper error handling"
✓ Good: Show specific error handling pattern with code example

❌ Inconsistent terminology

✗ Bad: Mix "API endpoint", "route", "path", "URL" for same concept
✓ Good: Choose "API endpoint" and use consistently

❌ Conversational language

✗ Bad: "Hey, when you're working with APIs, make sure you handle errors properly, okay?"
✓ Good: "Handle API errors by returning Result<T, Error> types"

❌ Temporal references

✗ Bad: "Use the new authentication system" or "Recently refactored to async/await"
✓ Good: "Use OAuth 2.0 authentication" (evergreen, specific)

❌ No glob patterns for context-specific rules

✗ Bad: React-specific rule without globs (always loads unnecessarily)
✓ Good: React rule with globs: ["**/*.tsx"] (loads only when relevant)

Quality Checklist

Before finalizing a Cursor rule:

Format & Structure:

• Uses .mdc format with YAML frontmatter
• Saved in .cursor/rules/ directory
• Frontmatter includes required fields for rule type
• Rule under 500 lines (decompose if longer)

Rule Type Configuration:

• Appropriate rule type chosen (Always/Auto Attached/Agent Requested/Manual)
• alwaysApply: true only for critical project-wide standards
• globs configured for Auto Attached rules
• description clear and specific for Agent Requested rules

Content Quality:

• Imperative/infinitive form (not second person)
• Consistent terminology throughout
• Concrete examples with code snippets
• References to project files using @filename syntax
• Progressive disclosure (overview → details)

Specificity:

• Actionable patterns, not vague guidance
• Specific constraints and requirements
• No temporal references ("new", "old", "recently")
• Clear anti-patterns identified

Token Efficiency:

• Large rules decomposed into focused components
• Auto Attached rules use appropriate globs
• Always rules limited to essential standards
• No redundant information

Example: Complete Rule File

Comprehensive example showing best practices:

---
description: API client patterns using Zod schemas and React Query hooks
globs: ["src/api/**/*", "**/*-client.ts"]
alwaysApply: false
---

# API Client Patterns

## Overview

This project separates API clients (Zod schemas + React Query hooks) from UI components.

**Pattern:** Schema definition → Client function → React Query hook → Component consumption

## Client Structure

<template>
// 1. Define Zod schema
const [Entity]Schema = z.object({
  id: z.string(),
  // ... fields
});

type [Entity] = z.infer<typeof [Entity]Schema>;

// 2. Create client function
async function fetch[Entity](id: string): Promise<[Entity]> {
  const response = await fetch(`/api/[entity]/${id}`);
  return [Entity]Schema.parse(await response.json());
}

// 3. Create React Query hook
export function use[Entity](id: string) {
  return useQuery({
    queryKey: ['[entity]', id],
    queryFn: () => fetch[Entity](id),
  });
}
</template>

## Error Handling

<instructions>
All client functions must handle errors consistently:
1. Parse responses with Zod (throws on invalid data)
2. Catch network errors and re-throw with context
3. React Query handles loading/error states
</instructions>

<example type="valid">
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    const data = await response.json();
    return UserSchema.parse(data);
  } catch (error) {
    console.error('Failed to fetch user:', { id, error });
    throw error;
  }
}
</example>

<example type="invalid">
// Missing error context and response validation
async function fetchUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return UserSchema.parse(await response.json());
}
</example>

## Reference Implementation

See @src/api/user-client.ts for production example implementing this pattern.

## Validation

Before completing API client:
- [ ] Zod schema covers all response fields
- [ ] Client function includes error handling
- [ ] React Query hook properly configured
- [ ] Types exported for component consumption

---

Remember: Effective Cursor rules are specific, actionable, and scoped appropriately. When in doubt, create focused rules with Auto Attached globs rather than broad Always rules.