Identify and avoid Windsurf anti-patterns and common integration mistakes.
Use when reviewing Windsurf code for issues, onboarding new developers,
or auditing existing Windsurf integrations for best practices violations.
Trigger with phrases like "windsurf mistakes", "windsurf anti-patterns",
"windsurf pitfalls", "windsurf what not to do", "windsurf code review".
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
Pitfall 5: Not Checkpointing Before Cascade
The mistake: Running Cascade on a dirty working tree without a Git checkpoint.
BAD: Uncomitted changes + Cascade edits = impossible to separate
→ Can't tell what was your work vs what Cascade changed
→ Can't revert Cascade changes without losing your work
GOOD: git add -A && git commit -m "checkpoint: before cascade"
→ Clean separation between your work and Cascade's
→ Easy revert: git checkout -- .
Pitfall 6: Conflicting AI Extensions
The mistake: Running GitHub Copilot alongside Windsurf.
Pitfall 7: Ignoring .windsurfrules Character Limits
The mistake: Writing a 20,000 character .windsurfrules file.
LIMITS:
- .windsurfrules: 6,000 characters max
- Global rules (global_rules.md): 6,000 characters max
- Combined total: 12,000 characters max
- Individual workspace rules (.windsurf/rules/*.md): 12,000 chars each
WHAT HAPPENS WHEN EXCEEDED:
- Content is SILENTLY TRUNCATED
- Global rules take priority over workspace rules
- You won't get an error — just missing context
FIX: Keep .windsurfrules concise (stack, patterns, don'ts)
Move detailed rules to .windsurf/rules/ with trigger modes
Pitfall 8: Long Cascade Conversations
The mistake: Using a single Cascade conversation for hours of work.
BAD: 50-message Cascade conversation spanning multiple topics
→ Context window fills up, Cascade "forgets" early context
→ Suggestions become inconsistent or contradictory
GOOD: One task per Cascade session
→ Click + icon to start new conversation for each new task
→ Clean context = better suggestions
→ Use Memories for facts that should persist across sessions
Pitfall 9: Pasting Secrets into Cascade
The mistake: Sharing API keys or credentials in Cascade chat.
BAD: "My API key is sk-abc123def456, why isn't auth working?"
→ Secret is now in Cascade's context, may appear in suggestions later
GOOD: "I'm getting auth errors with the API key from .env. The error
message is 'Invalid API key'. What should I check?"
→ Cascade can help without seeing the actual secret
Pitfall 10: Not Using Turbo Mode Safely
The mistake: Enabling Turbo mode without configuring deny lists.
BAD: Turbo mode ON + no deny list
→ Cascade auto-runs `rm -rf`, `git push --force`, etc.
GOOD: Turbo mode ON + configured deny list
→ Fast auto-execution for safe commands (npm test, git status)
→ Manual approval for dangerous commands (rm, sudo, push --force)
CONFIGURE:
Settings > cascadeCommandsDenyList > add destructive commands
Feature: "In [file], add [feature] that [behavior]. Follow the pattern
in @[reference-file]. Include error handling for [edge cases]. Don't
modify [protected files]."
Bug fix: "@[file] The function [name] fails when [condition]. The error
is [error message]. Fix it and add a test for this edge case."
Refactor: "Extract [logic] from [file] into a new [file]. Update all
imports. Run tests after. Don't change public API signatures."
