Guide complet de Cursor Composer : édition multi-fichiers et cas pratiques

Après trois mois avec Cursor, j’ai réalisé que je « gaspillais » l’outil.

Avant, pour modifier une fonctionnalité touchant 5 fichiers — composant, API, types, tests, config — je posais mes questions une par une dans Chat et copiais-collais le code. Souris qui saute d’un fichier à l’autre, doigts sur Cmd+C et Cmd+V en boucle. Épuisant.

Un jour, un collègue passe, regarde mon écran trois secondes et dit : « Pourquoi tu n’utilises pas Composer ? »

« Hein ? »

« Cmd+I, la fenêtre flottante : une phrase pour décrire le besoin, l’IA repère les fichiers à modifier et les change tous. »

J’étais sidéré.

Il m’a fait une démo : ouvrir Composer, @ quelques fichiers liés, saisir « modifier la logique de connexion pour supporter la vérification par e-mail », Entrée. L’IA réfléchit quelques secondes, modifie composant, API et types d’un coup. 10 minutes.

Moi, j’avais passé 1 heure.

Ce jour-là, j’ai compris : en trois mois, je n’avais utilisé que 20 % de Cursor. Comme conduire une Ferrari en première vitesse.

Qu’est-ce que Composer et pourquoi en avoir besoin

Composer vs Chat : la différence fondamentale

Une métaphore d’abord.

Chat, c’est un conseiller IA assis à côté de vous. Vous demandez « comment optimiser ce code ? », il conseille, vous modifiez.

Composer, c’est une équipe de chantier. Vous dites « remplace toutes les fenêtres de cet immeuble par des baies vitrées », elle s’exécute et vous dit « c’est fait, vérifiez ».

Conseiller vs équipe de chantier — voilà la différence.

Vous voyez « historique non sauvegardé » ? Mon plus gros piège — on y reviendra.

Les trois capacités clés de Composer

Capacité 1 : compréhension inter-fichiers

Chat ne voit que le fichier ouvert. Composer voit tout le projet.

Exemple : « ajouter la connexion utilisateur ». Chat demande « quel fichier modifier ? ». Composer répond : « je dois modifier ces 5 fichiers : Login.tsx, auth.ts, user.types.ts, api/auth.ts, App.tsx ».

Il sait où sont composants, types, API, routes — et les modifie.

Capacité 2 : modifications au niveau projet

Avec Chat, vous copiez-collez. Avec Composer, les changements s’appliquent directement — Accept ou Reject.

Chat = plan de rénovation. Composer = rénovation terminée, à votre validation.

Capacité 3 : raisonnement intelligent (mode Agent)

En mode Agent, Composer peut :

• Exécuter des commandes shell (npm install, git status)
• Rechercher dans tout le dépôt (tous les usages d’une fonction)
• Analyser les dépendances
• Créer ou supprimer des fichiers

Comme un chef de chantier qui décide et trouve ses outils — mais risque de « sur-rénover ». On verra comment contrôler.

3 scénarios où Composer est indispensable

Scénario 1 : nouvelle fonctionnalité (multi-fichiers)

Besoin : ajouter les commentaires.

Avec Chat :

1. Demander quels fichiers modifier
2. Lister 5 fichiers
3. Ouvrir un par un
4. « Écris le composant Comments »
5. Copier-coller
6. « Écris l’API commentaires »
7. Copier-coller
8. Répéter 5 fois

Épuisant.

Avec Composer :

1. Cmd+I
2. « Ajouter les commentaires : publier, supprimer, consulter »
3. Entrée
4. L’IA identifie et modifie tous les fichiers
5. Revue diff, Accept

10 minutes.

Scénario 2 : refactoring

Besoin : migrer Redux vers Zustand.

Chat : quasi impossible — 20+ fichiers, risque d’oubli et d’erreurs.

Composer :

@src/store
@src/components

Migrer le store Redux vers Zustand :
1. Conserver la structure d'état
2. Conserver l'API
3. Supprimer la dépendance redux

Mode Agent : l’IA analyse, modifie, teste. 20 minutes.

Scénario 3 : modifications en lot

Besoin : gestion d’erreurs uniforme sur tous les appels API.

