Cursor Agent sur grands projets : 7 méthodes pour ne plus perdre de fichiers ni modifier le mauvais code

La troisième alerte d’erreur s’affiche à l’écran.

Je venais de demander à Cursor Agent de refactoriser le module de connexion — cinq fichiers : formulaire frontend, route API, middleware d’authentification, modèle utilisateur et couche cache Redis. Deux minutes plus tard, l’Agent annonce fièrement : « Terminé. » Je lance le code… crash.

En creusant : l’Agent a trouvé quatre fichiers sur cinq, n’en a modifié que trois. Pire : il a « optimisé » un middleware qui fonctionnait — toutes les connexions renvoient 401. Une demi-heure de rollback manuel, repassage des dépendances, et j’ai fini le reste moi-même.

À ce moment-là, on doute : un assistant IA peut-il vraiment gérer un grand projet ?

Deux semaines à étudier le fonctionnement de Cursor Agent, une dizaine d’articles techniques et beaucoup d’essais sur le terrain. J’ai fini par une méthode qui rend l’Agent bien plus fiable sur les grands projets. Le taux de réussite des refactorings est passé de moins de 50 % à plus de 90 %.

Cet article partage 7 astuces pratiques autour de la gestion du contexte, du découpage des tâches et de la revue de code. Ce ne sont pas des théories : ce sont des leçons tirées de vrais pièges.

Pourquoi l’Agent dérape sur les grands projets

Avant les astuces, comprenons pourquoi l’Agent se trompe. Ce n’est pas qu’il soit « bête » — trois limites objectives s’imposent.

Le contexte, goulot principal

Même un modèle annoncé à 200k tokens ne couvre pas un vrai projet. Un projet frontend/backend moyen : des centaines de fichiers principaux, chacun de quelques centaines à milliers de lignes. Ajoutez package.json, configs, tests… le plafond de tokens explose vite.

L’Agent ne « voit » pas tout le projet. Seulement les fichiers mentionnés dans la conversation, plus ce que l’index Cursor associe faiblement. Comme chercher un objet sur un terrain de foot avec une vision de cinq mètres — des oublis sont inévitables.

Test sur un projet React + Node.js : même besoin, petit projet (20 fichiers) → 85 % de réussite du premier coup ; moyen (50 fichiers) → 60 % ; grand (100+) → 35 %. L’écart est net.

La « myopie » de l’Agent

Phénomène fréquent : l’Agent « ne voit » pas les dépendances indirectes.

Vous lui demandez de modifier une route API : il modifie la route et le Controller associé. Sauf que le Controller appelle un utilitaire, qui dépend d’un module de config… La chaîne se coupe souvent au deuxième maillon.

Pire, la préférence de récence : l’Agent privilégie les fichiers récemment ouverts ou cités. Un fichier mentionné plus tôt dans l’historique peut être modifié à tort ; un fichier clé non cité reste ignoré.

Absence de vue d’ensemble

Le plus coûteux.

Un développeur humain parcourt mentalement l’architecture avant d’agir : quels modules ? communications ? effet de bord sur B si on touche A ? L’Agent, non. Chaque tâche est une « optimisation locale » — code sous les yeux, solution plausible, exécution.

Cas extrême : optimiser une requête SQL — index, requête ajustée, perf en hausse. Trois jours plus tard, la mémoire explose : pour « optimiser », l’Agent a ajouté un préchargement intégral en cache et a saturé Redis.

L’Agent ne connaît pas l’intention d’architecture globale. Problème de perf → il optimise la perf ; code dupliqué → extraction de fonction — sans se demander si le design original tient encore.

3 astuces clés pour gérer le contexte

Une fois le diagnostic posé, on traite. La gestion du contexte est prioritaire : maîtrisez ce que l’Agent « voit », et beaucoup de problèmes disparaissent.

Astuce 1 : optimiser les Project Rules

Beaucoup chargent toutes les rules en mode always par paresse. Grosse erreur.

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

