Cursor AI Prompting — Why Migrations Drop Data by Default

# ============================================
# .cursorrules — Cursor AI Project Context
# ============================================

# ---- Technology Stack ----
Project: SaaS Analytics Platform
Framework: Next.js 16 with App Router
Language: TypeScript (strict mode)
Database: PostgreSQL with Prisma ORM
Auth: NextAuth.js with JWT
Payments: Stripe
Styling: Tailwind CSS with shadcn/ui
State Management: Zustand for client state, React Query for server state
Testing: Vitest + React Testing Library

# ---- Coding Standards ----
- Use TypeScript strict mode — never use `any` type
- All API routes return JSON with { data, error } shape
- Use Zod for input validation on all API routes
- Use Prisma for all database access — never raw SQL
- Error messages must be user-safe — no stack traces in responses
- All dates in UTC — format on the client side
- Use named exports (EXCEPT Next.js page.tsx, layout.tsx, and route.ts files which require default exports)
- Functions should be under 30 lines — extract helpers for complex logic
- Use async/await — no .then() chains
- Prefer composition over inheritance

# ---- File Structure ----
- app/ for Next.js routes (App Router)
- app/api/ for API route handlers
- components/ui/ for shadcn/ui components (do not modify)
- components/ for feature components
- lib/ for shared utilities and clients
- types/ for TypeScript interfaces and types
- hooks/ for custom React hooks
- prisma/ for database schema and migrations
- __tests__/ for test files

# ---- Naming Conventions ----
- Files: kebab-case
- Components: PascalCase
- Functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Database tables: snake_case

# ---- Domain-Specific Rules ----
- Subscription logic must handle trialing, active, past_due, and canceled states
- All monetary values stored as cents (integers) — never floats
- Rate limiting required on all public API endpoints
- Webhook handlers must be idempotent
- User data must be scoped by organization_id

# ---- What NOT to do ----
- Do not generate code with com.example or placeholder names
- Do not use useEffect for data fetching — use React Query or server components
- Minimize barrel files (index.ts re-exports) except for clean public APIs (e.g. lib/stripe/index.ts)
- Do not use CSS modules — use Tailwind CSS utilities
- Do not store secrets in code — use environment variables

# .cursorignore — Prevent sensitive files from being sent to Cursor servers
.env
.env.local
.env.*
*.pem
*.key
*.crt
prisma/migrations/
node_modules/
.next/
.git/
dist/
build/

// ============================================
// Composer Mode: Effective Prompting Patterns
// ============================================

// ---- Pattern 1: Feature Generation ----
/* PROMPT:
Create a user profile update feature.

Requirements:
- API route at app/api/user/profile/route.ts that accepts PUT requests
- Validates input with Zod: name (2-50 chars), bio (max 500 chars), avatarUrl (optional URL)
- Updates the user record in Prisma
- Returns { data: updatedUser, error: null } on success
- Returns { data: null, error: message } on validation failure
- Requires authentication via getServerSession

Also create:
- A Zod schema in types/user.ts for the update input
- A React component in components/profile/edit-profile-form.tsx using shadcn/ui Form
- Wire the form to the API route with react-hook-form

Conventions:
- Follow the existing API route pattern in app/api/
- Use the existing auth pattern from app/api/auth/
- Match the shadcn/ui form pattern from components/forms/
*/

// ---- Pattern 2: Refactoring ----
/* PROMPT:
Refactor the payment processing logic.

Currently:
- lib/stripe.ts has all payment logic in one file (280 lines)

Refactor into:
- lib/stripe/checkout.ts — checkout session creation
- lib/stripe/subscriptions.ts — subscription CRUD operations
- lib/stripe/webhooks.ts — webhook event handling
- lib/stripe/client.ts — shared Stripe client initialization

Constraints:
- Preserve all existing function signatures — do not change the public API
- Update all import statements in files that reference lib/stripe.ts
- Do not change any business logic — only move code
- Add a clean public API export in lib/stripe/index.ts for backward compatibility
*/

// ---- Pattern 3: Bug Fix with Context ----
/* PROMPT:
Fix the subscription status bug.

Symptom: Users with canceled subscriptions still see Pro features.

Context:
- The subscription check is in lib/auth.ts getServerSession callback
- The subscription status is stored in the subscriptions table
- The dashboard reads subscription status from the session
- Stripe webhook at app/api/webhooks/stripe/route.ts updates the status

Hypothesis: The webhook updates the status, but the JWT token is not refreshed.
The session still contains the old subscription status until the token expires.

Fix:
- In the JWT callback, fetch the current subscription status from the database
- Do not rely on the cached JWT claim for subscription status
- Add a revalidation endpoint that forces a session refresh
*/

// ============================================
// Context Control: @ Symbol Strategy
// ============================================

// ---- Context Hierarchy ----
//
// Symbol         | Scope              | Use When
// ---------------|--------------------|-------------------------------------------
// @file          | Single file        | Modifying one file, need its current code
// @folder        | Directory          | Working within a feature module
// @codebase      | Entire project     | Cross-cutting changes, understanding patterns
// @web           | Internet search    | Need latest API docs, library updates
// @git           | Git history        | Understanding why code was written this way

// ---- When to Use Each ----

// USE @file WHEN:
// - Fixing a bug in a specific file
// Example prompt:
//   @file app/api/users/route.ts
//   Add input validation using Zod for the POST handler.

// USE @folder WHEN:
// - Adding a new feature within a module
// Example prompt:
//   @folder app/api/subscriptions/
//   Add a DELETE endpoint that cancels a subscription.

