mixpanel-react-native/.cursor/rules/README.md

Official React Native Tracking Library for Mixpanel Analytics

# Cursor Rules for mixpanel-react-native

This directory contains Cursor MDC rules that actively guide AI assistance when working with the mixpanel-react-native codebase. These rules complement the comprehensive Claude Code context files and transform discovered patterns into actionable behavioral guidance.

## 🎯 Philosophy

The Cursor rules serve a different purpose than the Claude Code context:

- **Claude Code Context**: Comprehensive reference documentation for deep understanding
- **Cursor Rules**: Active behavioral guidance that shapes every code generation

Think of Claude Code as your library, and Cursor rules as your active coach that guides decisions in real-time.

## 🏗️ Rule Architecture

### Always Rules (`always/`)
Applied to EVERY file, ensuring fundamental patterns are never violated:

- **`core-conventions.mdc`**: Essential naming, import organization, token-based architecture
- **`architecture-principles.mdc`**: Dual implementation, graceful degradation, factory patterns
- **`error-handling.mdc`**: Input validation, silent failures, defensive programming

**Total context impact**: ~300 lines - designed to fit in limited context windows

### Component Rules (`components/`)
Auto-attached based on file patterns, providing context-specific guidance:

- **`native-modules.mdc`**: iOS Swift and Android Java bridge patterns (`ios/**/*.swift`, `android/**/*.java`)
- **`javascript-implementation.mdc`**: JS fallback patterns (`javascript/**/*.js`)
- **`storage-operations.mdc`**: AsyncStorage and persistence patterns (`**/*storage*.js`, `**/*persistent*.js`)
- **`network-operations.mdc`**: Retry logic and request patterns (`**/*network*.js`)

### Testing Rules (`testing/`)
Applied to test files for comprehensive testing strategies:

- **`test-patterns.mdc`**: Dual-mode testing, validation patterns (`__tests__/**/*.js`, `**/*.test.js`)

### Workflow Rules (`workflows/`)
Agent-requested rules for complex procedures:

- **`new-feature.mdc`**: Step-by-step feature addition workflow
- **`debugging.mdc`**: Systematic diagnostic approach
- **`testing-workflow.mdc`**: Comprehensive testing methodology

## 🔄 Rule Usage Patterns

### For New Team Members
1. Always rules provide immediate guardrails for any file they touch
2. Component rules guide technology-specific patterns automatically
3. Workflow rules available when tackling complex tasks

### For Feature Development
1. Always rules ensure architectural consistency
2. Native module rules guide iOS/Android bridge implementation
3. JavaScript implementation rules ensure fallback compatibility
4. New feature workflow provides step-by-step guidance

### For Debugging
1. Always rules maintain code quality during fixes
2. Component rules provide context-specific debugging patterns
3. Debugging workflow offers systematic diagnostic approach

### For Code Review
1. Always rules catch fundamental violations
2. Component rules verify technology-specific patterns
3. Testing rules ensure comprehensive coverage

## 📊 Rule Categorization Logic

### Always Apply (Critical Mass: ~300 lines)
Patterns that apply to literally every file and represent non-negotiable conventions:
- Token-based architecture (every operation must include token)
- Error handling philosophy (Helper classes, graceful degradation)
- Naming conventions (kebab-case files, camelCase variables)
- Import organization (external first, then grouped internal)

### Auto-Attached (Context-Sensitive)
Patterns specific to file types or technologies:
- Native bridge patterns only apply to iOS/Android files
- Queue management only applies to JavaScript implementation
- Storage patterns only apply to persistence-related files

### Agent-Requested (Complex Workflows)
Multi-step procedures that are too complex for always-apply:
- Feature addition requires multiple files and platforms
- Debugging requires systematic investigation
- Testing requires comprehensive setup and validation

## 🔗 Integration with Claude Code Context

### When to Use Cursor Rules
- **Real-time coding**: Rules guide every keystroke and suggestion
- **Code generation**: Rules ensure generated code follows patterns
- **Quick decisions**: Rules provide immediate answers without research

### When to Consult Claude Code Context
- **Deep understanding**: Need to understand why patterns exist
- **Complex architecture decisions**: Need full system context
- **Learning the codebase**: Need comprehensive overview
- **Debugging complex issues**: Need detailed diagnostic procedures

