Gouvernance de l'indexation Cursor pour les grands projets : du diagnostic à la reconstruction

La semaine dernière, j’ai audité l’ingénierie Cursor d’une équipe dont le Monorepo compte plus de 200 packages. À chaque ouverture du projet, les infobulles au survol mettaient 4 secondes à apparaître et la complétion répondait en moyenne en 6 secondes — une ligne de code, une gorgée de café, puis l’attente. L’équipe a passé deux jours à upgrader le matériel, changer de modèle et réinstaller Cursor. Le problème ne venait ni du modèle ni du réseau : Cursor indexait par défaut tout l’arborescence de packages/ comme contexte. Cet article vous propose un flux de diagnostic, des modèles de configuration et un plan de reconstruction pour retrouver la fluidité en 10 minutes.

Aperçu du mécanisme d’indexation Cursor — comprendre en 5 minutes pourquoi c’est lent

L’arbre de Merkle est l’acteur principal en coulisses. Cursor l’utilise pour suivre les changements de fichiers : chaque fichier reçoit un hash, chaque dossier un hash basé sur ceux de ses fichiers, et ainsi de suite jusqu’à la racine. Un fichier modifié ? Son hash change, celui de son dossier aussi, et la modification remonte jusqu’à la racine. Cursor ne réindexe que les fichiers modifiés, pas tout le dépôt.

Le problème, c’est ailleurs. Votre node_modules peut contenir 50 000 fichiers, chacun hashé — rien que les données de hash pèsent 3,2 Mo. Pire encore, Cursor calcule aussi des vecteurs d’embedding pour ces fichiers : le code des packages npm n’a souvent aucun rapport avec votre logique métier, mais l’indexeur ne le sait pas et indexe tout consciencieusement.

D’après le blog officiel de Cursor, la première requête au 99e percentile sur un grand dépôt prend 4,03 heures. Mais le travail en équipe apporte un avantage caché : entre clones d’un même dépôt, 92 % des fichiers sont en moyenne similaires. Cursor réutilise ces index et ramène la première requête à 21 secondes. Si votre index est propre, vos collègues profitent directement du cache que vous avez calculé.

En résumé : l’indexation est lente non parce que Cursor calcule mal, mais parce qu’il indexe trop de choses — dont beaucoup ne devraient pas l’être.

Flux de diagnostic — 3 étapes pour identifier le coupable

Ne changez pas la config dans la précipitation : diagnostiquez d’abord.

Étape 1 : vérifier l’état de l’index. Ouvrez le projet et regardez l’icône en bas à droite de la barre d’état. Si « Indexing… » reste affiché ou si la barre de progression est bloquée, l’indexation pose problème. Appuyez sur Cmd+Shift+P (Windows : Ctrl+Shift+P), saisissez « Show Cursor Logs », puis consultez les dernières lignes. Vous verrez par exemple « Indexing 1,342 files… » — plus de 5 000 ? C’est très probablement la cause.

Étape 2 : lister les dossiers suspects. Dans le terminal, à la racine du projet, exécutez find . -type d -name "node_modules" -o -name "dist" -o -name "build" -o -name ".git" | wc -l. Les « tueurs d’index » habituels :

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

Obtenir -15 % →Pub

Étape 3 : surveiller CPU et mémoire. Ouvrez Activity Monitor (macOS) ou le Gestionnaire des tâches (Windows) et observez le processus Cursor. CPU au-dessus de 80 %, mémoire au-delà de 4 Go ? L’index calcule frénétiquement hashes et embeddings.

Cet arbre de décision aide à cibler rapidement :

D’après le Troubleshooting Guide de Zest, 90 % des instabilités Cursor viennent de conflits d’extensions ou d’une mauvaise configuration d’index. Vous êtes probablement dans le second cas.

Configuration .cursorignore — 3 modèles pour les scénarios courants

La syntaxe de .cursorignore est identique à celle de .gitignore ; placez-le à la racine du projet. Cursor n’indexera pas son contenu.

Modèle 1 : projet JavaScript/TypeScript

# Dépendances
node_modules/
.npm/
.yarn/

# Artefacts de build
dist/
build/
out/
.next/
.nuxt/

# Tests et couverture
coverage/
.nyc_output/

# Logs et fichiers temporaires
*.log
*.tmp
.DS_Store

Avec un Monorepo (pnpm workspace par exemple), vous pouvez indexer par étapes : exclure tous les packages, puis rouvrir celui que vous modifiez.

