| 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 <jeremy@intentsolutions.io> |
| 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
