Cursor Composer : L'édition multi-fichiers qui fonctionne vraiment

La plupart des utilisateurs de Cursor restent dans le chat classique. Ils demandent une fonction, copient le résultat, le collent dans un fichier, et recommencent. Ça fonctionne pour les petites choses. Mais quand vous devez modifier cinq fichiers pour ajouter une fonctionnalité, ce flux de travail s'effondre.

Composer est la réponse de Cursor à ce problème. C'est un panneau séparé où vous décrivez ce que vous voulez changer, et Cursor propose des modifications à travers plusieurs fichiers en une seule fois. Vous examinez, acceptez ou rejetez chaque modification, et vous passez à autre chose. Pas de copier-coller. Pas de changement de contexte.

Ce guide couvre les vrais flux de travail du forum Cursor. Pas de langage marketing. Juste ce qui fonctionne.

Composer vs Chat classique : La vraie différence

Le chat classique est Q&R. Vous demandez, Cursor répond. C'est toujours vous qui déplacez le code dans les fichiers.

Composer est de l'action. Vous décrivez l'objectif, Cursor détermine quels fichiers toucher et quoi changer. Il présente un diff. Vous décidez ce qui est appliqué.

Fonctionnalité	Chat classique	Composer
Suggère du code	Oui	Oui
Édite les fichiers directement	Non	Oui
Modifications multi-fichiers	Non	Oui
Affiche le diff avant application	Non	Oui
Point de contrôle/rollback	Non	Oui
Idéal pour	Questions, extraits uniques	Refactoring, fonctionnalités, mises à jour par lots

La fonctionnalité clé est les points de contrôle. Composer sauvegarde un instantané avant de faire des modifications. Si l'édition part en vrille, vous revenez au point de contrôle en un clic. Le chat classique n'a pas de filet de sécurité.

Comment ouvrir Composer

Appuyez sur Cmd/Ctrl + I ou cliquez sur l'icône Composer dans la barre latérale gauche. C'est un panneau séparé du chat — ne confondez pas les deux.

Quand utiliser Composer

Composer brille quand une tâche touche plus d'un fichier. Scénarios courants :

• Refactoring — renommer une prop à travers les composants, extraire une utilitaire partagée
• Travail sur une fonctionnalité — ajouter un nouveau endpoint API nécessite des fichiers route, contrôleur, service et test
• Mises à jour de patterns — passer de fetch à un apiClient personnalisé partout
• Changements de types — mettre à jour une interface qui se propage dans dix fichiers
• Nettoyage des imports — réorganiser une structure de modules

Si vous copiez-collez du code du chat dans plus de deux fichiers, arrêtez. Utilisez Composer à la place.

Composer n'est pas pour tout

Questions rapides, one-liners, ou "explique cette regex" — le chat classique est plus rapide. Composer a un overhead. Réservez-le pour le travail multi-fichiers.

Vrai flux de travail 1 : Refactoring transversal

Vous avez un type User dans types.ts. Vous voulez renommer name en fullName parce que vous ajoutez un champ displayName et le nommage devient confus.

Cela touche :

• src/types.ts — la définition du type
• src/components/UserCard.tsx — affiche le nom
• src/components/UserProfile.tsx — l'affiche aussi
• src/api/users.ts — appels API qui reçoivent/envoient le champ
• src/lib/validators.ts — schéma Zod pour la validation utilisateur

Étape 1 : Ouvrez Composer (Cmd/Ctrl + I).

Étape 2 : Décrivez le changement :

Renomme le champ `name` en `fullName` dans le type User et mets à jour toutes les utilisations dans la base de code. Ne change aucun comportement — c'est un pur renommage.

Étape 3 : Examinez le diff proposé. Composer montre chaque fichier avec les modifications surlignées. Vérifiez que :

