Windsurf Cascade Config
A .windsurfrules file at project root that configures Cascade's agentic workflow with stack details, conventions, and anti-patterns.
Description
Windsurf's Cascade agent reads .windsurfrules from your project root on every session. The file has a documented 6,000 token local limit (plus 6,000 for global rules), so brevity matters more here than with other tools. Include your stack (framework versions, major libraries), naming conventions, import styles, explicit anti-patterns, and architecture overview. Update the file as the project evolves — a stale rules file is worse than no rules file. Cascade operates in Write, Chat, and Turbo modes, and the rules apply across all three. Community collections of .windsurfrules are available on GitHub for various frameworks.
Who is this for
Developers using Windsurf (formerly Codeium) as their primary AI editor, especially those using Cascade's agentic workflows.
Why files are split this way
A single file works because Windsurf's token limit enforces conciseness. Unlike tools with unlimited instruction files, Windsurf forces you to prioritize. The constraint is actually a feature — it prevents the instruction bloat that degrades AI performance in other tools.
What changed from the previous setup
No .windsurfrules file — Cascade operated with zero project context beyond what it could infer from open files.
Related patterns
Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Copilot Coding Agent Workspace
AGENTS.md plus scoped .instructions.md files, custom agents, skills, and hooks designed for GitHub's autonomous Coding Agent.
Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.