cursor-usage

name	cursor-usage
description	How to write and manage Cursor rules - invoke with @cursor-usage

Source Cursor rule: .cursor/rules/cursor-usage.mdc. Original file scope: .cursor/rules/*.mdc. Original Cursor alwaysApply: false.

Using Cursor Rules

Overview

Cursor rules provide system-level instructions to the AI to maintain code consistency, quality, and adherence to project standards. They are stored in the .cursor/rules/ directory as .mdc (Markdown with frontmatter) files.

Rule File Structure

Each .mdc rule file consists of two parts:

1. Frontmatter (YAML metadata)

---
description: Brief overview of what this rule enforces
globs: **/*.{ts,tsx}
alwaysApply: true
---

Frontmatter Fields:

• description: A clear, concise explanation of the rule's purpose
• globs: Glob pattern to match files where this rule should apply (plain string, no quotes or arrays)
  • Examples:
    • **/*.tsx - All TSX files
    • **/*.{ts,tsx} - All TS and TSX files
    • apps/*/components/**/*.tsx - All TSX files in any app's components directory
    • **/trigger/**/*.ts - All TS files in trigger directories
• alwaysApply: Boolean indicating if the rule should always be active
  • true: Rule is always active when working on matching files
  • false: Rule can be selectively invoked with @rule-name

2. Content (Markdown)

The body of the rule file contains the actual guidelines, examples, and instructions written in Markdown format.

How Rules Are Applied

Automatic Application

Rules with alwaysApply: true are automatically loaded when:

• You open a file matching the globs pattern
• You're working on code that matches the pattern
• Cursor AI generates or suggests code for matching files

Manual Invocation

You can reference specific rules in your prompts:

@design-system create a new button component

This explicitly tells Cursor to apply the design-system rule.

Best Practices for Writing Rules

1. Keep Rules Focused

• Each rule file should cover a specific domain (e.g., design system, API patterns, testing)
• Avoid mixing unrelated concerns in a single rule file
• Aim for rules under 500 lines for better AI comprehension

2. Provide Concrete Examples

Always include:

• ✅ Good examples (what TO do)
• ❌ Bad examples (what NOT to do)
• Real code snippets from your project

// ✅ Good: Use semantic tokens
<div className="bg-background text-foreground">Content</div>

// ❌ Bad: Hardcoded colors
<div className="bg-white text-black">Content</div>

3. Use Clear Section Headers

Organize content with descriptive headers:

## Core Principles

## Rules

## Examples

## Exceptions

## Common Mistakes

4. Define Exceptions Explicitly

If there are cases where rules don't apply, state them clearly:

## Exceptions

The ONLY time you can pass className to a design system component is for:

1. Width utilities: `w-full`, `max-w-md`
2. Responsive display: `hidden`, `md:block`

5. Include Checklists

Provide actionable checklists for validation:

## Code Review Checklist

Before committing:

- [ ] Uses semantic color tokens
- [ ] Works in both light and dark mode
- [ ] Fully responsive

Managing Rules

Creating a New Rule

1. Create a new .mdc file in .cursor/rules/
2. Add appropriate frontmatter
3. Write clear guidelines with examples
4. Test by working on matching files

Updating Existing Rules

1. Edit the .mdc file
2. Rules are automatically reloaded
3. Test changes with relevant files

Organizing Rules

Recommended structure:

.cursor/rules/
├── design-system.mdc       # Component usage, variants, composition
├── code-standards.mdc      # General code quality rules
├── typescript-rules.mdc    # TypeScript type safety
├── react-code.mdc          # React patterns and conventions
├── data-fetching.mdc       # Server/client data patterns
└── cursor-usage.mdc        # This file - how to use rules

Rule Scope with Globs

Common Glob Patterns

# All TypeScript/TSX files
globs: **/*.{ts,tsx}

# Only TSX files (React components)
globs: **/*.tsx

# Only trigger task files
globs: **/trigger/**/*.ts

# Prisma schema files
globs: **/*.prisma

# All JSON and TypeScript files
globs: **/*.{ts,tsx,json}

Glob Pattern Tips

• Use ** for recursive directory matching
• Use * for single-level wildcard
• Use {ts,tsx} for multiple extensions
• No quotes or array brackets needed
• Be specific to avoid over-applying rules

Debugging Rules

Rule Not Applying?

1. Check the globs pattern matches your file
2. Verify frontmatter YAML syntax is correct
3. Ensure alwaysApply is set appropriately
4. Try manually invoking with @ruleName

Rule Conflicting?

1. Check if multiple rules apply to the same files
2. Make rules more specific with tighter globs
3. Consolidate related rules into one file

Advanced Features

Conditional Rules

Use alwaysApply: false for rules that should only apply in specific contexts:

---
description: Performance optimization guidelines
globs: **/*.ts
alwaysApply: false
---

Invoke with: @performance-optimization refactor this component

Hierarchical Rules

More specific globs take precedence:

• design-system.mdc with globs: **/*.tsx (broad)
• trigger.basic.mdc with globs: **/trigger/**/*.ts (specific)

The specific rule will have more weight for trigger files.

Quick Reference

Create a New Rule

touch .cursor/rules/my-new-rule.mdc

---
description: What this rule enforces
globs: **/*.{ts,tsx}
alwaysApply: true
---

# Rule Title

## Guidelines

- Point 1
- Point 2

Apply a Rule

• Automatic: Save a file matching the globs pattern
• Manual: Use @my-new-rule in your prompt

Debug a Rule

1. Check file matches globs pattern
2. Verify YAML frontmatter syntax
3. Look for conflicting rules
4. Try manual invocation

---

Remember: Rules are here to help, not hinder. If a rule doesn't make sense for a specific case, discuss with the team and update the rule accordingly.