Skip to content

Cursor Rules System - Complete Guide

The Cursor Rules System is the heart of AI Velocity's intelligent development experience. It transforms Cursor from a simple AI assistant into a knowledgeable development partner that understands your entire project structure, patterns, and workflows.

What Are Cursor Rules?

Cursor Rules are intelligent guidelines stored in .cursor/rules/ that teach your AI about:

  • Your project architecture and tech stack
  • Code patterns and conventions
  • Development workflows and best practices
  • Template-driven code generation

Think of them as AI memory that persists across all your development sessions.

Rule Types Overview

1. Always-Applied Rules

.cursor/rules/project-overview.mdc
Purpose: Core project context active in every AI interaction
When Active: Always
Contains: Architecture overview, tech stack, routing patterns

2. Auto-Attached Rules

.cursor/rules/frontend/frontend-patterns.mdc → React/TypeScript files
.cursor/rules/backend/backend-patterns.mdc → Python files
.cursor/rules/frontend/styling-guide.mdc → Theme/UI files
Purpose: Context-specific patterns based on file type
When Active: Automatically when working in matching files
Contains: File-specific patterns, conventions, best practices

3. Manual/Requestable Rules

@api-workflow → Complete API development process
@database-migration → Alembic migration workflows
@deployment → Multi-platform deployment guides
@development-workflow → Local development processes
Purpose: Detailed workflows for specific tasks
When Active: Explicitly requested with @ruleName
Contains: Step-by-step processes, command sequences

4. Template System

@templates/component-template.tsx → React component boilerplate
@templates/service-template.py → FastAPI service boilerplate
Purpose: Consistent code generation patterns
When Active: Referenced by other rules or requested directly
Contains: Complete code templates with proper patterns

How Each Rule Type Works

Always-Applied Rules in Action

File: .cursor/rules/project-overview.mdc 

---
description: CraftYourStartup project overview and core principles
alwaysApply: true
---

# CraftYourStartup Boilerplate
- Backend: FastAPI + SQLModel + PostgreSQL
- Frontend: React 18 + TypeScript + Vite + Material-UI
- Authentication: JWT + OAuth (Google)
- Payments: Stripe integration
- State Management: TanStack React Query + Context API

Impact: AI always knows your tech stack and can make contextual suggestions.

Auto-Attached Rules in Action

When you open a React component file: 

// frontend/src/components/UserCard.tsx
import React from 'react';

Automatically activates: frontend/frontend-patterns.mdc

  • AI knows to use TypeScript interfaces
  • Suggests MUI components and styling patterns
  • Follows StandardButton system
  • Includes proper error handling patterns

When you open a Python service file: 

# app/services/user_service.py
from sqlmodel.ext.asyncio.session import AsyncSession

Automatically activates: backend/backend-patterns.mdc

  • AI knows to use dependency injection
  • Suggests proper service layer patterns
  • Includes error handling and logging
  • Follows FastAPI conventions

Manual Rules in Action

Usage: Type @api-workflow in Cursor

AI Response: 

# Complete API Development Workflow

1. Define Pydantic Schemas (app/schemas/)
2. Implement Service Layer (app/services/)
3. Add Controller Endpoints (app/controllers/)
4. Generate Frontend Client (`task generate-client`)
5. Create React Hooks (hooks/api/)
6. Build Components with proper error handling

Template System in Action

Usage: Ask AI to create a new service using templates

AI generates: 

# Uses @templates/service-template.py
class YourService:
    def __init__(
        self,
        db: AsyncSession,
        current_user: Optional[CurrentUserResponse],
        request: Request,
    ):
        self.db = db
        self.current_user = current_user
        self.request = request

    async def create_item(self, item_data: YourCreateSchema) -> YourReadSchema:
        # Template includes proper validation, error handling, logging
        if not self.current_user:
            raise HTTPException(status_code=401, detail="Authentication required")
        # ... complete template pattern

Practical Usage Examples

Example 1: Creating a New Feature

You: "Create a new Article feature with CRUD operations"

AI (using multiple rules):

  1. project-overview.mdc: Understands this is FastAPI + React + SQLModel
  2. @api-workflow: Follows complete development process
  3. @templates/service-template.py: Generates service with proper patterns
  4. @templates/component-template.tsx: Creates React components
  5. backend-patterns.mdc: Ensures proper dependency injection
  6. frontend-patterns.mdc: Uses StandardButton and MUI patterns

Result: Complete feature with consistent patterns across entire stack.

Example 2: Database Migration

You: @database-migration I need to add a new field to User model

AI Response: 

