windsurf-known-pitfalls

name	windsurf-known-pitfalls
description	Identify and avoid Windsurf anti-patterns and common mistakes. Use when onboarding new developers to Windsurf, reviewing AI workflow practices, or auditing Windsurf configuration for issues. Trigger with phrases like "windsurf mistakes", "windsurf anti-patterns", "windsurf pitfalls", "windsurf what not to do", "windsurf gotchas".
allowed-tools	Read, Grep
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","windsurf","anti-patterns","gotchas","best-practices"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Windsurf Known Pitfalls

Overview

Real gotchas when using Windsurf IDE. Cascade, Supercomplete, workspace indexing, and the rules system each have behaviors that catch developers off guard. Learn from these before they catch you.

Prerequisites

• Windsurf installed and configured
• Understanding of Cascade vs Supercomplete
• Awareness of workspace indexing behavior

Instructions

Pitfall 1: Using Cascade for Simple Tasks

The mistake: Opening Cascade (Cmd+L) to complete a single line of code.

BAD: Opening Cascade to write "add a console.log"
→ Cascade spins up full agent context, reads multiple files = slow and expensive

GOOD: Use Supercomplete (Tab) for inline completions
→ Instant, free, no credits consumed

RULE OF THUMB:
- Single line / simple completion → Tab (Supercomplete)
- Inline edit of selection → Cmd+I (Command)
- Multi-file task / complex reasoning → Cmd+L (Cascade)

Pitfall 2: Opening Monorepo Root in Windsurf

The mistake: Opening a 100K+ file monorepo as a single workspace.

BAD:  windsurf ~/company-monorepo/
→ Cascade indexes everything, slow context, vague suggestions

GOOD: windsurf ~/company-monorepo/services/payments/
→ Focused context, fast indexing, precise suggestions

WHY: Cascade's context window is limited. More files = more noise.
A focused workspace with 5K files gives better suggestions than
a bloated workspace with 100K files.

Pitfall 3: Vague Cascade Prompts

The mistake: Giving Cascade broad, unscoped instructions.

BAD: "Refactor the codebase to use TypeScript"
→ Cascade may try to convert EVERY file at once, breaking everything

BAD: "Add validation to the API"
→ Which API? Which endpoints? What validation rules?

GOOD: "Convert src/utils/api.js to TypeScript. Add proper types for
all function parameters and return values. Don't change other files."

GOOD: "In src/routes/users.ts, add zod validation for the POST /users
endpoint. Validate email format, name length (2-50 chars), and role
must be 'admin' or 'user'. Return 400 with field-level errors."

Pitfall 4: Accepting Changes Without Review

The mistake: Accepting all Cascade changes without reading the diffs.

BAD: Cascade modifies 12 files → "Accept All" → broken tests
→ Cascade may have changed shared utilities, removed error handling,
  or introduced dependencies on APIs that don't exist

GOOD:
1. Read Cascade's explanation of what it changed
2. Review each file diff in the Cascade output
3. Check for: removed error handling, new imports, changed signatures
4. Run tests BEFORE committing
5. Use revert button if any file looks wrong