Project Rules

Project rules are the foundation of effective AI-assisted development. In this 10-minute guide, you’ll learn to create rules that ensure consistent code generation aligned with your team’s standards.

Understanding Project Rules

Wskazówka

Think of rules as persistent prompts - instructions that automatically apply to every AI interaction, ensuring consistency without repetition.

Rule System Architecture

.cursor/rules/
├── always/              # Applied to every AI interaction
├── auto-attached/       # Applied based on file patterns
├── agent-requested/     # AI decides when to apply
└── manual/             # Only when explicitly referenced

How Rules Work

Automatic Context

Rules become part of the AI’s context automatically, like having a senior developer always guiding the junior

Version Controlled

Check rules into Git so your entire team benefits from shared knowledge and standards

Hierarchical

Rules cascade from project root to subdirectories, with local rules overriding global ones

Dynamic Updates

Update rules on the fly - AI immediately adopts new guidelines without restart

Generate Initial Rules

Automatic Generation

1. Open Command Palette: Cmd/Ctrl + Shift + P

2. Run Generation Command: “Generate Cursor Rules”

3. Review Generated Structure:

   .cursor/rules/
   ├── code-style.mdc
   ├── architecture.mdc
   ├── testing.mdc
   └── documentation.mdc

4. Customize Generated Rules: Edit each file to match your standards

What Gets Generated

Cursor analyzes your codebase and creates rules for:

• Coding style from existing patterns
• Architecture from project structure
• Testing patterns from test files
• Documentation from comments/docs
• Dependencies from package files
• Git conventions from commit history

Rule Types and Usage

1. Always Rules

Always Applied Rules

Rules that apply to every AI interaction. Use sparingly for universal standards.

---
description: Core coding standards
alwaysApply: true
---

# Universal Standards

- Never commit secrets or API keys
- Always handle errors explicitly
- Use TypeScript strict mode
- Follow ESLint configuration
- Include unit tests for new functions

2. Auto-Attached Rules

Frontend Rules

---
description: React component standards
globs: ["src/components/**/*.tsx"]
---

# React Component Rules

- Use functional components only
- Implement proper TypeScript props
- Include Storybook stories
- Use CSS modules for styling
- Follow atomic design principles

## Component Structure
```typescript
interface ComponentProps {
  // Documented props
}

export const Component: FC<ComponentProps> = (props) => {
  // Implementation
};

Backend Rules

---
description: API endpoint standards
globs: ["src/api/**/*.ts"]
---

# API Development Rules

- Use RESTful conventions
- Implement proper error handling
- Include OpenAPI documentation
- Validate all inputs with Zod
- Return consistent response formats

## Response Format
```typescript
{
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
  meta?: { page: number; total: number };
}

Database Rules

---
description: Database and ORM patterns
globs: ["src/db/**/*.ts", "prisma/**/*"]
---

# Database Rules

- Use migrations for schema changes
- Never use raw SQL in application code
- Implement soft deletes
- Add indexes for foreign keys
- Use transactions for multi-table updates

## Naming Conventions
- Tables: plural_snake_case
- Columns: snake_case
- Indexes: idx_table_columns

3. Agent-Requested Rules

---
description: Performance optimization guidelines - AI uses when optimizing code
alwaysApply: false
---

# Performance Optimization

When optimizing code:
- Profile before optimizing
- Document performance improvements
- Consider memory vs CPU tradeoffs
- Use caching strategically
- Implement lazy loading where appropriate

4. Manual Rules

---
description: Legacy code handling - use @legacy-rules
alwaysApply: false
---

# Legacy Code Guidelines

When working with legacy code:
- Maintain backward compatibility
- Add deprecation warnings
- Create migration guides
- Test extensively before refactoring

Creating Effective Rules

Rule Writing Best Practices

1. Be Specific and Actionable

   ❌ "Write good code"
   ✅ "Use const for immutable values, let for mutable"

2. Include Examples

   ## Error Handling Pattern
   ```typescript
   try {
     const result = await riskyOperation();
     return { success: true, data: result };
   } catch (error) {
     logger.error('Operation failed', { error, context });
     return { success: false, error: error.message };
   }

3. Provide Context

   # Why This Rule
   We use dependency injection to improve testability
   and reduce coupling between modules.

4. Keep Rules Focused

   • One topic per rule file
   • 50-200 lines optimal length
   • Clear section headers

Rule Template Library

Security Rules

---
description: Security best practices
alwaysApply: true
---

# Security Standards

## Authentication
- Use JWT tokens with short expiration
- Implement refresh token rotation
- Store sensitive data in environment variables
- Hash passwords with bcrypt (min 10 rounds)

## Input Validation
- Sanitize all user inputs
- Use parameterized queries
- Implement rate limiting
- Validate file uploads

## NEVER
- Log passwords or tokens
- Use eval() or dynamic code execution
- Trust client-side validation
- Store secrets in code

Testing Rules

---
description: Testing standards and patterns
globs: ["**/*.test.ts", "**/*.spec.ts"]
---

# Testing Guidelines

## Test Structure
- Use AAA pattern (Arrange, Act, Assert)
- One assertion per test when possible
- Descriptive test names that explain the scenario

## Coverage Requirements
- Minimum 80% code coverage
- 100% coverage for critical paths
- Test edge cases and error scenarios

## Example Test
```typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should hash the password before saving', async () => {
      // Arrange
      const userData = { email: 'test@example.com', password: 'plain' };

      // Act
      const user = await userService.createUser(userData);

      // Assert
      expect(user.password).not.toBe('plain');
      expect(bcrypt.compareSync('plain', user.password)).toBe(true);
    });
  });
});

