Config Guide Windsurf Cascade

Windsurf Rules: Configure Cascade for Better Code

Control how Cascade generates code with .windsurf/rules/

Quick Answer

Windsurf rules are configuration files that control how Cascade generates code. Create them in .windsurf/rules/ for workspace rules or global_rules.md for cross-project standards. Unlike auto-generated Memories, rules give you permanent control over security and coding patterns.

What are Windsurf rules?

Windsurf rules are manually-defined configuration files that tell Cascade - Codeium's AI agent - exactly how to write code for your project. They're the Windsurf equivalent of Cursor rules or CLAUDE.md.

Unlike Memories (which Cascade auto-generates as it learns your codebase), rules are permanent instructions you write yourself. For vibe coders building fast with AI tools, rules are critical - they let you enforce security patterns, coding standards, and framework preferences that Cascade wouldn't otherwise know about.

Key specs: Each rule file can contain up to 12,000 characters. Four activation modes control when rules apply: Manual, Always On, Model Decision, or Glob pattern matching.

Popular Windsurf rules resources

Get started faster with community-tested configurations:

📖 Official Docs

Windsurf Documentation Official guide to Memories and Rules from Codeium.

📁 Community

cursor.directory Rules templates that work in Windsurf with minor syntax changes.

How to set up Windsurf rules

Setting up Windsurf rules takes less than 5 minutes:

Create your rules directory

Terminal

mkdir -p .windsurf/rules

Create your first rule file

Terminal

# Workspace rule (project-specific)
touch .windsurf/rules/security.md

# Global rule (all workspaces)
touch ~/.windsurf/global_rules.md

Define activation mode and content

Each rule file starts with YAML frontmatter specifying when to activate:

.windsurf/rules/security.md

---
activation: always_on
---

# Security Standards

## SQL Injection Prevention
- ALWAYS use parameterized queries
- NEVER concatenate user input into SQL strings
- Use Prisma, Drizzle, or native parameterization

## Authentication & Authorization
- Check auth on EVERY server action and API route
- Use middleware for route protection
- Session tokens in HttpOnly cookies only

## Input Validation
- Validate ALL user input with Zod schemas
- Validate in server actions AND API routes
- Sanitize HTML input with DOMPurify

## Secret Management
- Secrets in .env files only, never commit to git
- Use process.env.VARIABLE_NAME server-side only
- Verify .env is in .gitignore

Test your rules

Cascade reads rule files automatically - no restart needed. Test by asking Cascade to generate database code and verify it uses parameterized queries.

Memories vs Rules: understanding the difference

Windsurf uses two systems to customize Cascade's behavior - understanding when to use each is critical for effective vibe coding.

Feature	Memories	Rules
Created by	Cascade (auto)	You (manual)
Scope	Workspace-specific	Workspace or global
Credit cost	Zero	Zero
Version control	No	Yes (.windsurf/rules/)
Use for	Learning codebase patterns	Enforcing standards

When to use Memories

Let Cascade discover your API structure, component patterns, and existing conventions automatically.

When to use Rules

Enforce security requirements, coding standards that differ from model training, and framework-specific patterns AI tools commonly get wrong.

Rule activation modes

Windsurf provides four activation modes that control when Cascade applies your rules. Choosing the right mode prevents context pollution while ensuring critical rules always fire.

activation: manual

Manual

Cascade only uses the rule when you @mention it by name. Use for specialized guidance that applies to specific tasks only.

Activate with: "Update schema @database-migration-guide"

activation: always_on

Always On

Active in every conversation. Use sparingly for critical security or coding standards - too many slow down responses.

Best for: Security rules, auth checks

activation: model_decision

Model Decision

Cascade activates based on natural language matching. Describe when to use the rule, and the model decides relevance.

Requires: Clear description field

activation: glob

Glob Pattern

Activate automatically when working with files matching the pattern. Most precise option for framework-specific rules.

Example: patterns: ["*.test.ts"]

Best practice: Start with Manual or Glob, promote to Always On only for security-critical patterns.

Security rules for Windsurf

Security is where Windsurf rules deliver the most value. AI tools generate working code fast, but they prioritize functionality over security. Copy this template to .windsurf/rules/security.md:

SQL Injection Prevention

❌ Vulnerable

const user = await db.query(
  `SELECT * FROM users WHERE email = '${email}'`
)

✅ Secure

const user = await db.user.findUnique({
  where: { email: userEmail }
})

Authentication Checks

