What is a .windsurfrules file?

.windsurfrules is a configuration file for Windsurf AI (built on Codeium, now part of OpenAI). It provides custom instructions to Cascade, Windsurf's autonomous AI agent, to follow your project's conventions.

Where should I place .windsurfrules?

Place .windsurfrules in your project's root directory. Alternatively, use .windsurf/rules/ directory for multiple rule files, or set rules via Windsurf Settings > Set Workspace AI Rules.

What are Cascade memories?

Cascade memories are Windsurf's context persistence system. They help Cascade remember project context across sessions. Rules files work alongside memories to guide AI behavior.

What's the maximum size for .windsurfrules?

Windsurf rules files are limited to 12,000 characters each. For larger rule sets, split them across multiple files in the .windsurf/rules/ directory.

What are the rule activation modes?

Windsurf supports 4 activation modes: Manual (via @mention), Model Decision (AI decides based on description), Glob (based on file patterns like *.tsx), and Always Apply.

How do .windsurfrules compare to .cursorrules?

Both serve similar purposes for their respective IDEs. The format and concepts are similar, but .windsurfrules is specifically for Windsurf's Cascade agent. Tools like ClaudeMDEditor can manage both.

Can I use global rules across all projects?

Yes. Use global_rules.md for rules that apply across all workspaces. Workspace-specific rules in .windsurf/rules/ take precedence for individual projects.

Should I avoid generic rules?

Yes. Generic rules like 'write good code' are unnecessary as they're already baked into Cascade's training. Focus on project-specific conventions and patterns.

Windsurf Configuration

.windsurfrules Guide

Name: ClaudeMDEditor
Price: 13.00 USD
Availability: InStock
Author: ClaudeMDEditor

Configure Windsurf's Cascade agent with custom rules. Learn about rule activation modes, Cascade memories, and best practices for AI-powered coding.

Understanding .windsurfrules

.windsurfrules is a configuration file for Windsurf AI, the AI-enhanced IDE built on Codeium (now part of OpenAI). It provides instructions to Cascade, Windsurf's autonomous AI agent, helping it understand your project's conventions and generate consistent code.

Windsurf differentiates itself with Cascade — an autonomous agent that tries to pull in the right context on its own and execute multi-step tasks without constant prompting.

Rule File Locations

Project root — Place .windsurfrules for project-wide rules
Workspace rules — Store multiple files in .windsurf/rules/
Global rules — Use global_rules.md for rules across all workspaces
Settings UI — Paste via Windsurf Settings → Set Workspace AI Rules → Edit Rules

.windsurfrules Format

Windsurf rules use Markdown format with support for XML tags to group related rules:

.windsurfrules

# Project Rules for E-commerce Platform

<tech_stack>
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS + Radix UI
- Prisma with PostgreSQL
- Stripe for payments
</tech_stack>

<coding_guidelines>
- Use Server Components by default
- Only add "use client" when needed for interactivity
- Prefer composition over inheritance
- Keep components under 150 lines
- Use Zod for all validation
</coding_guidelines>

<naming_conventions>
- Components: PascalCase (ProductCard.tsx)
- Hooks: camelCase with use prefix (useCart.ts)
- API routes: kebab-case (/api/create-checkout)
- Database models: PascalCase singular (Product, User)
</naming_conventions>

<testing>
- Write tests for critical business logic
- Use Playwright for E2E tests
- Mock Stripe in test environment
- Maintain 80% coverage on checkout flow
</testing>

<do_not>
- Use inline styles (use Tailwind)
- Create files over 300 lines
- Skip TypeScript types
- Commit .env files
</do_not>

Rule Activation Modes

Windsurf supports 4 modes for rule activation:

Always Apply — Rules loaded into every conversation automatically

Manual — Activate via @mention in Cascade's input box

Model Decision — AI decides based on natural language description

Glob — Applied to files matching patterns (e.g., *.tsx, src/**/*.ts)

Best Practices

Avoid generic rules — "Write good code" is already in Cascade's training
Use clear formatting — Bullet points and lists are easier for Cascade to follow than long paragraphs
Group with XML tags — Tags like <coding_guidelines> help organize related rules
Stay under 12,000 characters — Split larger rule sets across multiple files
Be specific about versions — Prevent outdated code suggestions

Frequently Asked Questions

Manage Your .windsurfrules Files Visually

ClaudeMDEditor lets you browse, edit, and organize .windsurfrules files across all your projects. Plus it handles CLAUDE.md, .cursorrules, and more.

Claude CodeCursorCopilotWindsurfGeminiCodexAider

Get ClaudeMDEditor — $13

One-time purchase for macOS Tahoe (26+)