Windsurf Multi Env Setup

Windsurf Multi-Environment Setup

Overview

Windsurf is an IDE, not a cloud API -- "multi-environment setup" means configuring Cascade AI context and behavior consistently across team members, projects, and deployment targets. The key configuration files are .windsurfrules (AI context per project), .windsurf/settings.json (IDE preferences), and .windsurfignore (indexing exclusions).

Prerequisites

• Windsurf IDE installed on developer machines
• Shared git repository for .windsurfrules and team config templates
• Team agreement on coding standards per service

Configuration Strategy

Instructions

Step 1: Per-Project Cascade Rules

<!-- .windsurfrules - Committed to repo root -->

# Project: PaymentService

## Stack
- Language: TypeScript (strict)
- Framework: Fastify v4
- Database: PostgreSQL with Prisma
- Testing: Vitest

## Architecture Rules
- All handlers in src/routes/ - never business logic
- Business logic in src/services/ only
- Database queries in src/repositories/ only
- Use Result<T, E> pattern for errors, never throw in services

## Naming Conventions
- Route handlers: GET/POST/PUT/DELETE prefix
- Service methods: verb + noun (createUser, findOrder)
- Repository methods: db operations (findById, upsert)

## Testing Requirements
- Unit tests for all service methods
- Integration tests for all route handlers
- No mocking of repositories in integration tests

Step 2: Team-Wide IDE Settings Template

{
  "codeium.indexing.excludePatterns": [
    "node_modules/**",
    "dist/**",
    ".next/**",
    "coverage/**",
    "*.min.js",
    "**/*.map",
    "**/*.lock"
  ],
  "codeium.autocomplete.enable": true,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.tsdk": "node_modules/typescript/lib",
  "codeium.chat.preferredModel": "claude-sonnet"
}

Store as .windsurf/settings.json and commit. Developers can extend with personal overrides in their local settings.

Step 3: Monorepo Multi-Service Setup

# Each service gets its own .windsurfrules
monorepo/
  services/
    auth/
      .windsurfrules    # Auth service context (JWT, OAuth flows)
      .windsurfignore
    payments/
      .windsurfrules    # Payments context (Stripe, PCI rules)
      .windsurfignore
    notifications/
      .windsurfrules    # Notification context (queues, templates)
      .windsurfignore
  .windsurf/
    settings.json       # Shared IDE settings
    team-config.md      # Team usage guidelines

Step 4: Onboarding Script for New Developers

#!/bin/bash
# scripts/setup-windsurf.sh

echo "Setting up Windsurf for this project..."

# Install recommended extensions
windsurf --install-extension esbenp.prettier-vscode
windsurf --install-extension dbaeumer.vscode-eslint

# Verify .windsurfrules exists
if [ ! -f ".windsurfrules" ]; then
  echo "WARNING: .windsurfrules not found. Cascade will lack project context."
fi

# Set Codeium API key if provided
if [ -n "$CODEIUM_API_KEY" ]; then
  windsurf --set "codeium.apiKey" "$CODEIUM_API_KEY"
fi

echo "Windsurf setup complete. Open your service directory (not the monorepo root) for best Cascade performance."

Step 5: CI Environment for Cascade Batch Tasks

# .github/workflows/cascade-tasks.yml
# Run Windsurf Cascade in headless mode for automated tasks
name: Cascade Automation
on: workflow_dispatch
  inputs:
    task:
      description: "Cascade task to run"

jobs:
  cascade:
    runs-on: ubuntu-latest
    env:
      CODEIUM_API_KEY: ${{ secrets.CODEIUM_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Run Cascade task
        run: windsurf --cascade --task "${{ inputs.task }}" --output cascade-output.md

Error Handling

Examples

Quick Project Health Check

# Verify Windsurf config is in place
ls -la .windsurfrules .windsurfignore .windsurf/settings.json

Per-Environment .windsurfrules

<!-- For staging/production deployment scripts -->
# Deployment Context
- Target: AWS ECS on us-east-1
- Container registry: 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp
- Secrets: AWS Secrets Manager (prefix: myapp/production/)
- Do NOT hardcode credentials or environment-specific values

Resources

• Windsurf Rules Documentation
• Codeium Team Configuration
• Windsurf IDE Documentation

Next Steps

For architecture best practices, see windsurf-reference-architecture.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale