Accueil › Windsurf › Rules

Windsurf Rules : configurer Cascade avec des règles

Les Windsurf Rules sont des instructions persistantes qui guident le comportement de Cascade. Elles codifient vos conventions de code, votre stack technique, vos patterns architecturaux et vos contraintes dans des fichiers Markdown que Cascade lit automatiquement à chaque interaction. C’est le levier de productivité le plus sous-estimé de Windsurf.

Pourquoi les Rules sont essentielles

Sans Rules, Cascade fonctionne avec des réglages par défaut conservateurs. Il ne connaît pas vos conventions de nommage, votre framework de test, votre architecture, ni vos contraintes techniques. Chaque conversation repart de zéro. Avec des Rules bien rédigées, Cascade applique automatiquement vos standards à chaque interaction, sans que vous ayez à les répéter.

Le contexte de Cascade est assemblé en couche à chaque interaction : Rules → Memories → fichiers ouverts → recherche indexée → actions récentes. Les Rules sont la première couche, celle qui a le plus de poids. Un fichier de rules précis réduit les itérations nécessaires (donc la consommation de quotas) et améliore la qualité de chaque réponse.

La règle d’or : les Rules encodent les contraintes stables (conventions, stack, architecture). Les Memories stockent les connaissances évoluant avec le temps (décisions, faits découverts). Les unes sont versionnées dans Git, les autres sont générées par l’IA.

Les trois niveaux de Rules

1. Rules workspace (projet)

Les rules workspace s’appliquent à un projet spécifique. Elles sont stockées dans le dossier .windsurf/rules/ à la racine de votre workspace. Chaque fichier .md dans ce dossier est une règle distincte avec son propre mode d’activation.

Windsurf découvre automatiquement les rules dans plusieurs emplacements : le workspace courant et ses sous-répertoires, les répertoires parents jusqu’à la racine Git (pour les monorepos), et les règles de tous les dossiers ouverts dans un workspace multi-dossiers (avec déduplication).

L’ancien format .windsurfrules (fichier unique à la racine du projet) est toujours supporté comme format legacy, mais le nouveau format .windsurf/rules/ est recommandé car il permet des règles multiples avec des modes d’activation différents.

2. Rules globales

Les rules globales s’appliquent à tous vos projets. Elles sont stockées dans le fichier global_rules.md accessible via les paramètres Windsurf. Utilisez-les pour des préférences personnelles qui ne dépendent pas du projet : langue de commentaires, style de formatage, patterns de codage préférés.

Le fichier global est limité à 6 000 caractères et est toujours actif (pas de frontmatter nécessaire). Les rules globales sont chargées en premier, puis complétées (pas écrasées) par les rules workspace.

3. Rules système (enterprise)

Les rules système sont gérées par l’équipe IT ou sécurité de votre organisation. Elles sont déployées via des outils de gestion de configuration (MDM, etc.) et s’appliquent à tous les utilisateurs de l’organisation. Dans l’interface Windsurf, elles affichent un label « System » et ne peuvent pas être supprimées par les utilisateurs finaux.

Les rules système sont fusionnées avec les rules globales et workspace sans les écraser. Elles permettent d’établir des standards de base (sécurité, conformité) tout en laissant les équipes ajouter des personnalisations spécifiques à leurs projets.

Modes d’activation (triggers)

Chaque rule workspace déclare un mode d’activation dans son frontmatter YAML. C’est ce qui contrôle quand la règle est injectée dans le contexte de Cascade.

Le fichier global_rules.md et les fichiers AGENTS.md à la racine du repo n’utilisent pas de frontmatter : ils sont toujours actifs.

Le choix du trigger impacte directement la consommation de fenêtre de contexte. Une rule always_on est chargée à chaque interaction, même quand elle n’est pas pertinente. Une rule glob n’est chargée que quand les fichiers matchent le pattern. Pour les projets avec beaucoup de rules, utilisez les triggers ciblés pour ne pas surcharger le contexte et laisser plus de place aux fichiers et aux réponses du modèle.

Exemple de frontmatter

