Windsurf Rules: Generate a Lean .windsurfrules File for Cascade

What Windsurf Rules Are and Why the File Stays Small

Windsurf rules are explicit, project-level instructions you write into .windsurfrules so Cascade — Windsurf's agent — follows your conventions on every interaction in that workspace. It's a markdown file at the project root, included in every prompt automatically. That last part is the whole design constraint: anything in the file costs tokens on every single turn.

Windsurf's Cascade memories and rules docs explain the mechanics well: rules versus auto-generated memories, the scope levels, the character limit. The design.dev Windsurf rules guide covers the format. What neither gives you is a prompt that turns your stack into a tight, well-shaped rules file. They establish the framework. Not the factory.

Rules vs Memories: Don't Confuse the Two

Windsurf has two memory mechanisms, and treating them as one is the most common setup mistake. Rules are manual: you write them upfront, and Cascade includes them every turn. Memories are automatic. Cascade creates them as you work, when it notices something worth remembering, and you can review or edit them in the UI.

The practical line: rules are standing policy, memories are accumulated notes. Put "always use the repository pattern for data access" in rules. Let Cascade's memory hold "the staging API key rotates weekly" after it learns that the hard way. Memories are scoped to your workspace, so a preference for one project doesn't bleed into another.

The Section Contract for a Good Rules File

A generator prompt that reads your stack can fill a fixed skeleton, so nothing important is left to "Cascade will figure it out":

• Stack and idioms. The language, framework, and the patterns this codebase prefers. Name them, don't gesture at them.
• Code style. Formatter, naming, import order: the conventions that aren't already enforced by a linter.
• Architecture rules. The structural decisions: where logic lives, what layers may call what, the patterns reviewers protect.
• Boundaries. What Cascade may change freely, what needs review, what's off-limits.
• Output preferences. How you want changes delivered: small diffs, tests alongside, no unrelated refactors.

Five tight sections, formatted as bullets and short lists. That's a file Cascade can actually hold in context every turn without drowning. Notice what's not on the list: no project description, no "you are an expert engineer" preamble, no restating of things Cascade already knows about the language. Those lines feel productive to write and do nothing but spend tokens. The sections above are the ones that change what Cascade actually produces, which is the only test a rule has to pass.

Where Windsurf Rules Quietly Fail

Three failure modes show up once a .windsurfrules file has been around a while. The first is contradiction: a rule says "prefer functional components" while a later rule, added in a hurry, says "use class components for stateful views." Cascade can't reconcile the two, so it picks one per turn, and the choice looks random to you. Review the file periodically and delete the loser.

The second is the rule that's really a memory. "The staging deploy needs the VPN on" isn't a coding convention; it's a fact Cascade should learn once and recall, which is exactly what memories are for. Putting it in rules means it rides along on every unrelated turn.

The third is the silent omission. A rules file written from memory reflects whatever you happened to think of that afternoon. Forget to mention your error-handling convention and Cascade defaults to whatever its training favored, usually a bare try/catch that swallows the error. That's the strongest case for generating the file against a contract: a fixed skeleton can't forget a section the way you can.

How to Generate Your .windsurfrules, Step by Step

1. Gather stack facts

The framework, the conventions reviewers enforce, the architectural lines you don't want crossed.

2. Fill the variables

The prompt takes {{stack}} and {{conventions}}, plus an optional {{boundaries}} for the Always / Ask-first / Never tiers.

3. Run it against the contract

Cascade follows bullet points and numbered lists more reliably than paragraphs, so the prompt formats the output that way by design, not as an afterthought.

4. Trim to the budget

Cut every line that's situational. If a rule only applies to one task, it's not a rule. It's a prompt you'll type once. Move it out.

One Opinion: Workflows, Not Rules, for Procedures

Here's a stance the Windsurf community keeps relearning. The instinct, when Cascade skips a step, is to add a rule: "always run lint and tests before pushing." But a multi-step procedure in your always-on rules file is dead weight on every unrelated turn. It belongs in a workflow you trigger on demand.

The test is simple: if it's a procedure you'd run at least weekly, make it a workflow. If it only ever applies to one task, it's just a long prompt. Rules are for what's true every turn. Everything else has a better home. That same discipline — always-on context stays lean, procedures load on demand — is exactly what makes a CLAUDE.md memory file work in Claude Code.

Variables You'll Set

Getting Started

1. Name your stack and the patterns this repo prefers.
2. List the conventions a linter doesn't already enforce.
3. Feed {{stack}} and {{conventions}} to a generator prompt with a fixed contract.
4. Take the bullet-formatted output and trim anything situational.
5. Commit .windsurfrules, and let Cascade's memories handle the rest.

Since Windsurf, Cursor, and Claude Code all read a variation of the same instruction format, the AGENTS.md Generator for Polyglot Monorepos produces the source file once and you adapt it to .windsurfrules. If your conventions are really about scaffolding new services consistently, the Golden-Path Service Scaffolder encodes those into a reusable starting point.

Why a contract beats free-form rules

Without a fixed skeleton, a generated rules file reflects whatever you happened to mention. Forget to note your testing convention, and the file silently omits it. A locked contract forces the output to either fill the Testing section or flag it empty, so the gap is visible instead of quietly absent. Cascade also parses a consistent ## Section structure more reliably across turns than ad-hoc prose, which keeps adherence steady as the conversation grows.

Windsurf rules are standing policy, not a dumping ground. Keep them lean, let Cascade's memories carry the situational stuff, and move procedures into workflows. For the same balance in other tools, see GitHub Copilot custom instructions and how to write .cursorrules that actually work.