Setting Up Your AI-Augmented Workflow

# Install Cursor
# Download from cursor.sh or:
brew install --cask cursor   # macOS

# Your VS Code settings automatically import on first launch
# Verify by checking: Cmd+Shift+P → "Cursor Settings"

// settings.json -- Cursor-specific settings
{
  // AI-specific
  "cursor.ai.model": "claude-sonnet-4-20250514",
  "cursor.ai.enableTab": true,
  "cursor.ai.tabSuggestionDelay": 200,

  // Codebase indexing -- CRITICAL for context quality
  "cursor.ai.indexOnStartup": true,
  "cursor.ai.indexIgnorePatterns": [
    "node_modules/**",
    "dist/**",
    "build/**",
    ".next/**",
    "*.min.js",
    "*.lock",
    "coverage/**"
  ],

  // General quality-of-life
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "non-relative"
}

# Install Copilot extensions
code --install-extension GitHub.copilot
code --install-extension GitHub.copilot-chat

# Recommended companion extensions for AI-augmented workflow:
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension eamodio.gitlens

{
  "github.copilot.enable": {
    "*": true,
    "markdown": true,
    "yaml": true
  },
  "github.copilot.advanced": {
    "length": 500,
    "temperature": "",
    "inlineSuggestCount": 3
  },
  // Keybinding tip: Alt+] and Alt+[ cycle through suggestions
  // Tab accepts, Escape dismisses
}

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Verify installation
claude --version

# First run -- authenticates and sets up
claude

# Recommended: Create a shell alias for quick access
echo 'alias cc="claude"' >> ~/.zshrc

# For Vim/Neovim users, add Copilot for inline completions:
# In your init.lua or .vimrc:
# Plug 'github/copilot.vim'

# Set your preferred model
claude config set model claude-sonnet-4-20250514

# Set permission mode (how much autonomy Claude Code gets)
# "ask" = asks before every file write and command
# "auto" = auto-approves safe operations
claude config set permissions auto

# Set your preferred editor for when Claude Code needs you to review
claude config set editor vim

# CLAUDE.md

## Project Overview
E-commerce platform backend. Node.js/TypeScript monorepo with Express API,
PostgreSQL via Prisma, Redis for caching and queues, deployed on AWS ECS.

## Architecture

### Service Boundaries
- `packages/api/` -- REST API (Express + TypeScript)
- `packages/worker/` -- Background job processor (Bull + Redis)
- `packages/shared/` -- Shared types, utilities, validators
- `packages/db/` -- Prisma schema and migrations

