Accueil › Windsurf › Prompts

Windsurf prompts : exemples et techniques pour Cascade

Un bon prompt Cascade décrit le résultat attendu (pas les étapes), fournit des contraintes explicites (ce qui ne doit pas changer), et laisse l’agent planifier l’exécution. Windsurf traque vos actions en temps réel : vous n’avez pas besoin de répéter le contexte de ce que vous venez de faire. Décrivez où vous voulez aller, pas d’où vous venez.

Les principes fondamentaux

Outcome-first : le résultat avant le processus

Les prompts orientés résultat produisent de meilleures modifications multi-fichiers que les instructions étape par étape. Cascade est un agent qui planifie et exécute. Donnez-lui l’objectif, et il trouvera le chemin.

Le premier prompt micromanage l’IA. Le second décrit le résultat attendu et les contraintes. Cascade détermine lui-même quels fichiers toucher, comment modifier la requête, et où ajouter le test.

Les contraintes sont aussi importantes que les objectifs

Sans contraintes, Cascade prend le chemin le plus court, ce qui peut inclure des modifications que vous n’avez pas demandées. Les non-goals protègent votre architecture :

Contraintes :
- Ne pas modifier le schéma de la base de données
- Ne pas ajouter de nouvelles dépendances
- Garder les signatures de fonctions publiques inchangées
- Utiliser le pattern existant dans src/services/ pour le nouveau service
- Ne pas toucher aux fichiers dans src/legacy/

Exploitez le Flow awareness

Cascade traque vos actions en temps réel : fichiers édités, fichiers consultés, commandes terminal, clipboard. Vous n’avez pas besoin de ré-expliquer ce que vous venez de faire. Après avoir modifié un fichier et lancé les tests dans le terminal, tapez simplement « Continue » ou « Corrige les erreurs ». Cascade sait déjà ce qui s’est passé.

Les problèmes qui apparaissent dans l’onglet « Problems » de l’éditeur peuvent être envoyés à Cascade en un clic (bouton « Send to Cascade »). Les erreurs inline peuvent être corrigées en les surlignant et en cliquant « Explain and Fix ». Ces raccourcis sont plus efficaces que de copier-coller des messages d’erreur dans un prompt.

Travaillez en deux passes

Pour les tâches complexes, demandez d’abord un plan, puis l’exécution :

Passe 1 : « Propose un plan pour ajouter l’authentification OAuth Google à l’app. Liste les fichiers à créer/modifier, les dépendances nécessaires, et les questions que tu as. »

Passe 2 : « Le plan est bon. Exécute-le. Commence par la configuration OAuth, puis les routes, puis les tests. »

Revoyez le plan avant de valider, surtout la liste des fichiers que Cascade prévoit de modifier. Si un fichier ne devrait pas être touché, corrigez le plan (bouton « Edit Plan ») avant l’exécution.

@-commands : injecter du contexte

Les @-commands permettent d’ajouter du contexte ciblé à vos prompts, similaires aux #-mentions de Copilot Chat :

Quand vous ne savez pas quels fichiers sont pertinents, @codebase est plus efficace que de naviguer manuellement dans l’arborescence. Pour des questions sur une API tierce, @web et @docs évitent à Cascade de deviner avec des informations potentiellement obsolètes.

Exemples de prompts par cas d’usage

Créer un endpoint API

Crée un endpoint POST /api/users/invite qui :
- Accepte un email dans le body
- Vérifie que l'email n'existe pas déjà en base
- Crée une invitation avec un token unique (UUID) et une date d'expiration (48h)
- Envoie un email via le service existant dans src/services/emailService.ts
- Retourne 201 avec l'ID de l'invitation

Suis le pattern des endpoints existants dans src/api/.
Inclus la validation Zod et un test Vitest.

Débugger une erreur

@src/routes/orders.ts Je reçois l'erreur :
"TypeError: Cannot read property 'id' of undefined at line 45"

