# Cursor Integration Best Practices

## Core Principles
- **Leverage Cursor's AI Capabilities**: Use built-in features for maximum efficiency
- **Optimize Rule Application**: Use appropriate rule types for different contexts
- **File Reference Integration**: Use `@` syntax for including files in context
- **Memory Integration**: Enable and utilize Cursor's memory features
- **Command Integration**: Use Cursor commands for rule generation and management

## Implementation Patterns

### Rule Type Selection Protocol
```python
# ✅ DO: Choose appropriate rule types
def select_rule_type(context: str, scope: str) -> RuleType:
    """Select the most appropriate rule type based on context."""
    
    if scope == "project_wide" and context == "essential":
        return RuleType.ALWAYS_APPLIED
    
    elif scope == "file_specific" and context == "automatic":
        return RuleType.AUTO_ATTACHED
    
    elif scope == "workflow_specific" and context == "intelligent":
        return RuleType.AGENT_REQUESTED
    
    elif scope == "manual" and context == "on_demand":
        return RuleType.MANUAL
    
    return RuleType.AGENT_REQUESTED  # Default fallback
```

### File Reference Integration
```python
# ✅ DO: Use file references effectively
def create_rule_with_references():
    """Example of effective file reference usage."""
    
    # Include implementation examples
    implementation_files = [
        "@src/services/protocols.py",
        "@src/services/transcription_service.py",
        "@tests/test_transcription_service.py"
    ]
    
    # Reference related rules
    related_rules = [
        "[project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)",
        "[audio-processing.mdc](mdc:.cursor/rules/audio-processing.mdc)"
    ]
    
    return Rule(
        content=rule_content,
        file_references=implementation_files,
        rule_references=related_rules
    )
```

### Memory Integration Pattern
```python
# ✅ DO: Integrate with Cursor memories
def integrate_with_memories(context: str) -> EnhancedContext:
    """Integrate rule processing with Cursor memories."""
    
    # Enable memory features
    if memories_enabled:
        # Use memory for context enhancement
        enhanced_context = enhance_with_memories(context)
        
        # Generate rules from memory patterns
        memory_based_rules = generate_rules_from_memories()
        
        # Update context with memory insights
        return EnhancedContext(
            original_context=context,
            memory_insights=enhanced_context,
            generated_rules=memory_based_rules
        )
    
    return context
```

### Anti-Patterns
```python
# ❌ DON'T: Use wrong rule types
def bad_rule_type_selection():
    """Inappropriate rule type selection."""
    # BAD: Using Always Applied for specific file patterns
    # BAD: Using Manual for essential project rules
    # BAD: Using Auto Attached without proper glob patterns
    pass

# ❌ DON'T: Ignore file references
def bad_file_reference_usage():
    """Poor file reference practices."""
    # BAD: Not using @ syntax for file inclusion
    # BAD: Not updating references when files change
    # BAD: Using hypothetical examples instead of real code
    pass

# ❌ DON'T: Ignore Cursor features
def bad_cursor_integration():
    """Not leveraging Cursor's capabilities."""
    # BAD: Not using /Generate Cursor Rules command
    # BAD: Not enabling memories
    # BAD: Not using nested rules for organization
    pass
```

## Cursor-Specific Workflows

### Rule Generation Workflow
1. **Identify Pattern**: Notice repeated prompts or decisions in chat
2. **Use Command**: Execute `/Generate Cursor Rules` command
3. **Review Generated Rule**: Check the generated rule for accuracy
4. **Refine Rule**: Edit the rule to match project standards
5. **Place Appropriately**: Put rule in correct nested directory
6. **Test Rule**: Verify rule applies correctly
7. **Document**: Update rule documentation if needed

### Memory-Enhanced Development
1. **Enable Memories**: Turn on memory features in Cursor settings
2. **Work Naturally**: Continue development as usual
3. **Review Patterns**: Check memory insights for patterns
4. **Generate Rules**: Use memory patterns to create new rules
5. **Apply Insights**: Use memory insights to improve existing rules
6. **Maintain Consistency**: Ensure memory insights align with rules

### Nested Rule Organization
1. **Analyze Project Structure**: Identify logical groupings
2. **Create Nested Directories**: Set up `.cursor/rules` in subdirectories
3. **Scope Rules Appropriately**: Use glob patterns for auto-attachment
4. **Test Rule Application**: Verify rules apply to correct files
5. **Maintain Hierarchy**: Keep rule hierarchy consistent
6. **Update References**: Keep cross-references current

## Quality Assurance Protocols

### Rule Generation Checklist
- [ ] Pattern identified in chat or workflow
- [ ] `/Generate Cursor Rules` command used
- [ ] Generated rule reviewed for accuracy
- [ ] Rule refined to match project standards
- [ ] Rule placed in appropriate directory
- [ ] Rule tested for correct application
- [ ] Documentation updated if needed

### Memory Integration Checklist
- [ ] Memories enabled in Cursor settings
- [ ] Memory insights reviewed regularly
- [ ] Patterns identified from memory data
- [ ] New rules generated from patterns
- [ ] Existing rules updated with insights
- [ ] Consistency maintained across rules

### File Reference Checklist
- [ ] `@` syntax used for file inclusion
- [ ] Real code examples referenced
- [ ] References updated when files change
- [ ] Cross-references to other rules maintained
- [ ] File paths are accurate and current
- [ ] Examples are relevant and helpful

## Performance Guidelines
- **Rule Generation**: Use `/Generate Cursor Rules` for efficiency
- **Memory Integration**: Enable memories for automatic insights
- **File References**: Keep references current and relevant
- **Nested Rules**: Use for better organization and performance
- **Rule Types**: Choose appropriate types for optimal loading
- **Cross-References**: Maintain for consistency and navigation

## File References
- **[cursor_rules.mdc](mdc:.cursor/rules/cursor_rules.mdc)** - Core rule guidelines
- **[agents.mdc](mdc:.cursor/rules/agents.mdc)** - Project context and navigation
- **[context_engineering.mdc](mdc:.cursor/rules/context_engineering.mdc)** - Context engineering protocols
- **[project-structure.mdc](mdc:.cursor/rules/project-structure.mdc)** - File organization patterns

## Error Handling Patterns
```python
# ✅ DO: Handle Cursor integration errors
def handle_cursor_integration_error(error: CursorIntegrationError) -> ErrorResolution:
    """Handle errors in Cursor integration."""
    
    if isinstance(error, RuleGenerationError):
        return resolve_rule_generation_error(error)
    elif isinstance(error, MemoryIntegrationError):
        return resolve_memory_integration_error(error)
    elif isinstance(error, FileReferenceError):
        return resolve_file_reference_error(error)
    elif isinstance(error, NestedRuleError):
        return resolve_nested_rule_error(error)
    else:
        return escalate_cursor_error(error)
```

## Continuous Improvement
- **Pattern Recognition**: Continuously identify patterns for rule generation
- **Memory Analysis**: Regularly analyze memory insights for improvements
- **Rule Optimization**: Optimize rule types and organization
- **Feature Integration**: Stay updated with new Cursor features
- **Workflow Enhancement**: Improve workflows based on Cursor capabilities
- **Documentation Updates**: Keep documentation current with Cursor features
description:
globs:
alwaysApply: true
---