| name | windsurf-sdk-patterns |
| description | Apply production-ready Windsurf workspace configuration and Cascade interaction patterns.
Use when configuring .windsurfrules, workspace rules, MCP servers,
or establishing team coding standards for Windsurf AI.
Trigger with phrases like "windsurf patterns", "windsurf best practices",
"windsurf config patterns", "windsurfrules", "windsurf workspace".
|
| allowed-tools | Read, Write, Edit, Grep |
| version | 1.11.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","windsurf","configuration","rules","mcp"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
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).