### Complementary Relationship
```
┌─────────────────┐    ┌─────────────────┐
│   Cursor Rules  │    │ Claude Context  │
│   (Behavioral)  │    │ (Knowledge)     │
├─────────────────┤    ├─────────────────┤
│ • What to do    │    │ • Why it works  │
│ • How to code   │    │ • How it fits   │
│ • Enforce rules │    │ • What options  │
│ • Guide style   │    │ • Understand    │
└─────────────────┘    └─────────────────┘
         │                       │
         └───────────┬───────────┘
                     │
            ┌─────────────────┐
            │   AI Assistant  │
            │   Effectiveness │
            └─────────────────┘
```

## 🎨 Rule Design Principles

### 1. Actionable Over Descriptive
Rules tell you what to do, not just what exists:
```markdown
❌ "The codebase uses token-based architecture"
✅ "EVERY operation MUST include token as first parameter"
```

### 2. Specific Over Generic
Rules provide concrete patterns, not abstract advice:
```markdown
❌ "Handle errors gracefully"
✅ "ALWAYS wrap storage operations in try-catch with return null fallback"
```

### 3. Contextual Over Universal
Rules apply when relevant, not everywhere:
```markdown
✅ Native module rules only apply to ios/**/*.swift and android/**/*.java
✅ Testing rules only apply to __tests__/**/*.js
```

### 4. Concise Over Comprehensive
Rules fit in limited context windows:
```markdown
✅ Always rules total ~300 lines
✅ Component rules focus on essential patterns only
```

## 🚀 Quick Start Guide

### For Immediate Use
1. Start coding any file - always rules provide immediate guidance
2. Work on iOS/Android files - native module rules auto-apply
3. Work on JavaScript files - implementation rules auto-apply

### For Complex Tasks
1. Request "new feature workflow" for adding functionality
2. Request "debugging workflow" for systematic issue investigation
3. Request "testing workflow" for comprehensive validation

### For Learning
1. Read through always rules to understand fundamental patterns
2. Explore component rules for technology-specific approaches
3. Reference workflow rules for complex procedures

## 🔧 Rule Maintenance

### When to Update Rules
- **New architectural patterns** discovered in the codebase
- **Technology integrations** change (new React Native versions)
- **Testing strategies** evolve
- **Common mistakes** identified in code reviews

### How to Update Rules
1. **Discover pattern** in actual codebase usage
2. **Validate pattern** follows established architecture
3. **Determine rule type** (always vs component vs workflow)
4. **Update relevant rule file** with specific, actionable guidance
5. **Test rule effectiveness** in practice

### Rule Quality Metrics
- **Specificity**: Rules provide concrete, actionable guidance
- **Coverage**: Rules apply to appropriate file patterns without over-matching
- **Consistency**: Rules align with discovered codebase patterns
- **Effectiveness**: Rules prevent common mistakes and guide good practices

## 🎯 Success Indicators

### Effective Rules Enable
- **Consistent code generation** following established patterns
- **Faster development** with guided decision-making
- **Fewer architectural mistakes** through active enforcement
- **Better code quality** through pattern reinforcement

### Rule Health Indicators
- **Rules stay current** with codebase evolution
- **Generated code follows** discovered patterns
- **New team members** produce consistent code
- **Common patterns** are automatically applied

## 📋 Rule Reference Quick Guide

### Essential Always Rules
- `core-conventions.mdc`: Naming, imports, token architecture
- `architecture-principles.mdc`: Dual implementation, graceful degradation
- `error-handling.mdc`: Validation, silent failures, defensive programming

### Key Component Rules
- `native-modules.mdc`: iOS @objc and Android @ReactMethod patterns
- `javascript-implementation.mdc`: Factory functions, async/await, queuing
- `storage-operations.mdc`: AsyncStorage wrapper, fallbacks, token-scoped keys

### Critical Workflows
- `new-feature.mdc`: API → iOS → Android → JS → Tests workflow
- `debugging.mdc`: Implementation mode → logging → systematic diagnosis
- `testing-workflow.mdc`: Validation → native mode → JS mode → integration

This rule system transforms the comprehensive Claude Code knowledge into active behavioral guidance, ensuring consistent, high-quality code generation that follows established patterns and prevents common mistakes.