Windsurf Best Practices
A consolidated reference for professional Windsurf usage in production engineering teams. These practices are drawn from high-performing teams that have integrated Windsurf into their core development workflow.
Always Review Diffs
Never accept Cascade changes without reviewing the complete diff. Cascade is highly capable but can make plausible-looking mistakes -- wrong variable names, subtly incorrect logic, missed edge cases. Treat every Flow output as a code review, not a rubber stamp.
One Goal Per Flow
Keep Flows focused: one clear goal per session. "Fix the login bug" not "Fix the login bug and also refactor the auth module and update the docs." Focused Flows produce better results, generate smaller diffs, and are dramatically easier to review and roll back.
Commit Before Every Flow
Always commit your current work before starting a significant Flow so you can roll back cleanly if Cascade takes a wrong turn. Use descriptive commit messages noting AI assistance: "feat: add rate limiting (Cascade-assisted)". This builds an audit trail.
Invest in .windsurfrules
Treat your .windsurfrules file as a living specification of your team's engineering standards. Update it after every retrospective, every significant architectural decision, and every time Cascade makes a mistake rooted in not knowing your conventions.
Productivity Anti-Patterns to Avoid
| Anti-Pattern | What Happens | Better Approach |
|---|---|---|
| Vague Flow prompts | Cascade makes assumptions that conflict with your intent; large diffs to undo | Specific goals with explicit constraints and non-goals |
| Skipping diff review | Subtle bugs merge undetected; harder to debug later because the change is mixed with AI output | Review every diff line before accepting |
| Overriding .windsurfrules ad-hoc | Inconsistent codebase; future Flows ignore the convention you just bypassed | Update .windsurfrules and let Cascade follow the new rule consistently |
| Using Flows for trivial tasks | Slower than just typing; Cascade plans where no planning is needed | Use inline completion or /commands for simple bounded edits |
| Starting Flows without committing | Large uncommitted diff after a failed Flow; hard to isolate what went wrong | Commit before every significant Flow |
| No test coverage for AI-generated code | Plausible-looking but incorrect logic ships; silent failures in production | Ask Cascade to generate tests alongside every implementation |
You have completed all 33 modules: AI Foundations, Claude Track, and Windsurf Track.
ShopMate -- Lessons Learned
# ShopMate Retrospective -- 6 months post-launch ## What worked brilliantly - .windsurfrules from day one: Cascade never suggested raw client.messages.create() - Few-shot examples from real ThreadCo listings: quality matched human copy within a week - logged_create() wrapper: cost visibility revealed we were using Sonnet where Haiku sufficed - safe_reply() guardrail: blocked 3 near-miss replies that would have promised wrong refund terms - RAG for the chat widget: hallucinated product details dropped from 12% to 0.3% - Eval suite: caught a prompt regression when we updated the system prompt in week 8 ## What we wish we had done differently - Set up the YAML brand config on day 1 -- adding it in week 4 required refactoring 6 files - Built the eval suite before launch -- found issues after customers complained - Written the .windsurfrules before writing any code -- first 2 weeks needed manual correction - Used prompt caching from the start -- adding it in month 2 cut costs by 40% immediately ## Windsurf anti-patterns we hit - Vague prompts: "improve the description feature" -- Cascade changed the wrong thing Fix: always specify what to change, what to keep, and how to test it - Not committing before large flows -- lost 45 minutes of work once on a bad flow Fix: always git commit before any Flow that touches more than 2 files - Accepting diffs without reading -- shipped a bug where brand_id was hardcoded to "threadco" Fix: read every line of every diff before accepting, no exceptions ## ShopMate at 6 months - 5,000 product descriptions generated per month across 3 brands - 3,000 customer chat messages handled per week, 6hr -> 3min response time - 8 email campaigns per month, Maya writes briefs, ShopMate writes copy - Monthly Claude cost: $38 (down from $120 after caching + model routing) - Description eval score: 88% (up from 54% at launch)