// USE @codebase WHEN:
// - Making changes that affect multiple modules
// Example prompt:
//   @codebase
//   Find all places where the deprecated calculatePrice function is used.

// ---- Context Optimization ----
//
// BAD: Using @codebase for everything
// GOOD: Graduated context
//   - Start with @file for the specific file
//   - Add @folder if the change spans a module
//   - Use @codebase only for cross-cutting concerns

// ============================================
// Cmd+K: Inline Editing Patterns
// ============================================

// ---- Pattern 1: Quick Refactor ----
// Select a function, describe the improvement

// BEFORE: Select this function and press Cmd+K
function calculateTotal(items: any[]) {
  let total = 0
  for (let i = 0; i < items.length; i++) {
    total = total + items[i].price * items[i].quantity
  }
  return total
}

// CMD+K PROMPT:
// "Refactor to use reduce. Add TypeScript types. Handle null items."

// AFTER: Cursor generates
interface LineItem {
  price: number
  quantity: number
}

function calculateTotal(items: LineItem[]): number {
  return items.reduce((total, item) => {
    if (!item) return total
    return total + item.price * item.quantity
  }, 0)
}

// ---- Pattern 2: Error Handling ----
// Select a try-catch block, improve error handling

// BEFORE: Select this block and press Cmd+K
try {
  const response = await fetch('/api/users')
  const data = await response.json()
  setUsers(data)
} catch (e) {
  console.log(e)
}

// CMD+K PROMPT:
// "Add proper error handling. Check response status.
// Show user-friendly error toast. Type the catch error."

// AFTER: Cursor generates
try {
  const response = await fetch('/api/users')

  if (!response.ok) {
    const error = await response.json()
    throw new Error(error.message ?? 'Failed to fetch users')
  }

  const data: User[] = await response.json()
  setUsers(data)
} catch (error) {
  const message = error instanceof Error ? error.message : 'An unexpected error occurred'
  toast.error(message)
  console.error('Failed to fetch users:', error)
}

// ---- When to Use Cmd+K vs Composer ----
//
// USE Cmd+K:                    USE Composer:
// - Single file changes         - Multi-file changes
// - One function or block       - New features
// - Quick refactors             - Complex refactors
// RULE OF THUMB:
// - If it touches one file → Cmd+K
// - If it touches 2+ files → Composer

// ============================================
// Advanced Prompting: The Five-Part Formula
// ============================================

// ---- The Formula ----
//
// 1. GOAL:      What you want to build or fix
// 2. CONTEXT:   Relevant files, patterns, existing code
// 3. CONSTRAINTS: Types, validation, auth, error handling
// 4. OUTPUT:    Expected format, file locations, naming
// 5. ANTI-PATTERNS: What to avoid

// ---- Example: Building an API Endpoint ----

/* GOAL:
Create a REST API endpoint for managing team invitations.

CONTEXT:
- Existing auth pattern: @file app/api/auth/[...nextauth]/route.ts
- Existing team model: @file prisma/schema.prisma (Team, TeamMember models)
- Existing email service: @file lib/email/send.ts
- API response pattern: all routes return { data, error } shape

CONSTRAINTS:
- POST /api/teams/[teamId]/invite
- Requires authentication (getServerSession)
- Requires team owner role (check team.members for owner role)
- Input validation with Zod: email (valid format), role (enum: member, admin)
- Rate limit: max 10 invites per team per day
- Send invitation email via existing email service
- Store invitation in database with 7-day expiry

OUTPUT:
- Route handler in app/api/teams/[teamId]/invite/route.ts
- Zod schema in types/team-invitation.ts
- Use existing email template from lib/email/templates/invite.ts
- Follow the existing API error pattern from app/api/users/route.ts

ANTI-PATTERNS:
- Do not use any type — define proper interfaces
- Do not skip authentication — every route must check session
- Do not return stack traces in error responses
- Do not use raw SQL — use Prisma for all database operations
- Do not create a new email sending function — use the existing one
*/

// ============================================
// Real-World Cursor Workflows
// ============================================

// ---- Workflow 1: Feature Development ----
//
// Step 1: Plan in chat
// Step 2: Generate with Composer (Cmd + I)
// Step 3: Review and fix with Cmd+K
// Step 4: Test with Composer
// Step 5: Commit with Cursor

// ---- Workflow 2: Bug Fixing ----
//
// Step 1: Reproduce and describe
// Step 2: Hypothesize
// Step 3: Fix with Composer
// Step 4: Verify

// ---- Workflow 3: Code Review ----
//
// Step 1: Select code to review
// Step 2: Ask Cursor to review
// Step 3: Apply fixes with Cmd+K

// ---- Workflow 4: Refactoring ----
//
// Step 1: Understand the current code
// Step 2: Plan the refactoring
// Step 3: Execute with Composer
// Step 4: Verify with tests

// ============================================
// Cursor vs GitHub Copilot: Feature Comparison
// ============================================

// ---- Context Scope ----
//
// Copilot: Current file only
// Cursor: Full project via @codebase

// ---- Interaction Model ----
//
// Copilot: Inline suggestions (Tab to accept)
// Cursor: Composer (multi-file) + Cmd+K (inline editing)

// ---- Best Use Cases ----
//
// USE COPILOT WHEN:
//   - Writing boilerplate code
//   - Completing a line or function you started typing
//
// USE CURSOR WHEN:
//   - Building a new feature across multiple files
//   - Refactoring code that spans multiple modules
//   - Debugging complex issues

// ---- Can You Use Both? ----
// YES. Cursor supports Copilot-style inline suggestions.
// Enable Copilot in Cursor settings for the best of both worlds.