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¶

Text Only
1	`.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¶

Text Only
1 2 3	`.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¶

Text Only

@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¶

Text Only
1 2	`@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

YAML
---
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:

TypeScript
// 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:

Python
# 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:

Markdown
# Complete API Development Workflow

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

Template System in Action¶

Usage: Ask AI to create a new service using templates

AI generates:

Python
# 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):

project-overview.mdc: Understands this is FastAPI + React + SQLModel
@api-workflow: Follows complete development process
@templates/service-template.py: Generates service with proper patterns
@templates/component-template.tsx: Creates React components
backend-patterns.mdc: Ensures proper dependency injection
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:

Bash
# 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¶

YAML
---
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¶

YAML
---
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>

Text Only

---

## 🧪 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

Bash
1 2	`# Create new rule touch .cursor/rules/your-new-rule.mdc`

2. Add Metadata

YAML
---
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¶

Bash
# Complete development workflow with AI
task run-local           # Start backend
@api-workflow           # Get AI guidance
Ask AI to create feature # Uses templates + patterns
task generate-client     # Sync API types
Ask AI to create UI      # Uses frontend patterns
@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¶

Verify AI integration in your boilerplate – /development/TEST_CURSOR_RULES.md
Master AI-assisted development
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. ✨