Windsurf AI Rules Guide 2026 — .windsurfrules & Cascade Rules
Complete guide to configuring Windsurf's AI through rules files. Global rules, project rules, and Cascade-specific patterns.
Quick Summary
Windsurf uses .windsurfrules files (project-level) and Global Rules (settings). Both feed into Cascade, Windsurf's AI engine. Rules are plain text or markdown.
How Windsurf Rules Work
Windsurf's AI system is called Cascade. When you ask Cascade to write code, it checks your rules first — project-level rules from .windsurfrules and global rules from your Settings — and applies them to everything it generates.
Unlike .cursorrules (which is a single file), Windsurf supports hierarchical rules: global rules apply everywhere, project rules apply to the project, and you can add directory-specific rules for different parts of your codebase.
Three Types of Rules
Global Rules
Location: Windsurf Settings → Rules → Global Rules
Use when: Personal preferences that apply everywhere: tone, language style, response format
Example:
Keep responses concise and technical. When explaining code, show the minimal example that illustrates the concept. Prefer existing code patterns in the project over suggesting new patterns. Always explain WHY before HOW.
Project Rules (.windsurfrules)
Location: .windsurfrules file in project root
Use when: Team coding standards, tech stack conventions, project-specific patterns
Example:
This is a Next.js 15 App Router project with TypeScript and Tailwind CSS.
RULES:
- Default to Server Components ('use client' only when needed)
- Use shadcn/ui components from /components/ui/
- All API routes validate input with zod
- Database access via /lib/db.ts service layer only
- Error handling: log with context, return user-friendly messagesDirectory-Specific Rules
Location: .windsurfrules in any subdirectory
Use when: Different rules for different parts of your codebase
Example:
# /api directory rules
All handlers must:
- Authenticate requests first
- Validate input with zod schema
- Return consistent { data, error } format
- Log all mutations with user ID and timestampComplete .windsurfrules Template
# Project: [Your Project Name] # Stack: [Your Stack — e.g., Next.js 15, TypeScript, Tailwind, Supabase] ## CORE RULES ### Languages & Frameworks - [Your framework] version [X.X] - TypeScript strict mode — no 'any' types - [Styling library] for all styling ### Code Style - [Your convention] - [Your convention] ### Architecture - [Where to put files] - [Data access pattern] - [Auth pattern] ### DO NOT - [Anti-pattern 1] - [Anti-pattern 2] ## SECURITY - All inputs validated server-side - Parameterized queries only - Secrets in environment variables only ## TESTING - Test files co-located with source - Write tests for all public functions - Use [your testing library]
Windsurf vs Cursor Rules: Key Differences
| Feature | Windsurf | Cursor |
|---|---|---|
| Rule file name | .windsurfrules | .cursorrules |
| Global rules | Settings UI | Settings → Rules |
| Directory rules | Yes (hierarchical) | Limited |
| Format | Plain text / Markdown | Plain text / Markdown |
| Rule inheritance | Parent → child directories | Single project file |
| AI engine | Cascade | Claude/GPT (selectable) |
Best Practices for Windsurf Rules
- Be explicit about your stack — Cascade reads your files but rules tell it what patterns to prefer
- Use directory rules — Add stricter rules for
/api,/lib/db, or other sensitive directories - Keep global rules minimal — Put project specifics in
.windsurfrules, not global settings - Commit .windsurfrules to git — So your team all benefits from the same rules
- Update rules as your conventions evolve — Stale rules cause inconsistency
Frequently Asked Questions
Can I use the same rules as my Cursor project?
Yes — the content is the same. Just create a .windsurfrules file with the same content as your .cursorrules. You can maintain both files in the same project.
Does Windsurf support MCP?
Yes. Configure MCPs in .windsurf/mcp.json. See our Windsurf MCP setup guide for the full config.
Compare All Rules Formats
See .cursorrules, SKILL.md, and Windsurf rules side by side.