### Key Dependencies
- Express 4.18 (NOT v5 -- we're waiting for stable release)
- Prisma 5.x with PostgreSQL 15
- Bull 4.x for job queues
- Zod 3.x for runtime validation
- Vitest for testing

## Commands
```bash
npm run dev           # Start all services
npm run test          # Run all tests
npm run test:unit     # Unit tests only
npm run test:int      # Integration tests (needs Docker)
npm run lint          # ESLint + Prettier check
npm run db:migrate    # Run pending migrations
npm run db:generate   # Regenerate Prisma client
npm run db:seed       # Seed development data

### .cursorrules -- For Cursor

```markdown
# .cursorrules

You are an expert TypeScript/Node.js developer working on an e-commerce
platform backend. Follow these conventions strictly:

## Response Format
- When modifying existing code, show only the changed sections with
  enough context to locate the change
- When creating new files, show the complete file
- Always include necessary imports
- Add JSDoc comments for exported functions

## Code Style
- Use `const` by default, `let` only when reassignment is necessary
- Prefer early returns over nested conditionals
- Maximum function length: 30 lines (extract helpers)
- Use descriptive variable names -- no single-letter names except
  loop indices and lambda parameters

## TypeScript Specifics
- Use strict null checks -- always handle null/undefined explicitly
- Prefer discriminated unions over optional fields for state
- Use `as const` for literal types
- Generic type parameters: T for main type, K for keys, V for values

## When Writing Tests
- Use Vitest (not Jest -- similar API but different imports)
- Structure: describe → it → arrange/act/assert
- Use factories for test data, never raw object literals
- Mock external services, never databases in unit tests

## When Writing Database Code
- Use Prisma's typed queries -- never raw SQL unless for performance
- Always use transactions for multi-table mutations
- Include `select` clauses to avoid over-fetching
- Handle unique constraint violations explicitly

## What NOT to Do
- Never use `any` type -- use `unknown` and narrow
- Never use `console.log` -- use the structured logger
- Never commit `.env` files or secrets
- Never use synchronous file I/O in request handlers

# Copilot Instructions

This is a TypeScript monorepo for an e-commerce platform.

## Key Conventions
- All API responses use the envelope format: { data, meta? }
- Use Zod for validation, Prisma for database access
- Errors are custom classes extending AppError
- Tests use Vitest with the describe/it pattern

## Libraries
- Express 4.18 (NOT v5)
- Prisma 5.x
- Zod 3.x
- Vitest (NOT Jest)
- Bull 4.x for queues

## Patterns to Follow
- Repository pattern for data access
- Result<T,E> for error handling in utilities
- Cursor-based pagination
- Structured logging with pino

# Mental model for choosing a model:

def choose_model(task: dict) -> str:
    if task["requires_large_context"]:
        # Reading 50+ files, understanding full codebase
        return "gemini-2.5-pro"  # 1M context

    if task["requires_deep_reasoning"]:
        # Architecture decisions, complex debugging,
        # multi-step planning
        return "claude-opus-4"  # or "o3"

    if task["requires_privacy"]:
        # Proprietary code that can't leave your network
        return "llama-3.3-70b"  # self-hosted

    if task["is_routine"]:
        # CRUD, tests, boilerplate, quick edits
        return "claude-sonnet-4"  # fast + good enough

    # Default: start with Sonnet, escalate to Opus if needed
    return "claude-sonnet-4"

Cursor Chat: Click the model selector dropdown
  → claude-sonnet-4-20250514 for most tasks
  → claude-opus-4-20250514 for complex reasoning
  → gpt-4o for when you want a different perspective

# Use @ references to include specific context:

@api/routes/users.ts @db/repositories/userRepo.ts
Add a "deactivate user" endpoint that:
1. Sets user.active = false
2. Revokes all active sessions
3. Cancels pending orders
4. Sends notification email via the job queue

# Claude Code can explore your codebase, but you can guide it:

$ claude

> Read the files in src/auth/ and src/middleware/ to understand
> our current authentication flow. Then add support for API key
> authentication alongside the existing JWT flow. API keys should
> be stored hashed in the database and support scoping (read-only,
> read-write, admin).

# Always create a feature branch for AI-assisted work
git checkout -b feat/add-rate-limiting

# Make AI-assisted changes
# Review ALL changes carefully (git diff)
git diff

# Stage selectively -- don't blindly git add -A
git add -p   # Interactive staging lets you review each hunk

# Write descriptive commit messages (AI can help here too)
git commit -m "feat(api): add sliding window rate limiting

- Redis-backed sliding window counter per API key
- 100 req/min limit with configurable override per key
- X-RateLimit headers in all responses
- Graceful degradation on Redis failure (fail-open with logging)

Co-authored-by: Claude <noreply@anthropic.com>"

# .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# Type check -- catches hallucinated APIs
npx tsc --noEmit

# Lint -- catches style violations
npx eslint --max-warnings 0 .

# Test -- catches logic errors
npm run test:unit

# Security check
npx audit-ci --moderate

// package.json
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.test.{ts,tsx}": [
      "vitest related --run"
    ]
  }
}

1. Review PRs with AI assistance
   → Claude Code: "Review the diff in PR #234 for security issues,
      performance problems, and style violations"

2. Plan the day's implementation
   → Cursor Agent: "I need to implement feature X.
      What files need to change and in what order?"

3. Write code with inline completions
   → Copilot/Cursor Tab handles boilerplate as you type

4. Complex implementations with agent mode
   → Cursor Agent or Claude Code for multi-file changes

5. Test generation
   → "Generate tests for the UserService.deactivate method
      covering: success, user not found, already deactivated,
      database error, partial failure in session revocation"

6. Self-review with AI
   → "Review my changes today. Focus on: error handling
      completeness, test coverage gaps, performance implications"

7. Documentation updates
   → "Update the API documentation to include the new
      rate-limiting headers and deactivation endpoint"

8. Commit and PR preparation
   → "Write a PR description summarizing the changes,
      motivation, and testing approach"

Default: Accept all suggestions automatically
Better:  Review each suggestion, use Tab selectively

Default: Use the fastest model for everything
Better:  Route complex tasks to stronger models

Default: Include all files in context
Better:  Configure ignore patterns for generated files, node_modules, builds

Week 1: Track tasks where AI helped vs. where you had to fix AI output
Week 2: Update .cursorrules/CLAUDE.md based on common corrections
Week 3: Refine your prompting patterns based on what worked
Week 4: Share learnings with your team and update shared configuration