Chat : fichier par fichier, oublis fréquents.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Composer :

@src/api

Ajouter une gestion d'erreurs uniforme à tous les appels API :
- try-catch
- format d'erreur uniforme
- journalisation des erreurs

15 fichiers d’un coup.

Composer vs Chat : la règle de décision en 5 secondes

Vous hésitez : Cmd+L ou Cmd+I ?

Trois étapes, cinq secondes.

Flux de décision

Étape 1 : combien de fichiers ?

• 1 fichier → continuer
• 2 ou plus → Composer

Simple : multi-fichiers = Composer.

Étape 2 : question ou modification ?

• Question (apprendre, comprendre, déboguer) → Chat
• Modification (générer, refactorer) → Composer

Conseiller vs équipe de chantier.

Étape 3 : ampleur du changement ?

• Petit (quelques lignes) → Chat + Cmd+K
• Grand (module entier) → Composer

Renommer une variable ou ajouter un commentaire : Cmd+K suffit.

4 scénarios pour Chat

Scénario 1 : Q&R rapide

Vous : « Ce code a un bug ? »
Chat : « Oui, dépassement de tableau ligne 12 »

Pas de modification — Chat parfait.

Scénario 2 : apprentissage

Vous : « Explique le principe de cet algorithme »
Chat : « C'est du tri rapide, l'idée centrale est… »

Scénario 3 : debug mono-fichier

Vous : « Optimise cette fonction »
Chat : « Utilisez la mémoïsation pour mettre en cache… »

Vous modifiez vous-même.

Scénario 4 : revue de code

Vous : « Quels problèmes potentiels ici ? »
Chat : « Ligne 15 : null non géré ; ligne 28 : fuite mémoire… »

4 scénarios pour Composer

Scénario 1 : nouvelle fonctionnalité — multi-fichiers, déjà vu.

Scénario 2 : refactoring — restructuration large :

• Découper gros fichiers
• Fusionner petits fichiers
• Réorganiser les dossiers
• Uniformiser la nomenclature

Chat ne peut pas.

Scénario 3 : migration de dépendances — axios → fetch, moment.js → dayjs, styled-components → Tailwind CSS, Redux → Zustand. Des dizaines de fichiers.

Scénario 4 : modifications en lot — console.log → logger, var → const, classes → composants fonctionnels.

3 cas comparatifs

Cas 1 : modifier les appels API

Tâche : axios → fetch. 15 fichiers.

Chat : fichier par fichier, oublis. Composer : @src/api remplacer tous les axios par fetch, revue diff.

Verdict : Composer

Cas 2 : déboguer une fonction

Tâche : bug dans le calcul du total. 1 fichier.

Chat : réponse immédiate. Composer : trop lourd.

Verdict : Chat

Cas 3 : système de permissions

Tâche : RBAC. 10+ fichiers.

Chat : quasi impossible. Composer (Agent) : middleware, API, composants, contrôles d’accès automatiques.

Verdict : Composer (Agent)

La bonne façon d’utiliser Composer

Première configuration (3 étapes)

Après l’installation, configurez avant de vous lancer.

Étape 1 : choisir le modèle

Recommandé : Claude 3.7 Sonnet.

Pourquoi ?

• Fort raisonnement : relations multi-fichiers complexes
• Faible taux d’erreur
• Bonne compréhension multi-fichiers

N’utilisez pas o1 ou o1-mini — ils ne supportent pas Composer. Cursor basculera sur un autre modèle, résultats décevants.

Étape 2 : activer le mode Agent (optionnel)

Cursor Settings → Beta → Agent.

Composer peut alors :

• Exécuter des commandes shell (npm install, git status)
• Rechercher dans le dépôt (Cmd+Enter)
• Créer/supprimer des fichiers
• Analyser la structure du projet

Comme une boîte à outils — mais risque de « sur-travaux ».

Étape 3 : tarification

• Gratuit : Composer limité, quelques requêtes/jour
• Pro : 500 requêtes premium/mois — suffisant
• Business : illimité

Usage intensif : Pro recommandé. Personnellement ~300-400 requêtes/mois.

Lecture de l’interface

