NAME
.windsurfrules — instruction file for Windsurf
SYNOPSIS
./.windsurfrules
METADATA
DESCRIPTION
.windsurfrules is the legacy project-level instruction file for Windsurf (formerly Codeium), an AI-powered code editor. It was a single flat file at the project root that gets injected into the system prompt for Windsurf's Cascade AI assistant.
As of current documentation, Windsurf has moved to .windsurf/rules/*.md files with YAML frontmatter supporting four trigger modes: always_on (included every message), model_decision (AI decides from description), glob (activated on file pattern match), and manual (via @rule-name mention). Workspace rules have a 12,000 character limit per file. Global rules live at ~/.codeium/windsurf/memories/global_rules.md with a 6,000 character limit.
Windsurf also supports AGENTS.md files for directory-scoped instructions and features an auto-generated memories system stored locally at ~/.codeium/windsurf/memories/ for workspace-specific context that persists across Cascade conversations.
STRUCTURE
ANNOTATED EXAMPLE
1You are an expert in Vue 3 with the Composition API, TypeScript, and Nuxt 3.
2
3## Code Style
4- Use <script setup lang="ts"> for all Vue components
5- Define props with defineProps<T>() using TypeScript generics
6- Use composables (use* prefix) for shared stateful logic
7- Prefer computed() over methods for derived state
8
9## Project Structure
10- pages/ — Nuxt file-based routing
11- components/ — Auto-imported Vue components
12- composables/ — Shared composition functions
13- server/api/ — Nitro API routes
14- stores/ — Pinia stores (setup syntax)
15
16## Naming
17- Components: PascalCase (auto-imported, no manual imports needed)
18- Composables: camelCase with "use" prefix (useAuth, useCart)
19- API routes: kebab-case matching URL path
20- Stores: camelCase with "use" prefix and "Store" suffix (useCartStore)
21
22## Patterns
23- Use Pinia stores for global state; composables for component-tree state
24- Prefer useFetch/useAsyncData over raw $fetch in components
25- Always handle loading and error states in async operations
26- Use Zod for runtime validation of API inputs
COMMON MISTAKES
Windsurf's official documentation no longer references .windsurfrules. The modern approach uses .windsurf/rules/*.md files with YAML frontmatter (trigger modes: always_on, model_decision, glob, manual). Existing .windsurfrules files may still be read for backward compatibility.
If you still use the legacy format, the filename is .windsurfrules with a trailing 's'. This is a common typo that results in the file being silently ignored.
Windsurf supports AGENTS.md as a cross-tool standard. Root-level AGENTS.md applies globally; subdirectory files auto-scope to their directory. No frontmatter required. This is simpler than .windsurf/rules/ for directory-specific conventions.
Each editor has its own instruction files. If you use both Cursor and Windsurf, you need separate config files. Consider AGENTS.md as a cross-tool standard both editors now support.