# Indexation par étapes Monorepo
packages/*/
!packages/api/        # Package en cours de développement
!packages/shared/     # Bibliothèque partagée, souvent référencée
node_modules/
dist/

Modèle 2 : projet Python

# Environnement virtuel
venv/
.venv/
env/
.env/

# Cache de compilation
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# Artefacts de packaging
*.egg-info/
build/
dist/

# Jupyter Notebook
.ipynb_checkpoints/

Un environnement virtuel Python contient souvent des milliers de fichiers, surtout du code tiers. Exclure venv/ peut réduire la taille de l’index de 90 %.

Modèle 3 : projet Go

# Cache des dépendances
vendor/

# Artefacts de build
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib

# Cache de tests
*.test
*.out
coverage.txt

Le dossier vendor/ de Go ressemble à node_modules/ : des milliers de fichiers de dépendances.

Comparaison d’effet : Developer Toolkit indique qu’avec les réglages par défaut (sans .cursorignore), la précision du contexte n’atteint que 65 % à cause du bruit ; avec des exclusions adaptées, elle monte à 98 %. En clair : exclure 20 % des fichiers pour gagner 50 % de précision.

Configuration d’espace de travail multi-dépôts pour Monorepo

Si votre Monorepo compte des dizaines de services et que vous attendez l’index à chaque ouverture, un fichier .code-workspace qui ne charge que les packages concernés peut suffire.

Créez workspace.code-workspace à la racine :

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

Commencer →Pub

{
  "folders": [
    {"name": "payments", "path": "./services/payments"},
    {"name": "shared-libs", "path": "./libs"}
  ],
  "settings": {
    "cursor.indexing.maxFileSize": 512000,
    "cursor.chat.scopeSelection": "activeFolder"
  }
}

Ouvrez ce fichier avec Cursor (pas tout le dépôt). La barre latérale n’affiche que payments et shared-libs ; les autres services sont hors champ. L’index ne parcourt que ces dossiers — jusqu’à 10 fois plus rapide.

Réglages clés :

• maxFileSize: 512000 : les fichiers de plus de 512 Ko ne sont pas indexés, évitant que de gros JSON/CSV saturent le contexte
• scopeSelection: "activeFolder" : en mode Agent, le contexte vient du dossier actif, sans recherche inter-packages

Utile sur les grands Monorepos. iamraghuveer cite un projet de 10 services à 5 000 fichiers chacun : l’index peut peser 1 à 5 Go — tout charger surcharge CPU et mémoire. Ne charger que le package en cours ramène l’index vers 50 Mo.

Quand utiliser un espace de travail ?

• Monorepo de plus de 20 packages, relativement indépendants
• Vous développez dans un package sans références croisées fréquentes
• L’équipe est répartie par service

Si les packages sont fortement couplés (microservices partageant des libs), .cursorignore reste plus sûr : exclure l’inutile, garder le nécessaire, sans changer de workspace.

Nettoyage du cache et reconstruction de l’index — de la lenteur à la fluidité

Parfois, après avoir modifié la config, l’index reste incohérent — le cache peut conserver d’anciens hashes. Il faut alors nettoyer.

Nettoyage rapide (à essayer en premier)

Cmd+Shift+P, saisissez « Reindex Codebase », validez. Cursor rescanne le projet et reconstruit l’index : quelques dizaines de secondes, 2-3 minutes sur un gros projet. La barre d’état repart de 0 % à 100 %.

Nettoyage approfondi (si le rapide échoue)

Supprimez le répertoire de configuration Cursor :

Fermez Cursor, supprimez (ou sauvegardez ailleurs) ce dossier, puis rouvrez Cursor pour une réinitialisation complète.

⚠️ Attention : cela efface réglages personnalisés (settings.json), raccourcis clavier et config des extensions. Sauvegardez d’abord User/settings.json.

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

Voir les tarifs →Pub

Réinitialisation complète

1. Fermer Cursor
2. Sauvegarder ~/Library/Application Support/Cursor/User/settings.json si présent
3. Supprimer tout le répertoire de configuration
4. Relancer Cursor
5. Attendre la réindexation (plusieurs minutes)
6. Restaurer settings.json

D’après Zest, redémarrage → cache → vérification d’état règle 80 % des problèmes d’index en 5 minutes. Le nettoyage rapide suffit le plus souvent ; le profond, surtout si .cursorignore a changé sans effet.

Quand reconstruire l’index ?

• « Indexing… » bloqué plus de 10 minutes
• Complétion passée de 1-2 s à plus de 5 s pendant plusieurs jours
• Après .cursorignore, @codebase inclut encore des fichiers exclus

Conclusion

La lenteur d’indexation Cursor vient surtout d’un index trop large. La solution est directe : diagnostiquer, exclure, reconstruire.

Liste d’actions :

1. Ouvrir le grand projet, Cmd+Shift+P → « Show Cursor Logs », noter le nombre de fichiers indexés
2. Au-delà de 5 000 fichiers, créer .cursorignore (copier un modèle de cet article)
3. Exclure node_modules/, dist/, .git/ et autres artefacts
4. Exécuter « Reindex Codebase » et attendre la fin
5. Si c’est encore lent, vérifier CPU/mémoire et envisager .code-workspace pour le package actif

Maintenance à long terme :

• À chaque nouvelle dépendance ou config de build, revoir .cursorignore
• Commiter .cursorignore à la racine pour une config d’équipe homogène
• Sur un grand Monorepo, nettoyer périodiquement les index des services inactifs

Essayez maintenant. En 10 minutes, Cursor redevient fluide — complétion en 1-2 secondes, @codebase réactif, infobulles instantanées. Votre productivité revient.

Références

Sources des données citées :

• Securely indexing large codebases - Cursor — Blog officiel Cursor, 2026-01-27
• Performance Optimization for Cursor - Developer Toolkit — Blog technique, 2026-05-28
• Cursor Codebase Indexing for Multi-Repo Workspaces - iamraghuveer — Blog personnel, 2026-04-25
• A Practical Guide to Cursor Troubleshooting - Zest — Blog technique, 2025-12-24
• How to setup Cursor for Large Scale Repositories - NOVA AI — Blog technique, 2026-04-07