Windsurf Rules (.windsurfrules): The Complete Guide

What are Windsurf rules?

Windsurf rules are persistent instructions injected into Cascade’s context so the agent codes the way your project expects — your stack, your patterns, your forbidden moves. Without them, Cascade re-derives your conventions from whatever happens to be open and gets them wrong often enough to matter. With them, “always use our error wrapper” or “never edit generated files” becomes a standing order.

Like Cursor, Windsurf has two generations of the feature. Knowing which is which — and which limits apply to each — is the whole game.

The two file systems

The original mechanism is a single .windsurfrulesfile at the workspace root: free-form Markdown, no frontmatter, applied to every Cascade conversation in that workspace. It’s simple, but everything in it is always on, with no way to scope a rule to one task or one file type. As it grows, it starts contradicting itself.

# Workspace rules
- TypeScript strict mode. No `any`, no unguarded `as` casts.
- Functions under 50 lines, files under 800.
- Use our internal `Result<T, E>` wrapper for fallible calls.
- Don't run `pnpm install` or migrations without asking first.

The modern system is a directory of individual rule files. Historically this was .windsurf/rules/; current builds prefer .devin/rules/ after the rebrand, with .windsurf/rules/ kept as a fallback. Each file is plain Markdown with a small frontmatter block, and — crucially — each one can carry its own activation mode, so you stop paying for every rule on every turn.

Activation modes

A directory rule sets its behavior with a single trigger field in frontmatter. There are four modes, and choosing the right one is mostly how you stay under the character limits (more on that next):

A directory rule with frontmatter looks like this:

---
trigger: glob
globs: ["src/**/*.ts", "src/**/*.tsx"]
description: TypeScript service conventions for the API layer
---

- Use our internal `Result<T, E>` wrapper for fallible calls.
- Service names are snake_case; file names match the export.
- Never throw across a module boundary — return a typed error instead.

The pattern mirrors Cursor closely: always_on is the global on-switch, model_decision leans on the description to decide relevance, and glob attaches the rule when a matching file is touched. Reach for manualwhen a rule is heavy and only occasionally needed. If you’re weighing the two editors themselves, see our full Windsurf vs Cursor comparison.

Character limits

This is the part that surprises people coming from Cursor: Windsurf enforces hard character limits, and it silently drops what doesn’t fit.

• Global rules file: 6,000 characters. Lives at ~/.codeium/windsurf/memories/global_rules.md and applies to every workspace.
• Workspace rule files: 12,000 characters each. Each file in your rules directory gets its own 12k budget.

When you blow past the global cap, Windsurf’s official tip is notto cram more in — it’s to change how rules activate. Switch the less-critical ones from always_on to model_decision or globso they only enter the context when they’re actually relevant. The always-on budget is precious; spend it only on rules that must apply to every single turn.

Rules vs Cascade Memories vs Workflows

Windsurf has three related mechanisms that are easy to conflate. They solve different problems:

Memoriesare auto-generated and stored locally — Cascade records context from a session so you stop re-explaining yourself, but a teammate doesn’t inherit yours. Workflows are Markdown prompt templates in .windsurf/workflows/*.md (also a 12,000-character limit), invoked with /[name] — think of them as saved procedures rather than standing rules. For anything you want the whole team to share and keep in version control, reach for Rules or a portable AGENTS.md, not memories.

Windsurf rules vs Cursor rules

If you’ve set up Cursor rules, Windsurf will feel familiar — the two have converged on nearly the same model:

Both moved from a single root file to a scoped directory, and both offer parallel trigger modes (always-on, manual, model-decision, and glob/path). The defining difference is enforcement: Windsurf imposes hard character limitsthat Cursor doesn’t, which is exactly why Windsurf’s docs push you toward scoped activation modes more aggressively. Cursor uses .mdc with three frontmatter fields; Windsurf uses plain .md with one trigger field.

What the Devin Desktop rebrand means for your rules

The 2 June 2026 rebrand is a naming and product shift, not a rules-format break. Here’s the practical migration picture:

• .windsurfrules still works. The legacy root file is read exactly as before — no action required.
• .devin/rules/ is now preferred. New builds look here first; .windsurf/rules/ remains a fallback. For a new project, author in .devin/rules/.
• No rush to rename. Migrating an existing repo is as simple as copying the directory; you can keep both during the transition since both are read. The character limits and trigger modes are unchanged.
• Cascade is becoming Devin Local. The agent name is changing, but the rules it reads are the same files.

Using Windsurf alongside other tools

Here’s the catch most rules guides skip: almost nobody uses only Windsurf. The moment you also run Cursor, Claude Code, or Copilot, the same conventions you just encoded in .windsurf/rules/ have to be re-encoded in .cursor/rules, CLAUDE.md, and copilot-instructions.md— and then kept in sync forever as each tool’s format drifts (the Devin rebrand is a fresh reminder of how often that happens).

One portability lever is AGENTS.md, the plain-Markdown standard a growing list of agents read directly — useful as a shared baseline even though Windsurf still wants its own trigger modes and limits for fine-grained control. The other is to keep a single canonical library and compile to every format. Skillwright does the latter: author your rules once, then deploy them to Windsurf, Cursor, Claude Code, and Copilot — including the per-tool quirks like Windsurf’s character limits. See how to manage AI coding rules across tools for the full picture, or grab ready-made rule templates to start.

Frequently asked questions