Commencer →Pub

always signifie « charger ces rules à chaque conversation ». Ça grignote les tokens. Frontend, backend, tests, docs — normes différentes par module. Tout en always : un tiers des tokens part avant le travail.

Bonne pratique : Auto Attached + glob

Exemple sur un projet que je maintiens :

# .cursorrules (racine du projet)

# Règles générales (le strict minimum)
- type: always
  rules:
    - Utiliser TypeScript
    - Respecter la config ESLint
    - Toute opération async doit gérer les erreurs

# Règles frontend (chargées seulement sur le frontend)
- type: auto
  glob: "src/frontend/**/*.{ts,tsx}"
  rules:
    - Utiliser React Hooks
    - Composants avec PropTypes ou types TypeScript
    - Tailwind CSS, pas de styles inline

# Règles backend
- type: auto
  glob: "src/backend/**/*.ts"
  rules:
    - Routes API avec validation des entrées
    - Opérations BDD en transaction
    - Pas de données sensibles dans les logs

# Règles tests
- type: auto
  glob: "**/*.test.ts"
  rules:
    - Chaque test avec une description claire
    - Structure Jest describe/it

L’Agent ne charge les règles que quand c’est pertinent. Chez moi : ~70 % de tokens en moins, et moins de règles parasites.

Astuce : terminer une règle par « En cas de doute, demandez-moi d’abord » — l’Agent pose des questions au lieu de deviner.

Astuce 2 : Long Context et Summarized Composers

Deux fonctions Cursor utiles et souvent ignorées.

Long Context

Option à activer pour les tâches complexes : fenêtre de contexte élargie, plus de code visible.

Ne le laissez pas toujours activé — tokens et latence augmentent. Mon usage :

• Tâche simple (fonction, petit bug) : off
• Tâche complexe (refactor module, nouvelle feature) : on
• Très complexe (multi-modules) : on + @ fichiers clés

Summarized Composers

Permet d’accéder aux résumés des conversations passées, pas à l’historique complet. Idéal sur la durée.

Hier, l’Agent a écrit un utilitaire ; aujourd’hui vous voulez l’étendre. « Utilise la fonction d’hier » seul ne suffit pas ; avec Summarized Composers, il retrouve le résumé pertinent.

Mon flux : après chaque gros module, nouvelle fenêtre Chat avec « Ce projet a déjà implémenté XX, code dans le répertoire YY » — contexte utile sans surcharge.

Astuce 3 : gérer activement la portée du contexte

La plus importante, et la plus négligée.

Ne comptez pas sur l’Agent pour trouver tous les fichiers — dites-lui quoi regarder et quoi éviter.

Référencer les fichiers clés : syntaxe @

Refactorisez le flux d'authentification utilisateur, fichiers concernés :
@src/routes/auth.ts (routes auth)
@src/middleware/jwt.ts (middleware JWT)
@src/models/User.ts (modèle User)
@src/utils/password.ts (outil hash mot de passe)

Ne modifiez aucun autre fichier.

Cette dernière phrase compte : probabilité de modifications hors scope : 30 % → moins de 5 %.

Limiter la portée

Ajoutez un composant mot de passe oublié dans src/frontend/components/auth/,
sans toucher aux autres répertoires.

Usage avancé : liste blanche + liste noire

