windsurf-sdk-patterns

# Windsurf Configuration Patterns ## Overview Production-ready configuration patterns for Windsurf IDE: rules files, workspace rules with trigger modes, MCP server integration, and Cascade prompt engineering. ## Prerequisites - Windsurf authenticated and operational - Understanding of Cascade Write vs Chat modes - Project with established coding conventions ## Instructions ### Step 1: Root-Level .windsurfrules (Permanent Context) The `.windsurfrules` file is the single highest-impact configuration for Cascade output quality. It provides persistent context every session. ```markdown <!-- .windsurfrules --> # Project: payments-api ## Stack - Runtime: Node.js 20 LTS - Language: TypeScript 5.x (strict, noUncheckedIndexedAccess) - Framework: Fastify v4 - ORM: Drizzle (PostgreSQL) - Validation: zod - Testing: Vitest - Linting: Biome ## Architecture Rules - Route handlers in src/routes/ — no business logic - Business logic in src/services/ — never throw, use Result<T,E> - Database queries in src/repositories/ — Drizzle only - Shared types in src/types/ — all exported with JSDoc ## Don't - Don't use `any` type - Don't use default exports - Don't use class-based patterns (use functions + closures) - Don't modify files in migrations/ without explicit request - Don't use deprecated APIs: my_old_helper, legacyAuth ## Testing - Unit tests for every service method - Integration tests for every route handler - No mocking repositories in integration tests - Use test fixtures from ...