Explique la cause racine et corrige sans changer l'interface publique de la route.

Le fichier est référencé directement. L’erreur exacte est fournie. La contrainte (ne pas changer l’interface publique) empêche Cascade de contourner le problème.

Refactoring à l’échelle du codebase

Renomme toutes les instances de `userId` en `accountId` dans le codebase.
Met à jour les imports, les types, les tests, et les migrations.
Ne touche pas aux fichiers dans node_modules/ ou dist/.
Crée un commit checkpoint Git avant de commencer.

Ce type de prompt exploite la force de Cascade : le refactoring multi-fichiers avec suivi des dépendances. Cascade construit un graphe de dépendances et modifie les fichiers où le symbole apparaît comme définition ou référence.

Générer des tests

Ajoute des tests unitaires pour toutes les fonctions dans @src/utils/validation.ts

Framework : Vitest
Structure : describe > it, noms en français
Couvre : happy path, edge cases, erreurs attendues
Mock les appels externes avec vi.mock()
Ne modifie pas le fichier source, seulement le fichier de test.

Migration de framework

Migre la gestion d'état de Redux vers Zustand dans src/store/.

Passe 1 : propose un plan avec la liste des fichiers impactés.
Passe 2 (après validation) : exécute la migration.

Contraintes :
- Garder la même interface publique (selectors, actions)
- Les composants React ne doivent pas changer (seulement les imports)
- Exécute les tests après chaque fichier migré
- Supprime les dépendances Redux du package.json à la fin

Déployer un projet

Déploie la branche actuelle en production de manière sécurisée.
Lance tous les checks (lint, types, tests).
Inclus un plan de rollback si le déploiement échoue.
Utilise le script de déploiement existant dans scripts/deploy.sh.

Cascade Skills : des workflows réutilisables

Les Cascade Skills (ajoutées en janvier 2026) sont des templates de workflow réutilisables. Un Skill définit ce que Cascade doit faire, quels inputs il a besoin, et quel output vous attendez. C’est un prompt structuré et paramétrable que vous activez à la demande.

Exemples de Skills : « Generate Tests » (génère des tests pour un fichier), « Refactor Module » (refactore un module en suivant un pattern), « Write Docs » (génère de la documentation), « Create Endpoint » (crée un endpoint API avec validation et tests).

Les Skills réduisent le travail de prompt engineering : au lieu de réécrire le processus complet à chaque fois, vous fournissez les spécificités (quel fichier, quel endpoint, quel schéma) et le Skill gère le reste. Pour les équipes, les Skills standardisent la qualité de l’output entre les développeurs.

Bibliothèque de prompts partagée

Toute prompt que vous tapez plus de deux fois devrait devenir un template. Créez un fichier prompts.md dans votre repo avec vos prompts les plus utilisés :

# Prompts Cascade partagés

## Nouvel endpoint API
"Crée un endpoint [METHOD] [PATH] en suivant le pattern dans
src/api/users.ts. Inclus validation Zod, gestion d'erreur,
et un test Vitest."

## Migration de schéma
"Génère une migration Drizzle pour [description du changement].
Utilise le dossier db/migrations/. Ne modifie pas les migrations existantes."

## Débugger une erreur
"@[fichier] Je reçois [erreur]. Explique la cause et corrige
sans changer l'interface publique."

## Ajouter de la documentation
"Ajoute de la documentation JSDoc à toutes les fonctions publiques
de @[fichier]. Style : concis, technique, en anglais."

Ce fichier est versionné dans Git et partagé avec l’équipe. Chaque développeur copie le template pertinent et remplace les variables. C’est plus efficace et plus cohérent que de laisser chaque développeur écrire ses propres prompts.

Erreurs courantes

Surcharger le contexte

Si vos Rules et Memories sont bien configurés, vous n’avez pas besoin de ré-expliquer vos conventions à chaque prompt. « Utilise TypeScript strict avec Vitest » est inutile si c’est déjà dans votre fichier .windsurfrules. Concentrez votre prompt sur ce qui est nouveau.

