🌊 Windsurf – Guide complet du développement agentique

Ne pas confondre Windsurf avec du vibe coding

Où Windsurf apporte le plus

Architecture logique de travail

La qualité du résultat dépend moins du modèle seul que de la qualité du contexte, de la taille de la tâche, de la capacité de l’agent à lire les bons fichiers, et de la discipline du développeur au moment de valider.

Importer sans transporter le chaos

Importer les settings d’un éditeur existant est pratique, mais ce n’est pas une raison pour récupérer des années d’extensions obsolètes. Windsurf fonctionne mieux avec un environnement lisible.

Ouvrir le premier dépôt

Le premier réflexe ne doit pas être de demander à Cascade de modifier du code. Il faut lui demander de lire et cartographier.

Prompt:
Map this repository before editing anything.
Identify the main modules, entry points, test strategy,
configuration files, database migration system, and risky areas.
Do not modify files. Return a concise architecture map and a risk list.

Réglages de départ

Raccourcis conceptuels

Peu importe les raccourcis exacts selon OS : il faut surtout comprendre quelle surface appeler selon le problème.

Ne pas tout faire avec le même outil

La maturité consiste à choisir la plus petite surface suffisante. Un inline edit est souvent meilleur qu’un agent complet pour une modification locale.

Hygiène de session

• Fermer les conversations obsolètes.
• Nommer clairement les branches.
• Ne pas mélanger bugfix, refactor et feature dans une même session.
• Créer un résumé de fin de session.
• Transformer les apprentissages utiles en Rules ou AGENTS.md.

End session summary:
- changed files
- decisions made
- tests run
- known risks
- follow-up tasks
- rules to update

Capacités clés

Workflow recommandé

Prompts opérationnels

Prompt: diagnosis only
Analyze this issue using the current repository context.
Do not edit files. Identify likely root causes,
files to inspect, and a minimal verification plan.

Prompt: patch only
Apply the smallest safe patch for the selected root cause.
Do not refactor unrelated code. Do not format entire files.
After editing, summarize exact changes and tests to run.

Prompt: review
Review your own diff as a senior maintainer.
List behavior changes, migration risks, security risks,
and any tests that are missing.

Chat Mode : comprendre avant d’agir

Le Chat Mode est idéal pour demander une lecture, un diagnostic, une explication de design ou une analyse de risque. Il faut l’utiliser lorsque la modification est encore prématurée.

Prompt:
Explain how this module works.
Do not propose code yet.
Identify the data flow, public APIs, side effects,
and places where a change could break compatibility.

Code Mode : modifier sous contrainte

Le Code Mode doit être utilisé avec des bornes strictes : fichiers autorisés, taille du patch, comportement attendu, tests à lancer, interdits explicites.

Prompt:
Edit only these files:
- app/services/parser.py
- tests/test_parser.py

Goal: fix the reported edge case.
Do not change public function names.
Do not modify database models.
Add one regression test.
Return a concise diff summary.

Interdits à écrire dans le prompt

• Toujours nommer le périmètre.
• Toujours nommer les fichiers à ne pas toucher si nécessaire.
• Toujours demander un résumé des risques.
• Toujours regarder le diff avant commit.

Commande inline

La commande inline sert à transformer une sélection : simplifier, typer, extraire une fonction, ajouter une gestion d’erreur, documenter un bloc. Elle doit rester locale.

Inline instruction:
Refactor the selected function for readability only.
Keep the same signature, same behavior, and same exceptions.
Do not edit any other function.

Commande naturelle dans le terminal

Windsurf permet de générer des commandes à partir d’instructions naturelles. Le bénéfice est réel pour des commandes longues, mais il faut contrôler les effets.

Codelenses et actions contextuelles

Les actions contextuelles sont précieuses pour comprendre ou refactorer un symbole sans quitter le fichier. Elles doivent être utilisées comme micro-outils.

@mentionner précisément

Limites de contexte

Les conversations longues finissent par perdre de la précision. Le bon réflexe est de repartir sur une nouvelle session avec un résumé structuré plutôt que d’accumuler des dizaines de tours.

Session handoff:
Current goal:
Decisions already made:
Files changed:
Tests passing:
Open risks:
Next smallest step:
Do not revisit previous decisions unless tests fail.

Ce qu’il ne faut pas donner

• Réduire le contexte à ce qui est nécessaire.
• Anonymiser les données métier sensibles.
• Fournir des exemples synthétiques.
• Favoriser les tests minimaux plutôt que les données réelles.

