Windsurf Rules: Complete Guide to .windsurfrules

Windsurf rules are project-level instructions that tell Windsurf's AI (Cascade) how to code in your project. By adding a .windsurfrules file to your repository root, you configure coding conventions, architecture patterns, and constraints that the AI follows across all interactions.

This guide covers how to create effective Windsurf rules, provides ready-to-use templates, and explains how to port rules between Windsurf, Cursor, Claude Code, and GitHub Copilot.

Quick Start

Create a .windsurfrules file in your project root:

# .windsurfrules

You are an expert developer working on this project.

## Tech Stack
- Next.js 15 with App Router
- TypeScript (strict mode)
- Tailwind CSS
- Prisma ORM with PostgreSQL

## Code Style
- Use functional components with hooks
- Prefer named exports over default exports
- Use Zod for runtime validation
- Write JSDoc comments for public functions

## Testing
- Use Vitest for unit tests
- Write tests alongside source files (*.test.ts)
- Achieve 80%+ coverage on new code

How Windsurf Rules Work

When you open a project in Windsurf, the IDE automatically reads the .windsurfrules file and includes its contents as context for Cascade (Windsurf's AI agent). This means:

• Every AI interaction in that project follows your rules
• Rules persist across sessions -- no need to repeat instructions
• Team members share the same AI behavior via version control
• Rules apply to both chat and inline completions

File Location

All four formats accept the same content -- markdown-formatted instructions about your project. You can maintain one set of rules and copy between formats.

Writing Effective Rules

1. Project Context

Start with what your project is and the tech stack. This gives Cascade essential context:

# Project Overview
This is a SaaS invoicing platform built with:
- Ruby on Rails 7.2 API backend
- React 19 frontend with Vite
- PostgreSQL database
- Stripe for payments
- Redis for caching and background jobs

2. Architecture Decisions

Document patterns so the AI follows your architecture:

# Architecture
- Use service objects for business logic (app/services/)
- Controllers should be thin -- delegate to services
- Use form objects for complex validations (app/forms/)
- Background jobs go in app/jobs/ using Sidekiq
- API responses use serializers (app/serializers/)

3. Code Style Rules

Be specific about formatting, naming, and patterns:

# Code Style
- Use 2-space indentation (Ruby/JS/CSS)
- Method names: snake_case (Ruby), camelCase (JS)
- Component names: PascalCase
- CSS: Use BEM naming for custom classes
- No inline styles in React components
- Prefer early returns over nested conditionals

4. Testing Requirements

Specify your testing expectations:

# Testing
- RSpec for Ruby, Jest for JavaScript
- Write unit tests for all service objects
- Integration tests for API endpoints
- Use factories (FactoryBot), not fixtures
- Test file mirrors source: spec/services/foo_spec.rb

5. Forbidden Patterns

Explicitly list what the AI should avoid:

# Do NOT
- Never use string concatenation for SQL queries
- Never commit .env files or secrets
- Never use any/unknown types in TypeScript
- Never add dependencies without checking bundle size
- Never use innerHTML for user-provided content

Templates by Framework

Next.js / React

# .windsurfrules — Next.js Project

## Stack
Next.js 15 App Router, TypeScript strict, Tailwind CSS, Prisma

## Conventions
- Use server components by default, 'use client' only when needed
- Data fetching in server components, not useEffect
- Use Next.js Image component for all images
- Metadata API for SEO (not manual meta tags)
- Route groups for layout organization

## Components
- Functional components only, no class components
- Props interface above component definition
- Extract hooks into src/hooks/ when reused
- Use React.forwardRef for composable components

Python / Django

# .windsurfrules — Django Project

## Stack
Django 5.1, Python 3.12, PostgreSQL, Redis, Celery

## Conventions
- Class-based views for CRUD, function views for custom logic
- Use Django REST Framework serializers for API
- Type hints on all function signatures
- Docstrings for all public methods (Google style)

## Models
- Abstract base models for common fields (timestamps, soft delete)
- Use Django's built-in validators
- Database indexes on frequently queried fields
- Custom managers for complex querysets

Porting Rules Between Tools

Since all AI coding tools use the same underlying concept (project-level system prompts), you can share rules across tools:

# Maintain one source of truth and copy to all locations:
cp .windsurfrules .cursorrules
cp .windsurfrules CLAUDE.md
cp .windsurfrules .github/copilot-instructions.md

Or use a skill from Skills Playground -- each skill provides a portable system prompt that works across all tools.

Advanced Patterns

Combining Multiple Rule Files

For large projects, you may want different rules for different parts of the codebase. While Windsurf reads from the project root, you can reference subdirectory-specific conventions:

# .windsurfrules

## General Rules
[general conventions here]

## Frontend (src/frontend/)
When working in src/frontend/:
- Use Tailwind utilities, not custom CSS
- Components in PascalCase directories

## Backend (src/api/)
When working in src/api/:
- Use dependency injection
- All endpoints need OpenAPI annotations

Dynamic Rules with Skills

Instead of maintaining rules manually, install specialized skills that encode best practices:

# Browse skills by category
# Visit: https://skillsplayground.com/categories/frontend/
# Visit: https://skillsplayground.com/categories/testing/

# Copy any skill's system prompt into your .windsurfrules