cursor_rules.mdc

---
description: Use when editing cursor rules, working with .mdc files, fixing rule issues, updating rule metadata, or troubleshooting rule activation problems
globs:
alwaysApply: false
---
# Cursor Rules: Core Guidelines

## 🚨 Critical Rule Length Guidelines

**Rule Length Limits for Effective AI Usage:**
- **Ideal**: 200-500 words per rule
- **Maximum**: 1,000 words for complex workflows  
- **Problem**: Rules over 1,000 words cause context overflow and reduced activation
- **Solution**: Split large rules into focused components

**Why Length Matters:**
- Long rules overwhelm Claude's context window when injected
- AI may ignore overly complex rules due to cognitive load
- Multiple focused rules work better than one comprehensive rule
- Context saturation can cause other rules to be ignored

## Rule Types and Behavior

Cursor rules go through **two distinct stages**:

### Stage 1: Context Injection
Rules are added to the AI's context based on frontmatter configuration

### Stage 2: Activation  
The AI decides whether to actually use injected rules based on relevance to the current query

## The Four Rule Types

### 1. Always Rules
```mdc
---
description: 
globs: 
alwaysApply: true
---
```
- **Behavior**: Always injected into every chat and command+k
- **Use case**: Universal coding standards, critical practices
- **Warning**: Use sparingly to avoid context overload

### 2. Auto-Attach Rules  
```mdc
---
description: 
globs: lib/**/*.ex, test/**/*.exs
alwaysApply: false
---
```
- **Behavior**: Injected when user attaches/mentions files matching glob patterns
- **Use case**: Technology-specific rules (Elixir, Phoenix LiveView, etc.)
- **Important**: Only triggered when files are explicitly attached to chat, not just opened

### 3. Agent Requested Rules
```mdc
---
description: Clear description of when this rule should apply
globs: 
alwaysApply: false
---
```
- **Behavior**: AI decides whether to fetch and use based on description
- **Use case**: Workflow guidance, context-dependent practices
- **Key**: Description must clearly indicate trigger conditions

### 4. Manual Rules
```mdc
---
description: 
globs: 
alwaysApply: false
---
```
- **Behavior**: Only used when explicitly referenced with @ or markdown links
- **Use case**: Specialized procedures, emergency workflows

## Critical Technical Details

### Frontmatter Format
- **NOT YAML**: Don't quote values or use YAML syntax
- **Three required fields**: All rules must have `description:`, `globs:`, and `alwaysApply:` (even if empty)
- **No field combinations**: Avoid mixing `description` with `globs` - causes confusion

### Context vs Activation
The AI receives this instruction about rules:
> "Use them if they seem useful to the user's most recent query, but do not use them if they seem unrelated."

This means:
- Rules in context are **suggestions**, not commands
- AI can ignore rules even if they're injected
- Rule content and relevance matter more than frontmatter after injection

## Best Practices

### Writing Effective Rules
- **Keep rules focused**: One concept per file
- **Use clear descriptions**: For Agent Requested rules, be specific about trigger conditions
- **Start descriptions with action words**: "USE WHEN creating tests", "APPLY FOR Elixir files"
- **Avoid redundancy**: Don't duplicate information across multiple rules
- **Test rule effectiveness**: Monitor when rules get applied vs ignored

### Rule Organization
- **Descriptive filenames**: Use `snake_case` (e.g., `elixir_coding_standards.mdc`)
- **Separate by domain**: Create different files for different technologies/workflows
- **Regular cleanup**: Remove obsolete rules that AI consistently ignores

## Related Rules

For detailed guidance on specific aspects:
- `cursor_rules_metadata.mdc` - Frontmatter editing and terminal verification
- `cursor_rules_troubleshooting.mdc` - Common issues and solutions
- `cursor_rules_best_practices.mdc` - Advanced organization and effectiveness tips