Peut modifier : tous les fichiers sous src/api/**
Ne pas modifier : src/api/legacy/** (legacy en attente de retrait)

J’ai pris l’habitude : avant chaque tâche, « combien de fichiers au maximum ? quels répertoires ? » — puis je le dis explicitement à l’Agent. Quelques minutes gagnées en amont, des heures de debug évitées ensuite.

2 règles d’or pour découper les tâches

Le contexte règle le « ne pas tout voir ». Reste le piège des tâches trop grosses. Là, le découpage sauve.

Astuce 4 : découper par responsabilité, pas par fichier

Mon plus gros piège au départ.

Inscription utilisateur, je découpais ainsi :

1. Composant formulaire frontend
2. Route API backend
3. Modèle base de données

Logique en surface — en pratique :

• Frontend sans connaître l’API → devinettes
• Backend avec paramètres frontend incohérents → retour frontend
• Modèle BDD avec mauvais type → encore des allers-retours

Bon découpage : par fonctionnalité

Même exemple inscription :

Étape 1 : flux d’inscription minimal

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Tâche 1 : inscription utilisateur de base
- Frontend : formulaire username + password uniquement
- Backend : API inscription + validation minimale
- BDD : modèle User (champs minimum)
Objectif : enregistrer un utilisateur de bout en bout

Étape 2 : validation et sécurité

Tâche 2 : renforcer validation et sécurité
- Format email
- Force du mot de passe
- Anti-doublon
- Stockage chiffré du mot de passe

Étape 3 : expérience utilisateur

Tâche 3 : améliorer l'UX inscription
- Validation formulaire en temps réel
- Connexion auto après inscription
- Email de bienvenue

Chaque tâche est verticale : frontend → backend → BDD, un point fonctionnel autonome.

Avantages :

1. Test indépendant : la tâche 1 tourne sans attendre la suite
2. Moins de rework : problèmes d’API visibles immédiatement
3. Objectif clair pour l’Agent

Mesure : découpage par responsabilité → taux de réussite du premier coup : 60 % → 85 %.

Astuce 5 : définir des checkpoints explicites

Cette astuce m’a sauvé maintes fois.

Sur un grand projet : vous codez longtemps, direction fausse, difficile de revenir. L’Agent ne demande pas « on sauvegarde ? » — il modifie. Dix fichiers plus tard, c’est tard.

Utiliser Checkpoint

Fonction Cursor sous-estimée : Checkpoint.

Avant la tâche :

# Dans Cursor : Cmd/Ctrl + Shift + P
# Saisir "Create Checkpoint"
# Note : avant refactor module connexion

L’Agent travaille. Si ça dérape : rollback en un clic, tout annulé.

Mon rituel :

• Nouvelle grosse tâche → checkpoint
• Agent terminé → tests OK → supprimer checkpoint ; échec → rollback
• Petites tâches → checkpoint tous les 2-3 succès

Pire cas : une petite tâche perdue, pas tout le refactor.

TDD (Test-Driven Development)

Variante avancée : tests d’abord, implémentation ensuite.

1. Écrire les tests (comportement attendu)
2. Lancer — échec attendu
3. Agent implémente jusqu'au vert
4. Tests toujours rouges → mauvaise compréhension, arrêt

Les tests fixent une condition d’arrêt : l’Agent vise « faire passer les tests », pas diverger.

Refactoring complet du module auth Node.js en TDD : sept itérations, zéro dérive. Sans tests : plus de dix tours, bugs persistants.

2 pratiques clés : revue de code et surveillance

Tout ce qui précède réduit les erreurs — pas à zéro. Dernière ligne : revue et monitoring.

Astuce 6 : revue de code multicouche

Erreur fréquente : « avec l’IA, plus besoin de Code Review ».

Au contraire : les erreurs Agent sont souvent subtiles — syntaxe OK, logique plausible, mais « pas bon ». Un humain voit tout de suite ce que l’Agent rate.

Règles auto dans .cursorrules

# .cursorrules (section revue)
code_review_rules:
  # Critique (obligatoire)
  critical:
    - "Pas de mots de passe ou clés API en dur"
    - "Requêtes BDD paramétrées (anti-injection SQL)"
    - "Validation et assainissement de toute entrée externe"

  # Avertissement (fortement recommandé)
  warning:
    - "Fonctions ≤ 50 lignes, sinon découper"
    - "Éviter any, typer explicitement"
    - "Async avec try-catch ou .catch()"

  # Info (optimisation)
  info:
    - "Envisager des tests unitaires"
    - "Commenter la logique complexe"
    - "Factoriser le code dupliqué"

Après chaque tâche, je demande :

Tâche terminée : revoyez le code selon code_review_rules dans .cursorrules,
listez tous les points critical et warning.

Souvent, l’Agent repère ses propres erreurs — un second regard « mécanique ».

Stratégie hybride

Ni 100 % Agent, ni revue ligne par ligne :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

1. Pré-revue Agent : syntaxe, conventions
2. Revue humaine ciblée :
   • Logique métier (erreur la plus fréquente)
   • Cas limites
   • Perf (N+1, etc.)
   • Sécurité (SQL, XSS…)
3. Tests : suite complète, pas de régression

Ne pas relire chaque ligne — ciblez le cœur et les risques.

Sur mes grands projets, ~15 à 20 % du code Agent pose problème :

• 5 % bugs graves (logique, sécurité)
• 10 % qualité (perf, maintenabilité)
• 5 % « tourne mais hors normes »

Sans revue, ces problèmes émergent des semaines plus tard — diagnostic bien plus coûteux.

Astuce 7 : Git, votre dernière assurance

Basique — mais souvent négligé.

git diff

Après l’Agent, avant les tests :

git diff

Quels fichiers, quels changements. Je vérifie :

• Volume cohérent avec la tâche (dizaines de fichiers → alerte)
• Pas de fichiers hors scope
• Logique centrale intacte ou volontairement modifiée

Astuce : git diff --stat d’abord :

git diff --stat

# Exemple :
# src/api/auth.ts          | 25 +++++---
# src/models/User.ts       | 12 ++--
# src/utils/password.ts    |  3 +-
# src/config/database.ts   | 150 ++++++++++++++++++++++++++++++++++++++++++++++

+150 lignes sur database.ts alors que la tâche ne le demandait pas → allez voir tout de suite.

Checkpoint + Git

1. Avant la tâche :
   - git checkout -b feature/xxx
   - Create Cursor Checkpoint

2. Après l'Agent :
   - git diff
   - tests
   - OK → git commit
   - KO :
     - petit : correction manuelle ou consigne ciblée
     - gros : rollback Checkpoint ou git reset --hard

3. Validé :
   - git push
   - Pull Request

• Checkpoint : rollback rapide
• Branche Git : isolation
• Commits : traçabilité

J’indique dans le message :

git commit -m "feat: ajout inscription utilisateur (by AI Agent)"

Plus tard, un commit « by AI Agent » → prudence renforcée au debug.

Conclusion

Retour à la scène du début, passé minuit.

Aujourd’hui, pour refactoriser le module connexion avec Cursor Agent :

1. Contexte : .cursorrules ciblées auth ; @ sur les 5 fichiers clés ; « ne modifiez que ces 5 fichiers »
2. Découpage : connexion de base d’abord, puis validation, puis cache — pas tout d’un coup
3. Revue : git diff après chaque petit bloc, tests, puis suite

Résultat : fichiers introuvables ~50 % → moins de 10 % ; mauvaises modifications ~30 % → moins de 5 %. Coût extra : 5 à 10 minutes par tâche.

Les outils IA ne remplacent ni l’architecture, ni la compréhension métier, ni la responsabilité qualité. Bien pilotés, ils peuvent doubler votre efficacité.

Contexte, découpage, revue — les trois dimensions se complètent. Contexte → l’Agent « vise juste » ; découpage → il « fait juste » ; revue → vous « dormez tranquille ».

Si vous utilisez Cursor Agent sur un grand projet : prenez 10 minutes aujourd’hui pour vos Project Rules. Passez always en auto + glob — seul ce changement économise des tokens et améliore nettement les résultats.

Les outils évoluent ; les principes restent : besoin clair, tâches découpées, validation continue. Valable pour l’IA comme pour tout projet complexe.

Et vous ? Quels pièges avez-vous rencontrés avec Cursor Agent ? Partagez en commentaire.