┌─────────────────────────────────┐
│  Composer  [Normal] [Agent]     │  ← changement de mode
├─────────────────────────────────┤
│  📝 Zone de saisie (besoin)     │
│  @ fichiers/dossiers/code       │
├─────────────────────────────────┤
│  💬 Historique de conversation  │
│  📄 Aperçu diff par fichier     │
│  ✅ Accept  ❌ Reject            │
└─────────────────────────────────┘

Normal/Agent en haut à droite. L’aperçu diff montre chaque modification. Ne jamais Accept All directement.

Maîtriser les références @

@ est au cœur de Composer.

@Files : fichier précis

@src/components/Header.tsx
Rendre ce composant responsive

@Folders : dossier entier

@src/utils
Refactoriser cette lib utilitaire, découper par fonction

@Code : bloc de code

Sélectionnez du code, Cmd+I :

@[fonction sélectionnée]
Optimiser les performances de cette fonction

@Web : contenu web

@https://docs.react.dev/reference/react/useEffect
Refactoriser cet effect selon les bonnes pratiques officielles React

@Docs : documentation projet

@README.md
Implémenter cette fonctionnalité selon la documentation

@Codebase : recherche globale

Cmd+Enter :

Trouver tous les usages de localStorage et migrer vers IndexedDB

En mode Agent, recherche et modification globales.

Normal vs Agent

Mode Normal :

• Tâches explicites
• Modifie uniquement les fichiers indiqués
• Plus contrôlable
• Plus rapide
• Moins de tokens

Mode Agent :

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

• Tâches complexes nécessitant du raisonnement
• Recherche, commandes, création de fichiers autonomes
• Plus intelligent, modifications parfois excessives
• Plus lent
• Plus de tokens

Conseil : tâche simple → Normal. Refactoring complexe → Agent. Incertain → Normal d’abord.

Usage personnel : 80 % Normal, 20 % Agent.

5 règles d’or de l’édition multi-fichiers

J’ai beaucoup galéré — voici 5 règles qui évitent 90 % des problèmes.

Règle 1 : découper les tâches

❌ Mauvais :

« Refactoriser tout le projet en TypeScript, optimiser les perfs, ajouter des tests »

Composer ne sait pas par où commencer. Résultat chaotique, 2 h de rollback.

✅ Bon :

4 sessions :

Session 1 : « Convertir src/utils en TypeScript »
Session 2 : « Ajouter des tests unitaires à utils »
Session 3 : « Optimiser les perfs du composant Header »
Session 4 : « Refactoriser les appels API, gestion d'erreurs uniforme »

Chaque objectif petit, git commit à chaque fois.

Pourquoi découper ?

• Moins de dérive de l’IA
• Diff plus petit, revue plus facile
• Rollback ciblé
• Moins de tokens

Max 10 fichiers par session Composer. Au-delà, découper.

Règle 2 : délimiter la portée

Utilisez @ pour cibler.

@src/components/User
@src/types/user.ts
@src/api/user.ts

Migrer les API utilisateur de RESTful vers GraphQL

L’IA ne touche que ces 3 endroits.

Sans portée : « uniformiser les appels API » — l’IA modifie peut-être des bibliothèques tierces. Projet cassé.

Avantages : pas de modifications hors scope, contrôle, moins de surprises.

Premier réflexe : @ les fichiers concernés.

Règle 3 : revue fichier par fichier

Ne jamais Accept All.

Tentant : 20 fichiers, un clic, tout appliqué. Mais…

Cas réel :

« Remplacer tous les console.log par un logger personnalisé ». 30 fichiers. Accept All sans regarder.

Résultat :

• console.log supprimés dans node_modules
• Code de debug effacé
• Projet qui ne démarre plus

1 heure de rollback et réparation.

Flux correct :

1. Aperçu diff de chaque fichier
2. Vérification ligne par ligne
3. Accept individuel
4. Reject et reformuler si problème

Lent — 20 diffs à lire — mais 90 % d’accidents évités.

Mon rituel : Composer fini → café → revue tranquille.

Règle 4 : committer rapidement

Après chaque petite tâche :

git add .
git commit -m "feat: migrer l'API utilisateur vers GraphQL"

Pourquoi ?

Historique Composer non sauvegardé. Refresh = conversation perdue.

