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.

<!-- .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 tests/fixtures/

Limits: 6,000 characters per rules file. 12,000 total (global + workspace combined).

Step 2: Workspace Rules with Trigger Modes

Create granular rules in .windsurf/rules/ with YAML frontmatter:

<!-- .windsurf/rules/testing.md -->
---
trigger: glob
globs: **/*.test.ts, **/*.spec.ts
---
All test files must:
- Use describe/it blocks (not test())
- Mock external API calls with msw
- Assert both success and error paths
- Include at least one snapshot test for UI components
- Use factory functions from tests/fixtures/ for test data

<!-- .windsurf/rules/api-routes.md -->
---
trigger: glob
globs: src/routes/**/*.ts
---
API route handlers must:
- Validate input with zod schema before processing
- Return consistent error format: { error: string, code: string, statusCode: number }
- Include request ID in all log lines
- Never call database directly — use repository layer

<!-- .windsurf/rules/security.md -->
---
trigger: model_decision
description: Apply when code touches authentication, authorization, or secrets
---
Security requirements:
- Never log secrets, tokens, or PII
- Use parameterized queries (never string interpolation for SQL)
- Validate JWT tokens with jose library
- Rate limit all public endpoints
- CORS: explicit origin whitelist, never wildcard in production

<!-- .windsurf/rules/migrations.md -->
---
trigger: manual
---
Database migration rules (activate with @migrations):
- Always create reversible migrations (up + down)
- Never drop columns in production — deprecate first
- Add indexes for any new foreign key columns
- Test migration on a copy of production data first

Step 3: MCP Server Configuration

Connect external tools to Cascade via Model Context Protocol:

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Enable in Windsurf Settings > Cascade > Model Context Protocol (MCP).

Tool limit: Cascade supports max 100 MCP tools total across all servers. Disable unused tools in each MCP's settings page.

Step 4: Effective Cascade Prompt Patterns

GOOD prompts (specific, scoped):
"In src/services/payment.ts, add a refundPayment method that calls
Stripe's refund API. Handle partial refunds. Return Result<Refund, PaymentError>."

"@src/routes/users.ts Add input validation using the UserCreateSchema
from src/types/user.ts. Return 400 with field-level errors."

BAD prompts (vague, unscoped):
"Add validation to the API"
"Refactor the codebase"
"Make it better"

Error Handling

Issue	Cause	Solution
Rules ignored by Cascade	File over 6,000 chars	Trim to essentials, split into workspace rules
Workspace rules not loading	Wrong directory	Must be .windsurf/rules/, not .windsurfrules/
MCP server not connecting	Command not found	Ensure npx can resolve the package
Too many MCP tools	Over 100 tool limit	Disable unused tools per MCP server
Glob trigger not firing	Wrong pattern syntax	Use gitignore-style globs: **/*.test.ts

Examples

Global Rules (Apply to All Projects)

<!-- ~/.windsurf/global_rules.md (6,000 char limit) -->
- Always use English for code comments and commit messages
- Prefer functional programming patterns over OOP
- Write self-documenting code; add comments only for "why", not "what"
- When suggesting terminal commands, explain what they do
- Never suggest installing global npm packages

Project Health Check

# Verify Windsurf config exists
ls -la .windsurfrules .codeiumignore .windsurf/rules/ 2>/dev/null

Resources

• Windsurf Rules Directory
• Cascade Memories
• MCP Integration

Next Steps

Apply patterns in windsurf-core-workflow-a for real-world Cascade usage.