--- 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.0.0 license: MIT author: Jeremy Longshore compatible-with: claude-code, codex, openclaw tags: [saas, windsurf, anti-patterns, gotchas, best-practices] --- # 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 ``` ### 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. ``` KNOWN CONFLICTS: - GitHub Copilot — conflicts with Supercomplete Symptoms: duplicate suggestions, wrong completions, slow editor - TabNine — conflicts with Supercomplete Symptoms: competing inline suggestions - Cody (Sourcegraph) — conflicts with Cascade Symptoms: multiple AI panels, context confusion FIX: Disable competing extensions Settings > Extensions > search "copilot" > Disable ``` ### 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 ``` ## Error Handling | Pitfall | Symptom | Prevention | |---------|---------|------------| | Wrong tool for task | Slow response for simple task | Tab for completions, Cmd+L for complex | | Giant workspace | Slow indexing, vague AI | Open service directory, not root | | Vague prompts | Wrong files modified | Specify paths, constraints, expected output | | No review | Broken build after Cascade | Always review diffs, run tests | | No checkpoint | Can't undo Cascade work | Always commit before Cascade | | AI conflicts | Duplicate/wrong suggestions | Disable competing extensions | | Over-limit rules | Silently truncated | Check char counts, use workspace rules | | Long conversations | Context degradation | New session per task | | Secrets in chat | Potential data exposure | Never paste actual credentials | | Unsafe Turbo | Destructive commands auto-run | Configure deny list | ## Examples ### Pre-Cascade Checklist ```bash set -euo pipefail echo "=== Pre-Cascade Checklist ===" echo "Git clean: $(git status --porcelain | wc -l | xargs) uncommitted files" echo "On branch: $(git branch --show-current)" echo "Rules: $(wc -c < .windsurfrules 2>/dev/null || echo 0) chars (max 6000)" echo "Conflicting exts: $(windsurf --list-extensions 2>/dev/null | grep -ci 'copilot\|tabnine\|cody' || echo 0)" ``` ### Common Prompt Templates ``` 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." ``` ## Resources - [Windsurf Documentation](https://docs.windsurf.com) - [Cascade Best Practices](https://docs.windsurf.com/windsurf/cascade/cascade) - [Windsurf Rules Directory](https://windsurf.com/editor/directory) ## Next Steps Start with `windsurf-install-auth` if you're new, or `windsurf-reference-architecture` for team setup.