How to Create Custom Windsurf Flows: A Complete Guide

Windsurf's Flow mode is a game-changer. It lets AI handle complex, multi-step tasks across your entire codebase. Here's how to harness its full power.

What are Windsurf Flows?

A Flow is Windsurf's term for a multi-step AI workflow. Unlike simple prompts, Flows can:

• Edit multiple files
• Run commands
• Make decisions based on results
• Ask for clarification when needed
• Roll back if something goes wrong

Think of Flows as autonomous AI workflows that handle complex tasks end-to-end.

Flow Mode vs. Standard Mode

Standard Mode (Cmd+K)

• Single edit or generation
• Quick fixes
• One file at a time

Flow Mode (Cmd+Shift+K)

• Multi-step operations
• Cross-file refactors
• Complex features
• Decision-making

Example Flows

Flow 1: Add Authentication to App

Prompt:

"Add authentication using NextAuth with Google provider. Create the API route, add session provider to layout, create a login page, and protect the dashboard route."

What Windsurf Does:

1. Installs next-auth
2. Creates /api/auth/[...nextauth]/route.ts
3. Wraps app in SessionProvider
4. Creates /login page
5. Adds auth middleware to /dashboard
6. Tests the implementation

Flow 2: Migrate from REST to tRPC

Prompt:

"Migrate all API routes to tRPC. Create tRPC router, convert each endpoint, update all client-side fetch calls to use tRPC client."

What Windsurf Does:

1. Installs tRPC
2. Creates router structure
3. Converts each API route
4. Updates all client calls
5. Removes old API routes
6. Tests each endpoint

Flow 3: Implement Dark Mode

Prompt:

"Add dark mode using next-themes. Create theme provider, add theme toggle component, update all components to support dark mode, persist theme preference."

What Windsurf Does:

1. Installs next-themes
2. Creates ThemeProvider
3. Builds toggle component
4. Updates CSS variables
5. Tests theme switching

Creating Effective Flow Prompts

1. Be Specific About the End Goal

❌ Bad: "Improve the app" ✅ Good: "Add form validation with Zod, show inline errors, and prevent submission if invalid"

2. Mention All Related Files

❌ Bad: "Add a feature" ✅ Good: "Add feature to UserProfile component, update the API route, and add tests"

3. Specify Your Stack

❌ Bad: "Add authentication" ✅ Good: "Add authentication using NextAuth with Prisma adapter and PostgreSQL"

4. Set Constraints

✅ "Implement this without installing new dependencies" ✅ "Use our existing design system components" ✅ "Keep backward compatibility with the old API"

Advanced Flow Patterns

Pattern 1: Conditional Flows

If we don't have a database schema yet, create one.
Then seed it with test data.
Finally, create API endpoints to query it.

Pattern 2: Exploratory Flows

Analyze our current error handling approach.
Identify inconsistencies.
Propose a standardized pattern.
Implement it across all API routes.

Pattern 3: Refactor Flows

Find all instances where we're duplicating the auth check logic.
Create a reusable middleware.
Replace all duplicated code with the middleware.
Test that nothing broke.

Windsurf Flow Rules

You can create custom "rules" for Flows, similar to Cursor rules.

Create a .windsurfrules file:

When implementing features:
1. Write TypeScript with strict mode
2. Add error handling to all async operations
3. Create tests for new functionality
4. Update relevant documentation
5. Run the build before marking complete

For API routes:
- Use tRPC
- Implement rate limiting
- Add input validation with Zod
- Log all errors to our monitoring service

For UI components:
- Use Tailwind CSS
- Ensure mobile responsiveness
- Add loading and error states
- Implement accessibility features

Troubleshooting Flows

Flow Gets Stuck

Press Escape to cancel and try a simpler prompt.

Wrong Direction

Use "Stop" and provide clarification:

"Stop. Don't modify the API, only update the client."

Needs More Context

Windsurf will ask questions. Answer them to guide the Flow.

Flow Failed

Review the error, then say:

"Try again, but this time [your modification]"

Best Practices

1. Start Small

Test Flows on small tasks before tackling big refactors.

2. Review Changes

Always review what the Flow did before committing.

3. Use Version Control

Commit before running complex Flows so you can roll back.

4. Provide Context

The more context in your prompt, the better the result.

5. Iterate

Flows can be refined. If it didn't do exactly what you wanted, clarify and run again.

Conclusion

Windsurf Flows are the closest thing we have to autonomous AI development. They handle the tedious multi-step tasks so you can focus on architecture and product decisions.

Master Flows, and you'll code 10x faster.

Find more Windsurf rules on AgentDepot →