Apply production-ready Windsurf SDK patterns for TypeScript and Python.
Use when implementing Windsurf integrations, refactoring SDK usage,
or establishing team coding standards for Windsurf.
Trigger with phrases like "windsurf SDK patterns", "windsurf best practices",
"windsurf code patterns", "idiomatic windsurf".
Production-ready configuration patterns for Windsurf IDE: rules files, workspace rules with trigger modes, MCP server integration, and Cascade prompt engineering.
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:
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