Documentation Rules

---
description: Documentation standards
alwaysApply: false
---

# Documentation Requirements

## Code Comments
- JSDoc for all public functions
- Explain WHY, not WHAT
- Document complex algorithms
- Include examples for utilities

## JSDoc Template

/**
 * Calculates the compound interest
 * @param principal - Initial amount
 * @param rate - Annual interest rate (as decimal)
 * @param time - Time period in years
 * @param n - Compounding frequency per year
 * @returns The final amount after compound interest
 * @example
 * calculateCompoundInterest(1000, 0.05, 2, 12) // $1104.94
 */

## README Sections
1. Project Overview
2. Quick Start
3. Architecture
4. API Documentation
5. Contributing Guidelines

Dynamic Rule Management

Update Rules from Chat

Wskazówka

Press # in chat to save learnings directly to rules - no manual editing required!

1. During Development:

   AI: "I'll use PostgreSQL for this feature"
   You: "# Always use MySQL for our projects, not PostgreSQL"

2. Rule Gets Added:

   # Database Choice
   Always use MySQL for our projects, not PostgreSQL

3. Immediate Effect: Next request will use MySQL

Generate Rules from Conversations

After a productive session:

1. Run /Generate Cursor Rules in chat
2. AI extracts patterns and decisions
3. Creates rules for future use
4. Review and commit to Git

Rule Organization Strategies

By Feature

.cursor/rules/
├── features/
│   ├── authentication/
│   │   ├── jwt-tokens.mdc
│   │   └── oauth-flow.mdc
│   ├── payments/
│   │   ├── stripe-integration.mdc
│   │   └── invoice-generation.mdc
│   └── notifications/
│       ├── email-templates.mdc
│       └── push-notifications.mdc

By Layer

.cursor/rules/
├── presentation/
│   ├── components.mdc
│   └── styles.mdc
├── business/
│   ├── services.mdc
│   └── validation.mdc
└── data/
    ├── repositories.mdc
    └── migrations.mdc

By Concern

.cursor/rules/
├── performance/
│   ├── caching.mdc
│   └── optimization.mdc
├── security/
│   ├── authentication.mdc
│   └── encryption.mdc
└── quality/
    ├── testing.mdc
    └── code-review.mdc

Advanced Rule Techniques

Conditional Rules

---
description: Environment-specific rules
globs: ["src/**/*.ts"]
---

# Environment Rules

## Development
When NODE_ENV is development:
- Use verbose logging
- Enable debug endpoints
- Skip email sending

## Production
When NODE_ENV is production:
- Use structured logging
- Disable debug endpoints
- Implement rate limiting

Reference External Files

---
description: Architecture patterns
---

# Follow Our Architecture

Implement patterns from:
@architecture/diagrams/system-design.png
@architecture/decisions/adr-001.md

Key principles:
- Event-driven communication
- CQRS for complex domains
- Repository pattern for data access

Progressive Enhancement

---
description: Refactoring guidelines
globs: ["src/legacy/**/*"]
---

# Legacy Code Refactoring

## Phase 1: Add Types
- Add TypeScript types to interfaces
- Document existing behavior
- Don't change functionality

## Phase 2: Extract Functions
- Break large functions < 50 lines
- Extract reusable utilities
- Add unit tests

## Phase 3: Modernize
- Convert to async/await
- Use modern JS features
- Update dependencies

Rule Validation

Common Issues to Avoid

Over-Specification

Don’t create rules for every tiny detail - focus on important patterns

Contradictions

Ensure rules don’t conflict with each other or existing tools

Outdated Rules

Review and update rules quarterly as your project evolves

Vague Instructions

Replace “write clean code” with specific, measurable guidelines

Testing Your Rules

1. Create Test Scenario:

   "Create a new API endpoint for user profiles"

2. Verify AI Follows Rules:

   • Check code style compliance
   • Verify architecture patterns
   • Confirm testing approach

3. Iterate if Needed:

   • Clarify ambiguous rules
   • Add missing examples
   • Remove ineffective rules

Team Collaboration

Sharing Rules

1. Commit to Git:

   git add .cursor/rules/
   git commit -m "Add project coding standards"
   git push

2. Document in README:

   ## AI Coding Standards
   
   This project uses Cursor rules for consistent AI assistance.
   Rules are in `.cursor/rules/` and automatically apply.
   
   To update rules:
   1. Edit relevant `.mdc` files
   2. Test with AI
   3. Commit changes

3. Regular Reviews:

   • Monthly rule review meetings
   • Track rule effectiveness
   • Update based on team feedback

Next Steps

Continue to PRD Workflow

Now let’s master the PRD → Plan → Todo workflow that transforms how you build features.

PRD Workflow →

Time: 15 minutes

Wskazówka

Achievement Unlocked: Your AI now understands your project’s standards and will generate consistent, high-quality code aligned with your team’s practices.