Configure Windsurf across development, staging, and production environments.
Use when setting up multi-environment deployments, configuring per-environment secrets,
or implementing environment-specific Windsurf configurations.
Trigger with phrases like "windsurf environments", "windsurf staging",
"windsurf dev prod", "windsurf environment setup", "windsurf config by env".
Configure Windsurf consistently across team members, projects, and deployment contexts. Windsurf is an IDE, not a cloud API -- "multi-environment setup" means standardizing AI behavior, workspace configuration, and Cascade context across your team.
Prerequisites
Windsurf IDE installed on developer machines
Shared git repository
Team agreement on coding standards per service
Instructions
Step 1: Per-Project Cascade Rules
<!-- .windsurfrules - committed to each service repo -->
# Project: PaymentService
## Stack
- Language: TypeScript (strict)
- Framework: Fastify v4
- Database: PostgreSQL with Drizzle
- Testing: Vitest
- Queue: BullMQ for async jobs
## 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
- PCI-sensitive data only in src/pci/ (encrypted at rest)
## Naming Conventions
- Route handlers: GET/POST/PUT/DELETE prefix
- Service methods: verb + noun (createPayment, findOrder)
- Repository methods: DB operations (findById, upsert)
Key practice: Each developer opens their service directory as the workspace, NOT the monorepo root. This gives Cascade focused context and fast indexing.
Step 4: Environment-Specific Workflow Rules
<!-- .windsurf/rules/deployment-context.md -->
---
trigger: glob
globs: deploy/**, scripts/deploy-*, .github/workflows/deploy-*
---
## Deployment Rules
- Target: AWS ECS on us-east-1
- Container registry: 123456789.dkr.ecr.us-east-1.amazonaws.com
- Secrets: AWS Secrets Manager (prefix: myapp/{environment}/)
- Never hardcode environment-specific values
- All environment config via ENV vars, not config files
- Staging deploys from develop branch, production from main
Step 5: Onboarding Script
#!/bin/bash
# scripts/setup-windsurf.sh
set -euo pipefail
echo "Setting up Windsurf for this project..."
# Verify Windsurf installation
windsurf --version || { echo "Install Windsurf: https://windsurf.com/download"; exit 1; }
# Install recommended extensions
windsurf --install-extension esbenp.prettier-vscode
windsurf --install-extension dbaeumer.vscode-eslint
# Disable conflicting extensions
windsurf --disable-extension github.copilot 2>/dev/null || true
windsurf --disable-extension tabnine.tabnine-vscode 2>/dev/null || true
# Verify configuration
[ -f ".windsurfrules" ] || echo "WARNING: .windsurfrules not found"
[ -f ".codeiumignore" ] || echo "WARNING: .codeiumignore not found"
echo ""
echo "Setup complete."
echo "IMPORTANT: Open your service directory (not monorepo root) for best Cascade performance."
echo "Example: windsurf services/payments/"