10 fichiers modifiés, pas de commit, page qui plante… vous ne savez plus où vous en êtes.

Avec commit à chaque étape :

• Rollback facile (git reset --hard HEAD)
• Traçabilité (git log)
• Code sauvegardé même si Composer est perdu

Mon rythme : Composer → revue → Accept → git commit. Réflexe.

Règle 5 : conserver le contexte

Composer ne sauvegarde pas l’historique. Refresh = « quelle refactorisation ? » de l’IA.

Solutions :

Solution 1 : captures d’écran des instructions importantes.

Solution 2 : planifier dans Chat, exécuter dans Composer

Chat :
Vous : « Migrer axios vers fetch, quels points surveiller ? »
IA : « Gestion d'erreurs, intercepteurs, types… »
Vous : « OK, plan de migration »
IA : « Étape 1… Étape 2… Étape 3… »

Puis exécution étape par étape dans Composer.

Solution 3 : README

## Journal de refactoring 2026-01-10
- Tâche : migrer axios vers fetch
- Instruction Composer : « Remplacer tous les appels axios par fetch natif, conserver la gestion d'erreurs »
- Fichiers : src/api/*.ts
- Résultat : 15 fichiers migrés

7 pièges courants et comment les éviter

Tous ceux que j’ai rencontrés — évitez-les.

Piège 1 : historique non sauvegardé

Refresh = conversation perdue. Crash Cursor, onglet fermé… tout disparaît.

✅ Captures d’écran
✅ Planifier dans Chat
✅ git commit message pour tracer l’intention
✅ Sessions courtes (max 10 fichiers)

Piège 2 : interruption de mise à jour

Composer bloque en cours de route. Réseau, service IA, ou autre.

Résultat : fichiers partiellement modifiés, projet à moitié refactoré.

✅ git commit avant
✅ Réseau stable (VPN instable déconseillé)
✅ Tâches petites
✅ git diff pour voir les changements réels

Deux interruptions vécues : sans commit, 2 h de réparation ; avec commit, git reset instantané.

Piège 3 : changement automatique de modèle

o1 ne supporte pas Composer. Cursor bascule silencieusement. Vous croyez utiliser o1, c’est GPT-4o.

✅ Claude 3.7 Sonnet fixe
✅ Vérifier le nom du modèle en haut à droite
✅ Modèle par défaut dans Settings

Piège 4 : perte de contexte

Session 1 : « Migrer l'API utilisateur vers GraphQL »
Session 2 : « Continue, migrer aussi l'API commentaires »

L’IA : « Quelle API utilisateur ? »

✅ @ les fichiers à chaque session
✅ « Sur la base de la modification précédente, continuer… »
✅ Nouvelle session avec contexte complet si nécessaire

Chaque session = première session, contexte explicite.

Piège 5 : échec de recherche de fichiers

Cmd+Enter, « @Codebase trouver tous les axios ». L’IA : « rien trouvé ». Pourtant 15 fichiers.

✅ @Files explicites
✅ Vérifier .cursorrules et .gitignore
✅ Découper par module sur gros projets

@Codebase peu fiable sur grands projets — je préfère @Files.

Piège 6 : mode Agent trop agressif

L’IA crée des fichiers inutiles, supprime du code important, dépasse la portée.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

« Refactoriser le module utilisateur » → src/user supprimé et recréé.

✅ Normal d’abord pour tâches complexes
✅ Agent pour migrations explicites
✅ Revue diff, Reject si incohérent

Agent : puissant et dangereux. Usage : migrations de dépendances claires.

Piège 7 : espace disque insuffisant

Composer crée des fichiers temporaires. Disque plein = mise à jour échouée à mi-chemin.

✅ Nettoyer node_modules, dist
✅ 5 Go+ libres
✅ df -h pour vérifier

Piège discret — une fois rencontré, diagnostic long avant de trouver la cause.

Cas pratique : migration axios vers fetch API

Contexte :

• Projet : blog Next.js
• Tâche : remplacer axios par fetch natif
• 15 fichiers API
• Manuel : ~2 h ; Composer : ~20 min

Étape 1 : planifier dans Chat

Moi : Remplacer axios par fetch API dans le projet, quels points surveiller ?

Chat :
1. fetch ne rejette pas automatiquement les 4xx/5xx — vérifier response.ok
2. Gestion d'erreurs différente d'axios
3. Content-Type à définir manuellement
4. Intercepteurs via fonction personnalisée

Conseil : créer d'abord une fonction fetchWrapper.

Étape 2 : créer fetchWrapper

Cmd+I :

@src/utils

Créer fetchWrapper.ts, encapsulation type axios :
- JSON automatique
- Gestion d'erreurs uniforme
- Intercepteurs
- Compatible avec les appels axios existants

Composer crée fetchWrapper.ts. Vérification :

• ✅ Types complets
• ✅ Erreurs correctes
• ✅ API cohérente

Accept. git commit -m "feat: add fetchWrapper utility"

Étape 3 : migration par module

Pas 15 fichiers d’un coup. D’abord posts et comments :

@src/api/posts.ts
@src/api/comments.ts
@src/utils/fetchWrapper.ts

Migrer les appels API de posts et comments d'axios vers fetchWrapper, conserver signatures et gestion d'erreurs.

3 fichiers modifiés.

Étape 4 : revue diff

posts.ts :

• import axios → import { fetchWrapper } ✅
• axios.get() → fetchWrapper.get() ✅
• Erreurs inchangées ✅
• Signatures identiques ✅

Accept.

comments.ts : OK ✅ Accept.

fetchWrapper.ts : imports corrects ✅

Étape 5 : tests

npm run dev

Tests navigateur : liste d’articles, détail, commentaire, suppression — tout OK.

git commit -m "feat: migrate posts and comments API to fetch"

Étape 6 : autres modules

Répéter étapes 3-5 : users, auth, settings. Revue, test, commit à chaque module.

25 minutes pour les 15 fichiers.

Pièges rencontrés

Piège 1 : axios modifié dans node_modules

Sans @Files explicites. Solution : « modifier uniquement src, pas node_modules ».

Piège 2 : logique d’erreurs perdue

fetch ≠ axios. Solution : « conserver la gestion d’erreurs, vérifier response.ok manuellement ».

Piège 3 : types incomplets

Erreurs TypeScript. Solution : types via Chat, application avec Cmd+K sur fetchWrapper.ts.

Résultat final

✅ 15 fichiers migrés
✅ Toutes les API fonctionnelles
✅ 25 minutes (debug inclus)
✅ Revue de code : OK
✅ Taille réduite : axios ~30 Ko, fetch natif

Manuel : ~2 h. Composer : 25 min. Efficacité ×5.

Synthèse

1. Planifier dans Chat pour les tâches complexes
2. Exécution par étapes, git commit à chaque fois
3. Portée explicite avec @
4. Revue diff, pas Accept All
5. Tester avant l’étape suivante

Valable pour toute tâche Composer.

Conclusion

Avec Composer, mon efficacité a au moins triplé.

Avant : bascule entre fichiers, copier-coller, erreurs, oublis. Épuisant.

Maintenant : une instruction, l’IA identifie et modifie tout. Revue diff, Accept. 10 minutes.

5 principes clés :

1. Multi-fichiers → Composer — ne perdez pas de temps avec Chat
2. Découper — max 10 fichiers par session
3. Revue individuelle — pas Accept All
4. Committer tôt — git commit à chaque étape
5. Conserver le contexte — captures, Chat, README

Deux raccourcis :

• Cmd/Ctrl + L → Chat (questions)
• Cmd/Ctrl + I → Composer (modifications)

Règle en 5 secondes :

Combien de fichiers ?
 → 1 → question ou modification ?
    → question → Chat
    → modification → ampleur ?
       → petit → Chat + Cmd+K
       → grand → Composer
 → 2+ → Composer

N’ayez pas peur de Composer.

Au début, « trop intelligent, incontrôlable ». Après quelques essais avec ces règles : très contrôlable, très utile.

À faire maintenant :

1. Ouvrir Cursor, Cmd+I
2. Petite tâche d’essai (renommage en lot, style uniforme)
3. Sauvegarder les 5 règles et 7 pièges de cet article
4. Multi-fichiers = Composer en premier réflexe

Ne vous limitez pas à Chat.

Composer est le cœur de Cursor.

Essayez — vous verrez.