Structure recommandée

# Agent instructions

## Project
This is a production Django application.
Prefer small, reviewable patches.
Do not rewrite large files.

## Code style
Use explicit names.
Avoid hidden side effects.
Keep public APIs stable unless requested.

## Database
Do not create indexes on large text fields.
Do not generate migrations without explaining the model delta.

## Tests
Add regression tests for bug fixes.
Run targeted tests before broad tests.

## Safety
Never edit secrets.
Never run destructive commands without approval.

Activation des règles

Les règles doivent être assez courtes, spécifiques, et liées à des contextes d’activation. Une règle trop générale devient du bruit ; une règle trop longue sera ignorée ou mal appliquée.

Erreurs fréquentes

• Écrire un roman dans une rule.
• Mélanger style, sécurité, architecture et commandes dans un seul bloc.
• Mettre une règle contradictoire avec le README.
• Ne jamais nettoyer les Memories erronées.
• Oublier les règles spécifiques aux migrations, crons, admin ou tests.

Workflow bugfix

Bugfix workflow:
1. Read the error and reproduction steps.
2. Inspect only relevant files first.
3. Identify root cause candidates.
4. Ask for confirmation before editing if scope is unclear.
5. Add or update one regression test.
6. Apply smallest safe patch.
7. Run targeted tests.
8. Summarize behavior change and risks.

Workflow documentation

Workflow release

Release workflow:
- inspect changed files
- list migrations
- list config changes
- list dependency changes
- run tests
- run linter
- generate release notes
- identify rollback plan
- identify manual checks after deploy

Intégrations utiles

Principes de configuration

• Commencer par un seul MCP utile.
• Préférer les connecteurs officiels quand disponibles.
• Documenter chaque serveur dans le repo ou le runbook équipe.
• Ne jamais donner un accès production par défaut.
• Créer une allowlist d’outils autorisés par environnement.

MCP governance:
- owner
- purpose
- allowed repositories
- allowed environments
- read/write permissions
- secret handling
- audit logs
- rollback procedure

Risques MCP

Auto-exécution : choisir prudemment

Listes recommandées

git status
python manage.py check
python manage.py test app.tests.test_unit
pytest tests/test_safe.py
npm test -- --runInBand
ruff check .
python -m compileall app

rm -rf
DROP DATABASE
TRUNCATE
python manage.py flush
docker system prune
kubectl delete
terraform destroy
chmod -R 777
curl | bash

Terminal dédié

Les versions récentes de Windsurf ont introduit une approche de terminal dédié pour fiabiliser les commandes agentiques, notamment lorsque les prompts shell personnalisés perturbent l’automatisation. Cette idée est importante : l’environnement d’exécution agentique doit être prévisible.

Terminal policy:
- deterministic shell
- known working directory
- safe environment variables
- no production credentials
- clear approval rules
- logs available for review

Corriger linter intelligemment

Windsurf peut corriger des erreurs de linter, mais il faut distinguer correction syntaxique et correction de design.

Tests et vérification

Verification ladder:
1. static check
2. targeted unit test
3. related integration test
4. migration dry run
5. full suite if needed
6. manual smoke test
7. PR review

Le bon test est celui qui prouve que le bug est corrigé sans masquer une régression.

Diff review obligatoire

• Vérifier les fichiers modifiés.
• Refuser les changements de style massifs non demandés.
• Repérer imports, dépendances, migrations ou settings ajoutés.
• Comparer comportement attendu vs réel.
• Demander à Cascade une auto-review, mais faire sa propre review.

Review prompt:
Review the current diff as a strict maintainer.
List unrelated changes, behavior changes, missing tests,
security risks, migration risks, and rollback notes.

Prompts UI propres

Prompt:
Fix the selected UI issue only.
Do not redesign the page.
Keep the existing layout, CSS variables, modal system,
and responsive behavior. Explain the exact CSS selectors changed.

Déploiement contrôlé

Un bouton de déploiement n’autorise pas une absence de procédure. L’agent peut aider à préparer, mais le déploiement doit respecter branche, CI, review, rollback et environnement.

Pièges frontend

• Corriger le visuel en cassant l’accessibilité.
• Créer du CSS global qui fuit sur d’autres pages.
• Changer des classes utilisées par JavaScript.
• Supprimer des attributs data-* nécessaires aux modals.
• Modifier une structure Django template sans vérifier les blocks.

Agent Command Center

