Indexation de la base de code avec Cursor : Comment l'optimiser

L'indexation de la base de code de Cursor est ce qui lui donne cet aspect "intelligent" vis-à-vis de votre projet. Quand ça fonctionne, vous obtenez des suggestions pertinentes, des @-mentions précises et des réponses qui comprennent réellement votre architecture. Quand ça ne fonctionne pas, Cursor est aveugle.

Ce guide explique comment l'indexation fonctionne et comment l'optimiser.

Comment Cursor comprend votre base de code

Cursor construit deux choses en arrière-plan :

1. Embeddings — Représentations vectorielles de vos fichiers de code. Lorsque vous posez une question ou utilisez @, Cursor recherche dans ces vecteurs pour trouver les fichiers les plus pertinents sémantiquement.

2. Analyse AST (Abstract Syntax Tree) — Cursor analyse votre code pour comprendre les imports, les définitions de fonctions, les hiérarchies de classes et les relations entre les fichiers.

Ces deux systèmes fonctionnent ensemble. Les embeddings trouvent "ce qui semble pertinent", et l'analyse AST détermine "ce qui est réellement connecté".

info

L'indexation se fait automatiquement lorsque vous ouvrez un projet. Pour les grandes bases de code, le scan initial peut prendre quelques minutes. Vous verrez un indicateur de progression dans la barre d'état.

@-Symboles : La bonne façon de les utiliser

Le symbole @ est votre ligne directe vers l'indexation de Cursor. Utilisez-le pour tirer un contexte spécifique dans le chat ou les éditions inline.

@file — Référencer un fichier spécifique

@src/utils/auth.ts comment fonctionne la validation du token ?

C'est la méthode la plus fiable pour s'assurer que Cursor voit exactement le fichier qui vous intéresse. Elle contourne la recherche par embeddings et attache le contenu complet du fichier (jusqu'aux limites de contexte).

@folder — Référencer tout un répertoire

@src/components expliquez la hiérarchie des composants ici

Utile pour les questions d'architecture, mais attention — les dossiers volumineux peuvent rapidement saturer votre fenêtre de contexte.

@code — Référencer un symbole spécifique

@code:validateUser quels cas limites cette fonction gère-t-elle ?

Cela utilise l'index AST pour trouver la fonction, classe ou variable exacte. C'est précis et efficace en termes de contexte.

astuce

Privilégiez @code: plutôt que @file quand vous n'avez besoin que d'une fonction. Cela économise de l'espace de contexte et réduit le bruit.

Optimiser pour les grands projets

Si votre projet compte des milliers de fichiers, l'indexation par défaut peut manquer des choses ou sembler lente.

Vérifier ce qui est réellement indexé

Ouvrez Paramètres Cursor > Général > Indexation de la base de code. Vous verrez :

• Nombre total de fichiers indexés
• Dernière heure d'indexation
• Les fichiers qui n'ont pas pu être analysés

Augmenter la pertinence du contexte

Pour les monorepos, Cursor peut parfois récupérer des fichiers non pertinents. Soyez explicite dans vos prompts :

Regarde uniquement dans @packages/api/src pour cette question. Ignore le code frontend.

Diviser les fichiers géants

Les fichiers de plusieurs milliers de lignes peuvent poser problème. Cursor peut n'indexer que le début ou avoir du mal avec les embeddings. Si vous avez un fichier utilitaire de 5000 lignes, envisagez de le diviser.

Ignorer des fichiers avec .cursorignore

Tout ne doit pas être indexé. Les fichiers générés, les sorties de build et le code tiers gaspillent l'espace de contexte et polluent les résultats de recherche.

Créez un fichier .cursorignore à la racine de votre projet :

# Sortie de build
dist/
build/
.out/

# Dépendances
node_modules/
vendor/

# Fichiers générés
*.generated.ts
*.min.js
coverage/

# Fichiers de données volumineux
*.csv
*.json

attention

.cursorignore utilise la même syntaxe que .gitignore, mais c'est un fichier séparé. Ne présumez pas que votre .gitignore suffit — Cursor ne le respecte pas automatiquement.

Après avoir édité .cursorignore, redémarrez Cursor ou attendez une minute pour la réindexation.

Quand l'indexation déraille : Dépannage

Parfois, Cursor ne "voit" clairement pas votre code. Voici la liste de contrôle :

1. Vérifier si le fichier est indexé

Ouvrez le fichier, puis demandez :

Quel fichier est-ce que je regarde actuellement ?

Si Cursor ne peut pas répondre, le fichier n'est peut-être pas dans l'index.

2. Forcer une réindexation

Palette de commandes (Ctrl+Shift+P) → "Cursor : Réindexer la base de code"

Cela reconstruit l'index entier à partir de zéro. Cela prend du temps mais corrige la plupart des problèmes de corruption.

3. Chercher les erreurs d'analyse

Dans Paramètres > Général > Indexation de la base de code, vérifiez les fichiers avec des indicateurs d'erreur rouges. Ces fichiers ne sont pas analysés pour les relations AST.

Causes courantes :

• Erreurs de syntaxe dans le fichier
• Langage non supporté (Cursor supporte bien environ 20 langages)
• Fichiers binaires ou minifiés identifiés à tort comme du code source

4. Vérifier que .cursorignore n'est pas trop agressif

Si vous avez ignoré *.config.* et que votre vite.config.ts contient des alias de chemins importants, Cursor ne comprendra pas vos imports.

Améliorer la qualité du contexte

Faire entrer les bons fichiers dans le contexte n'est que la moitié du combat. Comment vous utilisez ce contexte compte aussi.

Soyez spécifique dans vos questions

Mauvais :

Comment fonctionne l'authentification ?

Bon :

Dans @src/auth/middleware.ts, comment la vérification JWT gère-t-elle les tokens expirés ?

Enchaînez votre contexte

Si Cursor donne une réponse partielle, suivez avec des références @ plus spécifiques plutôt que de répéter toute la question.

Vous avez mentionné le rate limiting. @src/middleware/rateLimit.ts — comment la limite est-elle calculée ?

Utilisez les fichiers récents

Cursor pondère plus fortement les fichiers récemment ouverts dans la recherche par embeddings. Si vous venez d'ouvrir un fichier, les références @ vers des fichiers liés ont plus de chances de fonctionner sans mentions explicites.

astuce

Pour les refactorisations complexes, ouvrez d'abord tous les fichiers que vous prévoyez de modifier. Cela "prépare" l'index pour les traiter comme pertinents.

Résumé

• Cursor utilise embeddings + AST pour comprendre votre code
• Utilisez @file, @folder et @code: pour contrôler le contexte explicitement
• Créez un .cursorignore pour exclure le bruit
• Réindexez quand les choses semblent cassées
• Soyez spécifique dans les prompts — l'index trouve les fichiers, mais vous guidez comment ils sont utilisés

Le panneau de paramètres d'indexation de la base de code montre l'état d'indexation de votre projet et les éventuelles erreurs.