Windsurf Rules: How to Configure Windsurf for Your Project

What are Windsurf rules?

Windsurf rules are instructions that guide Windsurf's Cascade AI agent when it writes code for your project. Like Cursor rules and CLAUDE.md, they encode your team's conventions so the AI produces consistent, project-appropriate code.

What makes Windsurf unique is Cascade — its agentic workflow engine. Cascade doesn't just suggest code. It autonomously creates files, runs commands, installs dependencies, and orchestrates multi-file changes. Rules are especially important in Windsurf because Cascade operates with less step-by-step human oversight than other tools.

.windsurfrules file structure

Windsurf supports two approaches for rules:

The rules folder approach is recommended for any non-trivial project. Each file focuses on one topic:

.windsurf/rules/
  general.md           # Tech stack, coding style
  api-conventions.md   # Route patterns, error handling
  components.md        # React component structure
  testing.md           # Test patterns and conventions

File format

Windsurf rules use standard markdown. Unlike Cursor's .mdc format, there's no special frontmatter — just clear, structured instructions:

# API Conventions

## Route pattern
Use Next.js App Router handlers. Export named async functions.

## Response format
Return { data: result } on success.
Return { error: message } with appropriate status on failure.

## Authentication
Call requireAuth(request) before any write operation.

Global vs project scope

Global rules (~/.windsurf/rules/) apply to every project you open in Windsurf. Use these for personal preferences:

# Personal preferences

- I prefer functional components over class components
- Use early returns to reduce nesting
- Add TypeScript types explicitly, don't rely on inference for function signatures
- When creating files, use kebab-case naming

Project rules (.windsurf/rules/) are committed to git and shared with your team. They encode project-specific conventions:

# Project: dashboard-app

## Tech stack
- Next.js 15 (App Router)
- TypeScript 5.7 (strict)
- Tailwind CSS v4
- Drizzle ORM + PostgreSQL

## Architecture
- API routes in src/app/api/
- Components in src/components/ (named exports)
- Database schema in src/schema/
- Utilities in src/lib/

Project rules take precedence over global rules when they conflict.

Writing effective Windsurf rules

Be explicit about Cascade's behavior

Because Cascade operates autonomously, your rules need to be more explicit about boundaries:

## Cascade guidelines

- Do NOT install new npm packages without asking first
- Do NOT modify database migrations directly — create a new migration
- Do NOT delete files unless explicitly asked
- Always run type-check (pnpm type-check) after making changes
- When creating new API routes, always add tests in the same PR

Include command references

Cascade runs terminal commands. Tell it exactly which commands to use:

## Commands
- Dev server: pnpm dev
- Type check: pnpm type-check
- Run tests: pnpm test
- Run specific test: pnpm test src/path/to/test.ts
- Lint: pnpm lint
- Build: pnpm build
- Database migration: pnpm db:generate && pnpm db:migrate

Define file creation patterns

Cascade frequently creates new files. Guide it with explicit patterns:

## New component pattern

When creating a React component:

1. Create the file at src/components/{kebab-case-name}.tsx
2. Use named export (not default)
3. Define props with a TypeScript interface
4. Add basic JSDoc comment describing the component
5. If the component needs client interactivity, add "use client" directive

Example:

interface UserAvatarProps {
  name: string;
  imageUrl?: string;
  size?: "sm" | "md" | "lg";
}

export function UserAvatar({ name, imageUrl, size = "md" }: UserAvatarProps) {
  // implementation
}

Windsurf's agentic workflow and rules

Cascade's agentic mode is what sets Windsurf apart. Understanding how Cascade uses rules helps you write better ones:

1. Planning phase: Cascade reads all rules before starting work. Include high-level architecture guidance here.
2. Execution phase: Cascade creates files, writes code, and runs commands. Command references and file patterns matter most.
3. Validation phase: Cascade runs checks after changes. Tell it which commands validate success.

## Validation

After making changes, always run in this order:
1. pnpm type-check (must pass with zero errors)
2. pnpm test (all tests must pass)
3. pnpm lint (fix any warnings)

Do not consider a task complete until all three pass.

Sharing Windsurf rules with localskills.sh

Windsurf rules committed to .windsurf/rules/ work great for one project. But when your team works across multiple repositories — or uses multiple AI tools — you need a central registry.

localskills.sh lets you publish Windsurf rules once and install them anywhere:

# Install the CLI
npm install -g @localskills/cli
localskills login

# Publish your Windsurf rules
localskills publish

# The CLI detects .windsurf/rules/ files automatically

Your team installs with one command:

localskills install my-team/api-conventions --target windsurf

Skills are versioned — every publish creates a new version. Roll back from the dashboard if a change breaks things. Track adoption with download analytics.

Making Windsurf rules work in Cursor and Claude Code

The biggest benefit of publishing to localskills.sh is cross-tool compatibility. The same skill that installs into Windsurf also works in Cursor and Claude Code:

# Install into all three tools at once
localskills install my-team/api-conventions --target windsurf cursor claude

The CLI handles format translation:

• Windsurf: .windsurf/rules/api-conventions.md
• Cursor: .cursor/rules/api-conventions.mdc (with MDC frontmatter)
• Claude Code: .claude/skills/api-conventions.md

No manual file conversion. One publish, every tool updated.

Read the full tool comparison or learn about standardizing AI coding across your team.

---

Share your Windsurf rules across tools and teams. Get started with localskills.sh.

npm install -g @localskills/cli
localskills login
localskills publish