---
trigger: glob
globs: **/*.test.ts
---
Tous les fichiers de test doivent utiliser des blocs `describe`/`it`.
Mocker les appels API externes avec `vi.mock()`.
Ne pas tester les détails d'implémentation, tester le comportement.

Cette règle ne sera chargée que quand Cascade travaille sur des fichiers de test TypeScript. Elle ne consomme pas de fenêtre de contexte quand vous codez sur d’autres types de fichiers.

Exemples de Rules

Rule « Stack technique » (always_on)

---
trigger: always_on
---
# Stack technique

- TypeScript 5.4 strict (noUncheckedIndexedAccess)
- React 19 avec hooks, pas de classes
- Next.js 15 App Router
- Prisma ORM avec PostgreSQL
- Vitest pour les tests, Testing Library pour les composants
- Tailwind CSS v4, pas de CSS modules

# Conventions
- Fonctions fléchées uniquement
- Imports absolus avec @/
- camelCase variables, PascalCase types et composants
- Pas de `any`, utiliser `unknown` + type guard
- Commentaires en français, code en anglais

Rule « API Endpoints » (model_decision)

---
trigger: model_decision
description: Appliquer quand on crée ou modifie des endpoints API
---
# Règles API

- Validation input avec Zod sur chaque endpoint
- Gestion d'erreur centralisée via middleware errorHandler
- Réponses : { data, error, meta } standardisées
- Authentification JWT obligatoire sauf routes publiques
- Rate limiting sur les endpoints sensibles
- Logs structurés avec Pino (level, method, path, status, duration)
- Pas de logique métier dans les route handlers
- Documentation OpenAPI auto-générée via zod-to-openapi

Rule « Tests » (glob)

---
trigger: glob
globs: **/*.test.ts, **/*.spec.ts
---
# Règles de test

- Framework : Vitest + Testing Library
- Structure : describe > it, noms en français
- Mocker les dépendances externes (API, DB) avec vi.mock()
- Tester le comportement, pas l'implémentation
- Minimum : happy path + edge case + erreur attendue
- Pas de snapshots sauf pour les composants UI stables
- Assertion style : expect().toBe/toEqual, pas de truthy/falsy

Rule « Sécurité » (always_on)

---
trigger: always_on
---
# Contraintes de sécurité

- Ne jamais écrire de secrets en dur (clés API, mots de passe)
- Utiliser process.env ou un gestionnaire de secrets
- Valider et sanitizer toutes les entrées utilisateur
- Pas de requêtes SQL brutes, utiliser Prisma
- Ne pas logger de données personnelles (email, IP, tokens)
- Vérifier les dépendances avec npm audit avant installation

Rule « Refactoring » (manual)

---
trigger: manual
---
# Processus de refactoring

Quand je demande un refactoring :
1. Analyser l'impact sur les fichiers dépendants
2. Proposer un plan avant de modifier
3. Exécuter les tests après chaque modification
4. Ne pas changer les interfaces publiques sans demander
5. Préserver la couverture de test existante
6. Documenter les changements dans un CHANGELOG

Cette règle s’active uniquement quand vous tapez @Refactoring dans Cascade. Utile pour les règles spécialisées que vous ne voulez pas charger en permanence.

Compatibilité AGENTS.md

Windsurf reconnaît aussi les fichiers AGENTS.md (format popularisé par GitHub Copilot et Claude Code). Un fichier AGENTS.md à la racine du repo est toujours actif et fonctionne comme une rule always_on. Les fichiers AGENTS.md imbriqués dans des sous-répertoires s’appliquent quand Cascade travaille dans ces répertoires.

Si vous travaillez avec plusieurs outils IA (Windsurf + Copilot + Claude Code), un fichier AGENTS.md à la racine du repo est le format le plus portable. Il sera lu par les trois outils. Pour les fonctionnalités spécifiques à Windsurf (triggers, frontmatter), utilisez le format .windsurf/rules/.

Migration depuis d’autres outils

Depuis Cursor (.cursorrules)

Si vous avez un fichier .cursorrules dans votre projet Cursor, la migration vers Windsurf est directe. Copiez le contenu de votre .cursorrules dans un fichier .windsurf/rules/conventions.md. Ajoutez le frontmatter trigger: always_on en haut du fichier. Le format Markdown est identique entre les deux outils. Les conventions, contraintes et exemples se transposent sans modification.

Si votre .cursorrules dépasse 6 000 caractères, découpez-le en plusieurs fichiers dans .windsurf/rules/ avec des triggers ciblés (glob pour les tests, model_decision pour l’API, etc.). C’est l’occasion d’optimiser vos rules avec les modes d’activation spécifiques à Windsurf.

Depuis Copilot (copilot-instructions.md)

Le fichier .github/copilot-instructions.md de Copilot a le même objectif que les Windsurf Rules : guider l’IA avec des conventions projet. Copiez le contenu dans un fichier .windsurf/rules/conventions.md avec le frontmatter trigger: always_on. Le format est compatible. L’alternative est de créer un fichier AGENTS.md unique qui sera lu par les deux outils simultanément.

Depuis Claude Code (CLAUDE.md)

Le fichier CLAUDE.md utilisé par Claude Code fonctionne de manière similaire. Windsurf reconnaît nativement AGENTS.md (mais pas CLAUDE.md directement). Renommez votre fichier en AGENTS.md ou copiez son contenu dans .windsurf/rules/. Les deux formats sont en Markdown, la transposition est triviale.

Memories vs Rules : quand utiliser quoi

La recommandation officielle de Windsurf : pour les connaissances que vous voulez que Cascade réutilise de manière fiable, écrivez-les comme des Rules (ou dans AGENTS.md) plutôt que de compter sur les Memories auto-générées. Les Rules sont versionnnées, partageables, et vous donnent un contrôle explicite sur l’activation.

Bonnes pratiques

Soyez spécifique et concis

Les rules vagues (« écris du bon code ») n’apportent rien : c’est déjà intégré dans l’entraînement de Cascade. Les rules spécifiques (« utilise vi.mock() pour mocker les appels API, pas de mocks manuels ») changent concrètement le comportement.

Utilisez un formatage clair

Les listes à puces, les listes numérotées, et le Markdown structuré sont plus faciles à suivre pour Cascade qu’un long paragraphe. Les balises XML optionnelles (<security>, <testing>) peuvent aider à grouper les règles similaires.

Respectez les limites de caractères

6 000 caractères par fichier workspace, 6 000 pour le global, 12 000 total combiné. Si vos rules dépassent ces limites, elles seront tronquées (les rules globales ont priorité sur les workspace en cas de troncature). Découpez vos rules en fichiers spécialisés avec des triggers ciblés pour optimiser l’utilisation de l’espace.

Utilisez les triggers judicieusement

Mettez en always_on uniquement les règles universelles (stack, conventions générales, sécurité). Utilisez glob pour les règles spécifiques à un type de fichier (tests, composants, migrations). Utilisez model_decision pour les règles contextuelles. Utilisez manual pour les processus spécialisés. Chaque rule always_on consomme de la fenêtre de contexte à chaque interaction.

Encodez des contraintes, pas des préférences

Les Rules sont plus efficaces quand elles décrivent des contraintes dures (« ne jamais utiliser any », « toujours valider avec Zod ») que des préférences molles (« essaie d’écrire du code propre »). Plus la règle est binaire (faire/ne pas faire), plus Cascade la respecte.

Vérifiez que Cascade suit vos Rules

Après avoir écrit vos Rules, testez-les. Demandez à Cascade : « Quelles sont mes conventions de code ? ». Il devrait réciter vos contraintes. S’il ne le fait pas, vérifiez les erreurs de syntaxe dans vos fichiers (sections Markdown non fermées, frontmatter invalide).

Où trouver des templates

Windsurf propose un répertoire de templates de rules curées par leur équipe sur windsurf.com/editor/directory. Vous y trouverez des rules prêtes à l’emploi pour les frameworks courants : Next.js, React, Python, Node.js, TypeScript, et d’autres.

La communauté maintient aussi des collections de rules sur GitHub. Le dépôt awesome-windsurfrules rassemble des exemples de global_rules.md et de fichiers .windsurfrules partagés par des développeurs. Le site playbooks.com/windsurf-rules propose des snippets composables que vous pouvez assembler pour créer votre propre starter kit de rules.

Pour les équipes multi-outils (Windsurf + Cursor + Copilot), le format AGENTS.md est le plus portable. Un fichier unique à la racine du repo, lu par les trois outils. Consultez aussi les équivalents dans les autres IDE : Cursor Rules et Copilot Instructions.