Construire une feature entière en un seul prompt

Les prompts monolithiques (« Construis un système complet de notifications avec push, email, SMS, et une interface de gestion ») produisent du code approximatif. Découpez en étapes : schéma de données, puis API, puis service d’envoi, puis interface. Chaque étape est un checkpoint de review.

Ignorer le plan de Cascade

Cascade affiche un plan avant d’exécuter. Lisez-le. Vérifiez la liste des fichiers qu’il prévoit de modifier. Si un fichier ne devrait pas être touché, corrigez avant l’exécution. Ignorer le plan, c’est laisser Cascade écrire du code sur le disque sans supervision.

Ne pas vérifier les imports

Cascade hallucine parfois des imports de bibliothèques qui ne sont pas dans votre projet. Après avoir accepté les changements, vérifiez le package.json et lancez un build. C’est un problème commun à tous les assistants IA de code, pas spécifique à Windsurf.

Utiliser le mauvais modèle

Les modèles de raisonnement (Opus 4.6, GPT-5.2-Codex en mode high/xhigh) sont puissants mais plus lents et plus coûteux. Utilisez-les pour les tâches complexes (architecture, debugging multi-fichiers). Pour les tâches simples (ajouter des commentaires, petits refactorings), SWE-1.5 ou un modèle rapide suffit. L’Arena Mode permet de comparer les modèles directement sur vos tâches réelles.

Optimiser le contexte

Passez en Codebase context. C’est le réglage le plus impactant. En mode File (défaut), Cascade ne voit que le fichier actif. En mode Codebase, il indexe tout le repo et inclut les fichiers pertinents automatiquement. Ce réglage se trouve dans le panneau Cascade, bouton Context en haut à droite. C’est la première chose à changer après l’installation.

Utilisez .codeiumignore. Créez un fichier .codeiumignore à la racine du projet (format similaire à .gitignore) pour exclure les dossiers non pertinents (node_modules, dist, .git, logs). Attention : Windsurf utilise les patterns micromatch, pas les patterns .gitignore. dist/** fonctionne, dist/ ne fonctionne pas. Cela réduit le bruit dans l’indexation et améliore la pertinence des résultats.

Convertissez les specs en Markdown. Si vous avez des spécifications en PDF, convertissez les sections clés en Markdown et placez-les dans votre projet. Cascade peut les découvrir via @codebase et les utiliser comme contexte.

Indexez la documentation externe. Ajoutez la documentation de vos frameworks et bibliothèques aux sources indexées pour que @docs retourne des informations pertinentes et à jour.

Prompts inline et vocaux

Inline Edit (⌘+K / Ctrl+K)

Pour les modifications ciblées qui ne nécessitent pas le panneau Cascade complet, l’inline edit est plus rapide. Sélectionnez du code, appuyez sur ⌘+K (macOS) ou Ctrl+K (Windows/Linux), et décrivez la modification en une phrase : « Ajoute la gestion d’erreur », « Convertis en async/await », « Documente cette fonction ». Windsurf applique le changement directement dans l’éditeur. Les inline edits sont illimités et ne consomment pas de quotas.

Terminal prompt (⌘+I)

Quand vous ne vous souvenez pas d’une commande terminal, ⌘+I dans le terminal ouvre un prompt IA qui vous aide sans quitter votre workflow. Décrivez ce que vous voulez faire en langage naturel (« lance les tests uniquement pour le module auth ») et Cascade génère la commande appropriée.

Saisie vocale

Cascade supporte la saisie vocale pour décrire des tâches complexes sans taper. Activez la saisie vocale dans le panneau Cascade et parlez naturellement. La transcription speech-to-text convertit votre parole en texte dans le champ de saisie. C’est particulièrement utile pour les descriptions longues ou quand vous réfléchissez à voix haute à une approche architecturale.