How to write Windsurf
AI rules and system prompts

How Windsurf uses system prompts via rules

Windsurf AI rules are system prompts that configure Cascade - Windsurf's AI engine - to understand your codebase, follow your coding standards, and operate safely within the boundaries you define. Windsurf differs from Cursor in a key way: Cascade has stronger default multi-file awareness, understanding how files relate to each other without requiring explicit scope definitions in every request.

What to include in .windsurfrules

Organize your .windsurfrules with clear markdown section headers. Cover three categories:

# Tech stack
- TypeScript for all new files, strict mode enabled
- React 18 with functional components and hooks
- Tailwind CSS for styling, no CSS modules
- Zustand for state management

# Architecture
- Components live in src/components/, organized by feature
- API calls go through src/lib/api/ using the existing client
- Auth is handled by src/lib/auth/ - do not reimplement it
- Shared types are in src/types/ - check here before creating new ones

# Safety
- Ask before refactoring more than the file I specify
- Ask before adding new dependencies
- Write tests for all new utility functions
- If uncertain about the right approach, present options rather than guessing

Common questions

Does .windsurfrules support markdown formatting?

Yes. Cascade understands both plain text and markdown. Using headers, bullet points, and code blocks makes the rules more readable for both Cascade and your team.

How does Windsurf compare to Cursor for large codebases?

Windsurf's Cascade tends to have stronger default context awareness across large projects. Cursor offers more granular rule scoping with multiple .mdc files. For most projects both are effective. See our Cursor guide for comparison.

Can I have different rules for different branches?

Not directly - .windsurfrules applies at the repository level. For different instruction contexts, maintain separate .windsurfrules per project or use global settings for universal preferences.