• Seul le name lié aux utilisateurs est renommé (pas d'autres props name)
• La couche API envoie/reçoit toujours les bonnes données
• Aucun changement de logique ne s'est glissé

Étape 4 : Acceptez ou rejetez par fichier. Si un fichier semble incorrect, rejetez uniquement celui-là et corrigez-le manuellement.

Vérifiez le diff attentivement

Composer dépasse parfois les bornes. Il pourrait renommer une prop name dans un composant non lié si le contexte semble similaire. Parcourez toujours le diff avant d'accepter.

Vrai flux de travail 2 : Ajouter une fonctionnalité à travers plusieurs fichiers

Vous voulez ajouter des "rôles utilisateur" à votre application. Les admins voient des éléments d'interface supplémentaires et peuvent accéder à des endpoints API supplémentaires.

Fichiers concernés :

• src/types.ts — ajouter role: 'user' | 'admin' à User
• src/api/auth.ts — inclure le rôle dans le payload JWT
• src/components/Navbar.tsx — montrer le lien admin uniquement pour les admins
• src/components/AdminPanel.tsx — nouveau composant
• src/hooks/useAuth.ts — exposer le flag isAdmin
• src/middleware/auth.ts — nouveau middleware pour vérifier le rôle admin

Étape 1 : Ouvrez Composer.

Étape 2 : Donnez-lui un plan, pas seulement un souhait :

Ajoute les rôles utilisateur à l'application :

1. Ajoute `role: 'user' | 'admin'` au type User dans src/types.ts
2. Mets à jour la réponse de connexion dans src/api/auth.ts pour inclure le rôle dans le payload JWT
3. Ajoute une valeur calculée `isAdmin` dans src/hooks/useAuth.ts
4. Mets à jour Navbar.tsx pour conditionnellement afficher un lien "Admin" quand isAdmin est vrai
5. Crée src/components/AdminPanel.tsx avec un tableau de bord admin placeholder
6. Crée src/middleware/auth.ts avec un middleware requireAdmin qui vérifie le rôle du JWT

Utilise les patterns existants dans la base de code. Suis le même style de gestion d'erreurs que les autres fichiers API.

Étape 3 : Composer génère un diff multi-fichiers. Examinez chaque fichier.

Étape 4 : Si le nouveau AdminPanel.tsx semble incorrect, rejetez-le et gardez le reste. Les éditions de Composer sont granulaires.

Demandez d'abord un plan

Avant de laisser Composer coder, demandez-lui d'esquisser le plan. Ajoutez "Liste les fichiers que tu vas modifier et pourquoi avant de faire les éditions." Cela attrape les malentendus tôt et ne coûte rien.

Vrai flux de travail 3 : Mise à jour par lots des appels API

Vous avez commencé avec des appels fetch bruts éparpillés dans le frontend. Maintenant vous avez un apiClient personnalisé avec les headers d'authentification, la gestion d'erreurs et l'URL de base configurée. Vous devez tout migrer.

Fichiers : potentiellement des dizaines de sites d'appels API.

Étape 1 : Assurez-vous que apiClient existe et est correctement importé dans un fichier d'abord. Composer fonctionne mieux quand il a une implémentation de référence.

Étape 2 : Ouvrez Composer et délimitez la tâche :

Remplace tous les appels `fetch` bruts dans src/ par le `apiClient` de src/lib/apiClient.ts.

Règles :
- Utilise les méthodes existantes `apiClient.get`, `.post`, `.put`, `.delete`
- Supprime le JSON.stringify manuel et la gestion de response.json() — apiClient s'en charge
- Garde les mêmes chemins d'endpoints
- Préserve les headers personnalisés qui ne sont pas déjà dans apiClient

Commence par le répertoire src/api/, puis src/hooks/ si nécessaire.

Étape 3 : Examinez par lots. N'acceptez pas 20 fichiers d'un coup sans regarder. Composer est bon, mais pas parfait.

Étape 4 : Exécutez votre suite de tests après acceptation. Les erreurs de type et le comportement d'exécution peuvent diverger même quand le diff semble propre.

Ne migrez pas tout en une fois

Si vous avez 50+ fichiers, découpez en morceaux. "Migre src/api/ d'abord." Puis "Migre src/hooks/ ensuite." Les grands lots sont plus difficiles à examiner et plus faciles à rater.

Composer + Mode Agent : Le combo puissant

Composer et le mode Agent résolvent des problèmes différents. Composer est pour les éditions multi-fichiers ciblées où vous savez ce que vous voulez. Le mode Agent est pour les tâches ouvertes où l'IA doit explorer, exécuter des commandes et trouver des solutions.

Mais ils fonctionnent ensemble.

Pattern : Agent planifie, Composer exécute

Utilisez le mode Agent pour déterminer la portée d'un changement :

Je veux migrer de React Context à Zustand pour la gestion d'état. Liste tous les fichiers qui utilisent AuthContext et quels changements chacun nécessite.

Le mode Agent explore la base de code et vous donne le détail. Puis vous ouvrez Composer et exécutez les modifications fichier par fichier, avec un examen complet du diff.

Pattern : Composer pour le refactoring, Agent pour la vérification

Après un gros refactoring Composer, basculez en mode Agent :

Exécute la suite de tests et corrige les imports cassés ou les erreurs de type causées par le refactoring récent.

Le mode Agent gère le nettoyage pendant que vous examinez les modifications de Composer.

Le mode Agent peut utiliser Composer

En mode Agent, Cursor ouvre parfois Composer en interne pour les éditions multi-fichiers. Vous ne contrôlez pas cela directement, mais vous verrez des diffs de style Composer apparaître pendant les sessions Agent. Examinez-les de la même manière.

Erreurs courantes et comment les éviter

1. Prompts vagues

Mauvais : "Améliore l'authentification."

Bon : "Ajoute un champ role au type User, mets à jour l'API de connexion pour l'inclure dans le JWT, et montre un lien admin dans la Navbar pour les utilisateurs admin."

La spécificité réduit les surprises.

2. Accepter sans examiner

Les diffs de Composer semblent propres, mais ils pourraient :

• Supprimer un commentaire que vous vouliez garder
• Changer le formatage sur des lignes non liées
• Manquer un cas limite dans un fichier

Parcourez toujours le diff. Ça prend 30 secondes et évite des retravail.

3. Trop de fichiers à la fois

Composer gère bien 10-15 fichiers. Au-delà, la fenêtre de contexte est mise à rude épreuve et la qualité baisse. Découpez les grandes tâches en morceaux logiques.

4. Ne pas utiliser les points de contrôle

Avant de commencer une grosse session Composer, appuyez sur le bouton de point de contrôle. C'est un clic. Si la session tourne mal, le retour arrière est un clic aussi. Il n'y a aucune excuse pour passer cette étape.

Les points de contrôle ne remplacent pas les commits Git

Les points de contrôle de Composer vivent à l'intérieur de Cursor. Ils ne remplacent pas git. Commitez sur git avant un gros travail Composer aussi. Utilisez les deux filets de sécurité.

5. Ignorer les erreurs de type après les modifications

Les éditions de Compiler fonctionnent peut-être 90% du temps. Les 10% restants introduisent des incompatibilités de type subtiles, surtout lors du renommage ou de la modification d'interfaces. Exécutez tsc ou votre linter après avoir accepté les modifications.

Référence rapide

Action	Raccourci
Ouvrir Composer	Cmd/Ctrl + I
Accepter la modification	Cmd/Ctrl + Y
Rejeter la modification	Cmd/Ctrl + N
Créer un point de contrôle	Cliquez sur l'icône de point de contrôle dans le panneau Composer
Revenir au point de contrôle	Cliquez sur l'icône de retour à côté du point de contrôle

Résumé

• Utilisez Composer pour les éditions multi-fichiers. Utilisez le chat classique pour les questions.
• Décrivez exactement ce que vous voulez. Incluez les chemins de fichiers et les contraintes.
• Examinez chaque diff avant d'accepter.
• Créez des points de contrôle avant les grosses sessions.
• Découpez les grandes tâches en morceaux.
• Combinez Composer avec le mode Agent : Agent explore, Composer exécute.

Composer n'est pas magique. C'est un outil qui supprime la taxe de copier-coller du travail multi-fichiers. Bien utilisé, il fait gagner des heures. Utilisé sans soin, il crée du travail de nettoyage. La différence réside dans l'étape d'examen — ne la sautez pas.