# Step-by-step migration process:
1. Update model in app/models.py:
   new_field: str = Field(default="default_value")

2. Generate migration:
   task alembic-revision-local -- "Add new_field to User"

3. Review migration file in migrations/versions/

4. Apply migration:
   task alembic-upgrade-local

5. Test in development before production

Example 3: Deployment Guidance

You: @deployment I want to deploy to Railway

AI provides: Complete Railway deployment guide with:

  • Step-by-step commands
  • Environment variable setup
  • Database configuration
  • Troubleshooting tips

Rule File Structure

Standard Rule Format

---
description: Brief description of rule purpose
globs: ["app/**/*.py"]  # For auto-attached rules
alwaysApply: true       # For always-applied rules
---

# Rule Content
Your rule content in markdown format with:
- Code examples
- Best practices
- Template references
- Workflow steps

Auto-Attached Rule Example

---
description: React frontend patterns and conventions
globs: ["frontend/src/**/*.tsx", "frontend/src/**/*.ts"]
---

# Frontend Development Patterns

@templates/component-template.tsx

## Button System
Always use StandardButton components:

```tsx
import { StandardButton, CTAButton } from "@/components/ui/StandardButton";

<StandardButton variant="contained" icon={<Save />}>
  Save Item
</StandardButton>

---

## 🧪 Testing Your Rules

### **Verification Methods**

**1. File-Based Testing**
- Open Python file → Ask for service creation → Should use service patterns
- Open React file → Ask for component → Should use component patterns

**2. Manual Rule Testing**
- Type `@api-workflow` → Should provide complete API development guide
- Type `@database-migration` → Should provide migration workflow

**3. Template Testing**
- Type `@templates/service-template.py` → Should show service template
- Ask to create component → Should reference component template

### **Debug Commands**
```bash
# Check rule files exist
ls -la .cursor/rules/

# View rule metadata
head -10 .cursor/rules/project-overview.mdc

# Check auto-attached patterns
grep -r "globs:" .cursor/rules/

Success Indicators

✅ AI suggests code following your patterns
✅ Manual rules respond when requested
✅ Templates are used in generated code
✅ Context-specific rules activate correctly

Best Practices

Rule Organization

  • Keep rules focused: One concern per rule file
  • Use clear descriptions: Help AI understand purpose
  • Reference templates: Link to reusable code patterns
  • Update regularly: Keep rules current with code changes

Template Design

  • Include complete examples: Full working code
  • Add extensive comments: Explain patterns and decisions
  • Cover edge cases: Error handling, validation, logging
  • Use TypeScript interfaces: Ensure type safety

Testing Rules

  • Test after changes: Verify rules work as expected
  • Use multiple scenarios: Different file types and contexts
  • Check rule interactions: Ensure rules work together
  • Document discoveries: Note what works best

Customizing Rules

Adding New Rules

1. Create Rule File 

# Create new rule
touch .cursor/rules/your-new-rule.mdc

2. Add Metadata 

---
description: Your rule description
globs: ["matching/**/*.pattern"]  # For auto-attached
---

3. Add Content

  • Code examples
  • Best practices
  • Template references
  • Usage patterns

Modifying Existing Rules

1. Update Rule Content

  • Edit existing .mdc files
  • Add new patterns or examples
  • Update best practices

2. Test Changes

  • Verify rule activation
  • Check AI responses
  • Test with real development scenarios

Advanced Usage

Rule Combinations

Rules work together intelligently:

  • Always-applied + Auto-attached = Context-aware assistance
  • Manual rules + Templates = Guided code generation
  • Multiple auto-attached = Comprehensive pattern coverage

Workflow Integration

# Complete development workflow with AI
1. task run-local           # Start backend
2. @api-workflow           # Get AI guidance
3. Ask AI to create feature # Uses templates + patterns
4. task generate-client     # Sync API types
5. Ask AI to create UI      # Uses frontend patterns
6. @deployment             # Get deployment guidance

Team Adoption

  • Share rules: Consistent patterns across team
  • Document patterns: Rules serve as living documentation
  • Update together: Evolve rules with project needs
  • Train newcomers: Rules help onboard new developers

Next Steps

  1. Verify AI integration in your boilerplate – /development/TEST_CURSOR_RULES.md
  2. Master AI-assisted development
  3. Try the complete feature creation process using Cursor (@api-workflow)

The Cursor Rules system transforms your AI from assistant to partner.

Instead of explaining your project every time, your AI already knows your patterns, conventions, and workflows. This is the future of development—intelligent, consistent, and fast. ✨