Cursor Rules

Comprehensive development guidelines and patterns organized as Cursor AI rules for consistent, production-ready code.

🎯 Rule System Overview

What Are Cursor Rules?

Cursor rules are specialized markdown files (.mdc) that provide context-aware development guidance to AI assistants. They contain:

Coding patterns and best practices
Architecture guidelines specific to your stack
Real code examples from your actual codebase
Domain-specific knowledge for complex features

How Rules Work


// Rules are automatically applied based on:
// 1. File types (globs: "*.tsx", "*.ts")
// 2. Always-apply status (alwaysApply: true/false)
// 3. Manual activation (fetch_rules tool)
 
// Example rule header:
---
description: Guidelines for building Convex projects
globs: *.tsx,*.ts
alwaysApply: false
---

🏗️ Rule Categories

Core Architecture Rules

Project Structure (`project-structure.mdc`)

File organization and naming conventions
Directory structure for Next.js + Convex
Route organization with route groups
Import patterns and path aliases


// Example patterns from the rule:
// ✅ Good - Consistent file naming
convex/core/
├── users.queries.ts        # Query functions
├── users.mutations.ts      # Mutation functions
├── users.validators.ts     # Input validation
└── users.helpers.ts        # Shared utilities
 
// ✅ Good - Page-specific organization
w/[workspace-slug]/
├── page.tsx
├── layout.tsx
└── _components/           # Page-specific components
    ├── AppSidebar/
    └── InviteMembersDialog.tsx

Convex Overview (`convex-overview.mdc`)

Function types (queries, mutations, actions)
Custom authentication wrappers
File organization patterns
Cross-references to specialized rules

Backend Development Rules

Schema Design (`convex-backend-schema.mdc`)

Table definitions with proper indexing
Custom validators integration
Multi-tenant patterns for SaaS
Performance optimization strategies

Query Patterns (`convex-backend-queries.mdc`)

Authentication wrappers (userQuery, workspaceMemberQuery)
Pagination and search patterns
Data enrichment with file URLs
Performance optimization techniques

Mutation Patterns (`convex-backend-mutations.mdc`)

CRUD operations with proper validation
File upload and storage management
Authorization and permission handling
Error handling best practices

Validation System (`convex-backend-validators.mdc`)

Custom validator creation
Type-safe input validation
Reusable validation patterns
Integration with mutations/queries

Data Aggregation (`convex-backend-aggregates.mdc`)

Analytics patterns and reporting
Performance optimization for large datasets
Real-time aggregation techniques

Frontend Development Rules

React Client Integration (`convex-react-client.mdc`)

Custom hooks with Convex integration
Real-time subscriptions management
Error handling and loading states
Type-safe client patterns

Custom Hooks (`custom-hooks.mdc`)

Hook organization in _hooks/ directories
Naming conventions (use<Feature>.<operation>.tsx)
UI component integration within hooks
Reusable patterns across pages

Styling Guidelines (`styling.mdc`)

Design system colors for dark mode
Tailwind CSS patterns and utilities
Component styling consistency
Color mapping from hardcoded to system colors

UI/UX Standards (`uiux.mdc`)

User-centered design principles
Accessibility guidelines and ARIA patterns
Loading states and error handling
Copy-to-clipboard functionality
Progressive disclosure patterns

Feature-Specific Rules

Stripe Integration (`manage-stripe-product-and-price.mdc`)

Complete Stripe management system
Product and pricing configuration
Metadata-driven business logic
Developer-only administration
Real-world examples of pricing models

Development Process Rules

SaaS Kit Management (`saaskit-*` rules)

saaskit-overview.mdc - Complete boilerplate overview
saaskit-init.mdc - Project initialization guide
saaskit-generate-tasks.mdc - Task generation from PRDs
saaskit-create-prd.mdc - Product requirement documents
saaskit-process-task-list.mdc - Task management workflow
saaskit-self-improve.mdc - Rule improvement guidelines

🔧 Using Cursor Rules

Automatic Application

Rules are applied automatically based on file patterns:


// Rules with alwaysApply: true are always active
// Rules with specific globs activate for matching files
 
