NAME
.windsurf/rules/*.md — instruction file for Windsurf
SYNOPSIS
.windsurf/rules/
~/.codeium/windsurf/memories/global_rules.md
METADATA
DESCRIPTION
.windsurf/rules/*.md is the modern rules system for Windsurf, replacing the legacy .windsurfrules flat file. Each .md file uses YAML frontmatter with a trigger field specifying one of four activation modes: always_on (included in every message), model_decision (AI decides relevance from description), glob (activated when file patterns match), and manual (invoked via @rule-name).
Workspace rules in .windsurf/rules/ have a 12,000 character limit per file and take precedence over global rules. Global rules live at ~/.codeium/windsurf/memories/global_rules.md with a 6,000 character limit. Rules can also be placed in subdirectories and searched up to the git root.
Windsurf also supports AGENTS.md as a simpler alternative for directory-scoped instructions (no frontmatter needed), and features an auto-generated memories system stored at ~/.codeium/windsurf/memories/ for workspace-specific context that persists across Cascade conversations without consuming credits.
Lower numbers load first. Higher-priority files override lower ones.
STRUCTURE
ANNOTATED EXAMPLE
1---
2trigger: always_on
3---
4
5# Project Conventions
6
7You are working on a Vue 3 + Nuxt 3 application with TypeScript.
8
9## Code Style
10- Use <script setup lang="ts"> for all Vue components
11- Define props with defineProps<T>() using TypeScript generics
12- Use composables (use* prefix) for shared stateful logic
13
14## Naming
15- Components: PascalCase
16- Composables: camelCase with "use" prefix (useAuth, useCart)
17- API routes: kebab-case matching URL path
18
19---
20
21## Example: Glob-triggered rule (.windsurf/rules/testing.md)
22
23```
24---
25trigger: glob
26globs: "**/*.test.ts"
27---
28
29# Testing Conventions
30
31- Use Vitest as the test runner
32- Colocate test files next to source files
33- Use describe blocks organized by function/component name
34- Prefer userEvent over fireEvent in component tests
35- Mock external services; never hit real APIs in unit tests
36```
37
38---
39
40## Example: Model-decision rule (.windsurf/rules/security.md)
41
42```
43---
44trigger: model_decision
45---
46
47# Security Checklist
48
49- Sanitize all user input before database queries
50- Use parameterized queries; never string concatenation for SQL
51- Validate JWT tokens on every protected route
52- Never log sensitive data (passwords, tokens, PII)
53```
SPECIAL DIRECTIVES
trigger: always_onYAML frontmatter field. Rule content is included in the system prompt on every message. Use for universal project conventions.
trigger: model_decisionYAML frontmatter field. The rule description is always shown to the AI, but full content is only included when the model decides it is relevant. Reduces token usage for contextually specific rules.
trigger: globYAML frontmatter field. Rule activates when file patterns match. Requires an accompanying globs field with patterns like '**/*.test.ts' or '*.tsx'.
trigger: manualYAML frontmatter field. Rule is only activated when explicitly referenced via @rule-name mention in Cascade chat.
globs: patternYAML frontmatter field (required with trigger: glob). A glob pattern or array of patterns specifying which files trigger this rule. Examples: '**/*.tsx', ['src/api/**', '*.test.ts'].
COMMON MISTAKES
Unlike Cursor's .mdc format which has implicit defaults, Windsurf rules require an explicit trigger field in the frontmatter to specify how the rule should be activated.
The trigger: glob mode requires an accompanying globs field to know which file patterns to match. Without it, the rule will not activate on any files.
Windsurf supports AGENTS.md files alongside .windsurf/rules/. Root-level AGENTS.md applies globally; subdirectory files auto-scope to their directory. No frontmatter required. Use .windsurf/rules/ when you need explicit trigger modes or model_decision activation.
Windsurf enforces character limits on rule files. Workspace rules in .windsurf/rules/ have a 12,000 character limit per file. The global rules file at ~/.codeium/windsurf/memories/global_rules.md has a 6,000 character limit. Split large rules into multiple focused files.
The legacy .windsurfrules flat file is no longer documented by Windsurf. Migrate to .windsurf/rules/*.md files with YAML frontmatter for trigger-based activation, or use AGENTS.md for simpler directory-scoped rules.