❌ Missing auth

export async function updateProfile(data) {
  return await db.profile.update({
    where: { id: data.id }, data
  })
}

✅ Auth verified

export async function updateProfile(data) {
  const session = await getSession()
  if (!session) throw new Error('Unauthorized')
  // Verify ownership before update
  return await db.profile.update(...)
}

Input Validation

❌ No validation

export async function createPost(title, content) {
  return await db.post.create({
    data: { title, content }
  })
}

✅ Zod validation

const PostSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().max(5000)
})

export async function createPost(input) {
  const data = PostSchema.parse(input)
  return await db.post.create({ data })
}

See our guides on SQL injection, missing authentication, and hardcoded secrets for more patterns.

Windsurf rules templates by stack

Different tech stacks need different patterns. Here's a copy-paste template for the most popular vibe coding stack:

.windsurf/rules/nextjs-supabase.md

---
activation: always_on
---

# Next.js 14 + Supabase Standards

## Framework Patterns
- Use App Router, not Pages Router
- Server Components by default
- 'use client' only for hooks, event handlers, browser APIs

## Database & Auth
- All queries through Supabase client
- Row Level Security (RLS) policies required on all tables
- Auth checks in middleware: middleware.ts
- Use Supabase Auth, not custom JWT

## API Routes
- Use Server Actions for mutations
- API routes only for webhooks and third-party integrations
- Validate webhook signatures (Stripe, etc.)

For more stack-specific templates, see our Next.js + Supabase security guide.

Windsurf rules vs Cursor rules

Both tools serve the same purpose but differ in implementation:

Feature	Windsurf	Cursor
File location	`.windsurf/rules/`	`.cursor/rules/`
Global rules	`~/.windsurf/global_rules.md`	`~/.cursor/rules/`
Activation control	4 modes (Manual, Always On, Model Decision, Glob)	4 modes (similar)
File size limit	12k characters per file	No hard limit
Multiple files	Unlimited in rules/ directory	Unlimited in rules/ directory

Migration tip: If switching from Cursor to Windsurf, copy your .cursor/rules/ content to .windsurf/rules/ and update the frontmatter syntax.

Best practices

✅ Do

Keep rules "simple, concise, and specific"
Use bullet points for scannability
Show before/after code examples
Use Glob activation for framework-specific rules
Test rules by generating relevant code
Version control rules with your project

❌ Don't

Write generic guidance already in model training
Use Always On for everything (context pollution)
Mix unrelated topics in one file
Rely on descriptions alone - show code
Store sensitive data in rules files
Leave outdated framework patterns

Handling the 12k character limit

If you hit the limit, split by concern:

security.md - Auth, SQL injection, input validation
react-patterns.md - Component standards, hooks usage
database.md - Query patterns, migrations

Frequently asked questions

Do Windsurf rules cost credits to use?

No. Both Memories and Rules cost zero credits. You can create unlimited rule files without affecting your Windsurf subscription - rules only guide how Cascade uses its existing context window.

How many rule files can I create in .windsurf/rules/?

Unlimited. Each file has a 12,000 character limit, but you can create as many files as needed. Use Glob or Model Decision activation to prevent loading unnecessary rules into every conversation.

Can I use Windsurf rules with other AI coding tools?

No. Windsurf rules only work with Cascade in the Windsurf editor. However, the security patterns work with any tool - copy relevant sections to .cursorrules or CLAUDE.md for other editors.

What's the difference between .windsurf/rules/ and global_rules.md?

Files in .windsurf/rules/ apply only to that workspace and are version-controlled with your project. The global_rules.md file (in ~/.windsurf/) applies to ALL workspaces - use it for personal preferences or company-wide standards.

Should I use Always On activation for security rules?

Yes for critical patterns like SQL injection and auth checks. Use Glob activation for framework-specific security to reduce context pollution. Avoid Always On for style preferences - use linters instead.

Why are my Windsurf rules not working?

Check three things: 1) File is in .windsurf/rules/ directory (not project root), 2) Activation mode matches your use case, 3) Description field is clear for Model Decision mode. Test by asking Cascade to generate code that should trigger the rule.

Verify Your Rules Are Working

Windsurf rules help prevent vulnerabilities, but can't catch everything. VibeShip Scanner automatically detects security issues in your vibe coded projects - even ones that slip past your rules.

Scan Your Code Free

Official documentation

Windsurf Memories & Rules Documentation - Official Codeium docs
Windsurf by Codeium - Download and getting started