---

name: windsurf-sdk-patterns description: 'Analyze and apply production-ready Devin Desktop (formerly Windsurf) workspace configuration and Cascade interaction patterns.

Use when configuring .devin/rules/project.md, 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 argument-hint: "[scope or requirements]" version: 1.12.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• windsurf
• configuration
• rules
• mcp compatibility: Designed for Claude Code

---

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 Code and Chat modes
• Project with established coding conventions

Tool Use

• Use Read to inspect only the repository files and configuration needed for the request.
• Use Grep to locate relevant settings, rules, logs, or code without broad collection.
• Use Write only for a new artifact the user requested; never write credentials or unreviewed production configuration.
• Use Edit for bounded, reviewable changes and preserve unrelated user work.

Instructions

Step 1: Root-Level .devin/rules/project.md (Permanent Context)

The .devin/rules/project.md file is the single highest-impact configuration for Cascade output quality. It provides persistent context every session.

<!-- .devin/rules/project.md -->

# 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 .devin/rules/ with YAML frontmatter:

<!-- .devin/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

<!-- .devin/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

<!-- .devin/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

<!-- .devin/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"

Output

Create a minimal customization set using the correct mechanism—Rule, AGENTS.md, Workflow, Skill, Hook, or MCP configuration—with activation behavior, ownership, secret handling, and a verification example. Avoid undocumented settings keys.

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 or invalid frontmatter	Use .devin/rules/*.md and validate the trigger: mode
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)

<!-- ~/.codeium/windsurf/memories/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 .devin/rules/project.md .codeiumignore .devin/rules/ 2>/dev/null

Resources

• Focused first-party references
• Windsurf Rules Directory
• Cascade Memories
• MCP Integration

Related Skill

Continue with windsurf-core-workflow-a to apply these configuration patterns in a bounded Cascade session with explicit validation and rollback checkpoints.