My ./.cursor/rules template

001-follow-rules.mdc

---
description: How to use Cursor rules effectively - READ THIS FIRST for any project work
globs: 
alwaysApply: true
---

# Understanding Rules

Rules are your project-specific knowledge base. They guide your decision-making with context that doesn't exist in code alone. **ALWAYS CHECK FOR RELEVANT RULES** when making decisions.

## Why Rules Matter

Rules capture:

1. **Business Logic**: Critical formulas and definitions that must be consistent
2. **Technical Constraints**: Architectural choices, optimizations and limitations
3. **Data Patterns**: Naming conventions and structure reflecting business domains
4. **Troubleshooting Knowledge**: Common issues and their solutions

## How to Use Rules Effectively

### 1. Actively Search for Relevant Rules

**ALWAYS** look for relevant rules before making decisions. Use these methods:

```bash
# Method 1: Check all rule titles to understand what's available
ls .cursor/rules/

# Method 2: Search for topic-specific rules
grep -l "duckdb" .cursor/rules/*.mdc
grep -l "subscription" .cursor/rules/*.mdc
```

### 2. Understand Rule Priority

Rules are organized by importance with numeric prefixes:
- **000-099**: Fundamental project principles (ALWAYS reference these)
- **100-199**: Core business context, logic and patterns
- **200-299**: Architecture, coding guidelines= & implementation details
- **300-399**: Testing, Troubleshooting and Debugging
- **400-499**: Integrations with external systems
- **500+**: Folder, Library & Tool-specific guidance

### 3. Interpret Front-matter

At the top of each rule is front-matter which aides in rule understanding and application. It uses the following format:
```
---
description: Brief purpose of the rule
globs: File patterns where rule applies
alwaysApply: Whether rule applies globally
---
```

- If `globs` is empty but `alwaysApply: true` → Rule applies to all decisions
- If `globs` matches current files → Rule is directly relevant
- If `alwaysApply: false` and `globs` doesn't match → Consider as general guidance

### 4. Apply Rules Contextually, Not Mechanically

Rules are thoughtful, clear guidance, not rigid, absolute statements (unless noted specifically). When applying rules:

1. Extract key principles, guardrails and motivations
2. Apply the principles to your specific situation
3. Balance multiple rules when they both apply
4. Prioritize rules that match the current task most directly
5. Resolve conflicts using the rules below

### 5. Rule Conflicts Resolution

When rules appear to conflict:
1. Rules with more specific `globs` override more general rules
2. Rules with higher numbers (900-999) override lower counterparts numbered rules
3. Technical approaches 
4. When truly ambiguous, explain the conflict and recommend the approach that aligns most with business requirements

## Example: Using Rules for a pydantic Model Change

When modifying a database model:

1. First, check `-models.mdc` rules to understand the appropriate model layer
2. Next, check `-business-logic-standards.mdc` for domain-specific formulas
3. Then, check `-db-optimization.mdc` for performance considerations
4. Finally, consult troubleshooting rules if you encounter issues

This approach ensures you respect both business requirements and technical constraints.

## Remember

The value of rules is not in following them blindly, but in understanding why they exist and applying that understanding to make better decisions that align with project goals.

002-write-rules.mdc

---
description: How to write effective rules that guide AI agents - for rule authors
globs: .cursor/rules/*.mdc
alwaysApply: false
---

# Writing Effective Rules for AI Agents

Creating rules for AI agents is fundamentally different from writing documentation for humans. This guide explains how to write rules that truly guide decision-making rather than merely documenting practices.

## Key Principles for AI-Effective Rules

### 1. Focus on Decision Guidance, Not Documentation

**BAD:**

```
# Code Style: Always use 4 spaces for indentation in Python files
```

**GOOD:**

```
# When editing Python files, maintain consistent 4-space indentation to reduce merge conflicts and improve readability in our legacy codebase
```

The difference: The good example explains *why* (context) and *what problem it solves* (motivation), not just *what* to do.

### 2. Provide Context and Motivation

Rules should always explain:

- **Why** this approach matters for this specific project
- **What problems** it solves or prevents
- **When** the guidance is most critical to apply
- **How** it relates to business or technical goals

### 3. Target the Agent's Decision-Making Process

Agents need:

- Clear prioritization frameworks
- Troubleshooting paths with decision trees
- Contextual information for making tradeoffs
- Understanding of consequences and impact

They don't need:

- General best practices without context
- Detailed formatting guides
- Explanations of industry standards

### 4. Use Action-Oriented Language

**BAD:**

```
# Documentation best practices suggest that...
```

**GOOD:**

```
# When adding a new model, first check SPEC.md for business requirements, then...
```

The difference: The good example provides clear, actionable steps with an implied sequence.

### 5. Include Examples of Decision Processes

**BAD:**

```
# Dimension tables should be properly documented
```

**GOOD:**

```
# When creating dimension tables, consider:
# 1. What business entities does this represent?
# 2. Which fields are required for joins vs. analysis?
# 3. Will this dimension need historical tracking (SCD)?
# 
# Example reasoning: dim_users captures member profiles where:
# - user_id serves as the primary join key
# - tier_category impacts pricing analysis
# - registration_date is critical for cohort analysis
```

The difference: The good example models the thinking process, not just the outcome.

## Front-matter Best Practices

### Make Descriptions Actionable

**BAD:**

```
description: SQL style guidelines
```

**GOOD:**

```
description: How to optimize SQL for MotherDuck performance - apply when writing queries
```

The difference: The good example explains when and why to apply the rule.

### Target Globs Precisely

**BAD:**

```
globs: **/*.py
alwaysApply: true
```

**GOOD:**

```
globs: models/warehouse/**/*.sql
alwaysApply: false
```

The difference: The good example precisely targets where the guidance is most relevant.

## Rule Content Structure

1. **Start with context**: Briefly explain the domain and why it matters
2. **Highlight critical principles**: Lead with the most important guidance
3. **Provide decision frameworks**: Help prioritize competing concerns
4. **Include realistic examples**: Show applied reasoning, not just code
5. **Address tradeoffs**: Acknowledge when guidelines might conflict

## Examples of Effective vs. Ineffective Rules

### Ineffective Rule (Style Guide Approach)

```
# Python Coding Standards
Use snake_case for variable names.
Follow PEP8 formatting.
Add docstrings to all functions.
```

### Effective Rule (Decision Guidance Approach)

```
# Working with the Payment Processing Module

The payment module interfaces with Stripe and our membership database.
When modifying this code:

1. First verify which payment processor is involved (Stripe/legacy)
2. Payment failures should be explicitly logged with detailed error codes
3. All subscription changes must update both Stripe AND local membership tables
4. Test with the sandbox credentials from .env.example

Common failure patterns:
- Mismatched subscription IDs between systems (check both tables)
- Webhook processing timeouts (implement idempotency)
- Payment intent status edge cases (verify 'requires_action' handling)
```

The effective rule provides contextual understanding and addresses real concerns that guide decision-making, not just style preferences.

## Remember

Great rules guide agents to make the same decisions a knowledgeable human would make, by providing the context, motivation, and decision frameworks that humans accumulate through experience.