// Example: Working on a Convex query file
// convex/core/users.queries.ts
// → Automatically applies convex-backend-queries.mdc
// → Provides query patterns and authentication wrappers

Manual Rule Activation

Use the fetch_rules tool to access specific guidance:


// Example: Need Stripe integration help
// AI can fetch: manage-stripe-product-and-price.mdc
// → Get complete Stripe patterns and examples
 
// Example: Setting up new project
// AI can fetch: saaskit-init.mdc
// → Get step-by-step initialization guide

Rule Categories by Use Case

Starting New Features

convex-backend-schema.mdc - Design your tables
convex-backend-mutations.mdc - Create data operations
convex-react-client.mdc - Build frontend integration
custom-hooks.mdc - Create reusable hooks

Building UI Components

uiux.mdc - Follow design principles
styling.mdc - Use design system colors
project-structure.mdc - Organize components properly

Complex Integrations

manage-stripe-product-and-price.mdc - Stripe billing
convex-backend-validators.mdc - Input validation
convex-backend-aggregates.mdc - Data analytics

📋 Rule Structure Pattern

Standard Rule Format


---
description: Brief description of the rule's purpose  
globs: *.tsx,*.ts                    # File patterns to apply to
alwaysApply: false                   # Auto-apply status
---
 
# Rule Title
 
## Overview
 
Brief description of what this rule covers
 
## Core Patterns
 
Key patterns and practices
 
### Pattern Name
 
Detailed explanation with code examples
 
```typescript
// ✅ Good - Recommended approach
const goodExample = () => {
  // Implementation following the rule
};
 
// ❌ Bad - What to avoid
const badExample = () => {
  // Anti-pattern explanation
};
```

Best Practices

Additional guidance and tips

Common Pitfalls

Things to watch out for



### **Cross-Rule References**

Rules reference each other for comprehensive guidance:

```markdown
// From convex-overview.mdc
### Schema & Database Design
See [convex-backend-schema.mdc](mdc:.cursor/rules/convex-backend-schema.mdc) for:
- Database schema patterns and table definitions
- Index design and optimization

### Queries & Data Retrieval
See [convex-backend-queries.mdc](mdc:.cursor/rules/convex-backend-queries.mdc) for:
- Query patterns and authorization wrappers
- Full-text search using searchIndex

🚀 Rule Benefits

Consistency Across Team

Standardized patterns across all developers
Consistent file organization and naming
Unified coding standards and best practices

Accelerated Development

Ready-to-use patterns for common tasks
Real examples from production codebase
Best practice guidance built-in

Knowledge Preservation

Documented decisions and architectural choices
Migration guides for updating patterns
Continuous improvement through rule updates

AI-Assisted Development

Context-aware guidance based on current file
Automatic pattern application for consistency
Reduced cognitive load for complex features

🔄 Rule Maintenance

Self-Improvement Process (`saaskit-self-improve.mdc`)

The rules include a meta-rule for improving themselves:

Pattern Recognition - Identify new patterns in codebase
Rule Updates - Add new examples and practices
Cross-Reference Updates - Keep references current
Deprecation Management - Remove outdated patterns

Update Triggers

New technologies used in 3+ files
Common bugs that could be prevented
Repeated code review feedback
Better examples discovered in codebase

Quality Standards

Actionable and specific guidance
Real code examples from actual project
Up-to-date references and links
Consistent enforcement across patterns

📖 Getting Started with Rules

For New Developers

Read saaskit-overview.mdc - Understand the complete system
Follow saaskit-init.mdc - Set up your development environment
Study project-structure.mdc - Learn file organization
Practice with convex-overview.mdc - Understand backend patterns

For Specific Features

Check existing rules for similar patterns
Use fetch_rules to get specific guidance
Follow established patterns from rules
Update rules if new patterns emerge

For Code Reviews

Reference rules in review comments
Suggest pattern improvements based on rules
Update rules when better examples are found
Ensure consistency with established patterns

The Cursor rules system provides comprehensive, context-aware guidance that evolves with your codebase, ensuring consistent, production-ready development across your entire team.