Un tableau de pilotage agentique permet de suivre plusieurs sessions : tâches locales Cascade, agents cloud, états, PRs, fichiers et contexte partagé.

Spaces : contexte de tâche

Les Spaces servent à regrouper sessions, PRs, fichiers et contexte autour d’une tâche. C’est très utile pour ne pas perdre le fil quand plusieurs agents ou conversations sont actifs.

Space structure:
- task objective
- source issue
- relevant files
- active agent sessions
- pull requests
- decision log
- test status
- open risks

Quoi déléguer à Devin / agent cloud ?

Prompt standard de patch

Task:
Implement the smallest safe patch for this issue.

Constraints:
- do not rewrite unrelated code
- do not change public APIs unless requested
- do not modify database schema unless requested
- preserve existing style
- add or update one targeted test

Output:
- files changed
- behavior change
- tests to run
- risks
- rollback notes

Quand arrêter Cascade

Rendre le patch observable

• Logs précis mais non bavards.
• Compteurs si cron ou batch.
• Messages d’erreur exploitables.
• Tests ciblés avec noms explicites.
• Résumé final des fichiers et risques.

Patch report:
Status: success or failed
Files changed:
Tests run:
Behavior changed:
Risks:
Rollback:
Next patch:

Migrations : zone rouge

Migration prompt:
Analyze the model delta first.
Do not create a migration yet.
List tables, columns, indexes, constraints,
data migration needs, lock risks, and rollback strategy.
Then propose the smallest migration plan.

Crons / management commands

Windsurf est très utile pour générer des commandes Django robustes : options, dry-run, verbose, debug, counters, export, summary et logs.

Command requirements:
- --dry-run
- --limit
- --verbose
- --debug
- structured counters
- clear progress output
- exception summary
- idempotent behavior
- safe transaction boundaries

Django admin et templates IDEO-Lab

Pour tes guides et dashboards, l’agent doit préserver l’architecture : blocks Django, CSS local, classes kcard/ig-modal, data-open/data-close, boutons Copy/Print, responsive.

Template prompt:
Keep the existing Django template architecture.
Do not rename blocks.
Do not break data-open or data-close attributes.
Do not remove modal JavaScript.
Use local CSS scoped to this page.

Tests recommandés

Politique de commandes

Gouvernance MCP

• Scopes minimaux.
• Read-only par défaut.
• Liste des MCP approuvés.
• Logs d’accès.
• Rotation des credentials.
• Contrôle par environnement.
• Revue mensuelle.

MCP approval record:
Name:
Owner:
Purpose:
Permissions:
Data accessed:
Risks:
Review date:
Rollback:

Déploiement équipe

Métriques utiles

Windsurf vs GitHub Copilot

Copilot est très fort dans l’écosystème GitHub, PR, IDEs et assistant généraliste. Windsurf est davantage pensé comme un IDE complet centré sur une expérience agentique intégrée.

• Copilot : adoption entreprise GitHub, PR, code review, intégration large.
• Windsurf : éditeur dédié, Cascade, flow local, previews, terminal intégré.
• Le choix dépend de l’écosystème : GitHub-first ou IDE agentique dédié.

IDE vs terminal / cloud agents

Comment choisir

Choose Windsurf when:
- you want an AI-native IDE
- you value integrated flow
- you need strong local interaction
- you want Cascade as main assistant
- previews and terminal integration matter

Avoid switching blindly when:
- team tooling is already standardized
- security policy is not ready
- tests are weak
- repo is not clean
- developers will accept changes without review

Bugfix

Feature

Refactor

Refactor protocol:
- map current behavior
- add characterization tests
- refactor one unit
- run tests
- inspect diff
- commit
- repeat

Résumé de fin

End of session:
- objective completed
- files changed
- tests run
- decisions made
- risks remaining
- rollback path
- rules to update
- next step

Une bonne session Windsurf se termine par un état transmissible. C’est essentiel si l’on veut industrialiser l’usage agentique en équipe.

Fonctions à surveiller

Checklist de veille

Monthly Windsurf watch:
- read latest changelog
- review Cascade changes
- review terminal auto-execution policy
- review MCP permissions
- update workspace rules
- clean wrong memories
- update AGENTS.md
- review cloud agent usage
- review security incidents
- train team on new features

Résumé doctrine IDEO-Lab

Le vrai niveau senior n’est pas de produire du code plus vite. C’est de produire des changements plus vite sans dégrader la maintenabilité, la sécurité, ni la capacité de rollback.