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.

// io.thecodeforge — javascript tutorial

// Before: blind accept — one hallucination deploys
// After: toggle this setting in Cursor

// .cursor/config.json (manual)
{
  "composer": {
    "requireDiffReview": true,
    "autoApply": false
  }
}

// Workflow in code: never trust the diff you don't see
async function applySuggestion(modelResponse, filePath) {
  // This simulates what Cursor does internally — DON'T skip review
  const diff = generateDiff(await readFile(filePath), modelResponse);
  
  // Real devs: this is where you STOP and look
  const approved = await promptUser(`Review changes for ${filePath}:\n${diff}`);
  
  if (!approved) {
    console.warn('Blocked hallucination from reaching disk', filePath);
    return;
  }
  await writeFile(filePath, modelResponse);
  console.log('Applied after human verification');
}

// io.thecodeforge — javascript tutorial

// .cursorignore — protect the surface area you own
*.migration.js
*.interface.ts
.env*
docker-compose*

// Real-world: lock your API contracts
import express from 'express';
const router = express.Router();

// This file is LOCKED — Cursor cannot touch it
// WHY: changing this route signature cascades to 12 frontend API hooks
router.get('/api/users/:id/profile', async (req, res) => {
  const profile = await userService.getProfile(req.params.id);
  // Locked: never let AI guess the response shape
  res.json(profile);
});

// Instead, let Cursor work here: safe to modify
router.post('/api/users/:id/feedback', async (req, res) => {
  // Only this handler touches a single service
  const result = await feedbackService.add(req.params.id, req.body);
  res.status(201).json(result);
});

// io.thecodeforge — javascript tutorial

// Ask in Cursor composer or chat panel:
// "Find all places that call validateToken()"

// Cursor returns:
// ./src/middleware/auth.js:22
// ./src/routes/user.js:45
// ./src/routes/admin.js:12

// Follow-up query:
// "Show me the validateToken implementation"

// Cursor shows:
function validateToken(token) {
  return jwt.verify(token, process.env.JWT_SECRET);
}

// io.thecodeforge — javascript tutorial

// BAD: Vague prompt with no context
// "Fix the login bug"

// GOOD: Atomic prompts, open file first
// Step 1: Open src/controllers/auth.js
// Prompt: "Add try-catch to the login function"

// Step 2: Review diff via Cmd+I
// Step 3: Accept only clean changes

// Always check for:
// - eval() calls
// - process.env hardcoded defaults
// - missing return statements

// io.thecodeforge — javascript tutorial
function processOrder(order) {
  if (!order.items || order.items.length === 0) {
    throw new Error('Order must have items');
  }
  const total = order.items.reduce((sum, item) => sum + item.price * item.qty, 0);
  if (total > 1000) {
    console.warn('High-value order:', order.id);
  }
  return { status: 'processed', total };
}
// Ask Cursor: "Add discount logic for orders over $500"

// io.thecodeforge — javascript tutorial
/**
 * Fetches user data from API.
 * @param {number} id - User ID
 * @returns {Promise<{name: string, email: string}>}
 */
async function fetchUser(id) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  return res.json();
}
// Type @docs to make this searchable via Cursor chat

// io.thecodeforge — javascript tutorial
function Car(make, model) {
  this.make = make;
  this.model = model;
}
Car.prototype.getInfo = function() {
  return `${this.make} ${this.model}`;
};
const myCar = new Car('Tesla', 'Model 3');
console.log(myCar.getInfo());
// Prototype chain: myCar -> Car.prototype -> Object.prototype