Guide complet de l'indexation Cursor Codebase : principes, configuration et @ symboles en pratique

Mise à jour du 2026-06-08 : revérifié avec la doc officielle de Cursor — les réglages d’indexation se trouvent désormais sous Cursor Settings → Indexing & Docs (vérifiable via « View included files ») ; les morceaux de code sont en fait chiffrés puis envoyés aux serveurs de Cursor pour générer des embeddings stockés dans une base vectorielle distante (pas un index FAISS purement local) — mais le code source n’est jamais stocké en clair et les index sont supprimés après 6 semaines d’inactivité ; la synchronisation tourne environ toutes les 5 minutes. Le texte ci-dessous est mis à jour en conséquence.

La cinquième suggestion erronée de Cursor à l’écran.

« Aide-moi à corriger ce bug de connexion » — la demande était pourtant claire. Cursor proposait du code sans savoir qu’il existait déjà une fonction utilitaire auth dans le projet, et me faisait réécrire toute la logique de validation. Pire : il suggérait de placer le code dans un dossier utils… qui n’existe pas dans ce projet.

Ce jour-là, j’ai compris : aussi intelligent soit-il, sans vue d’ensemble du projet, l’IA n’est qu’un robot qui code — ses suggestions restent à côté de la plaque.

Vingt minutes plus tard, j’avais configuré l’indexation Codebase et le fichier .cursorignore. Nouvel essai : Cursor a tout de suite saisi le contexte — trouvé la fonction auth, repéré trois duplications de validation, proposé une encapsulation commune. Ce sentiment que « l’IA comprend enfin mon projet », c’est vraiment satisfaisant.

Les fondements de l’indexation Cursor

Qu’est-ce que l’indexation Codebase ?

Franchement, au début, le mot « indexation » me perdait. Ça sonne technique, mais une fois compris, c’est simple.

Imaginez une bibliothèque sans catalogue : vous parcourez rayon par rayon, peut-être une journée entière. Avec un index, titre ou mot-clé en main, vous localisez le livre en quelques secondes.

L’indexation Codebase de Cursor, c’est la même idée — un « catalogue intelligent » de tout le projet pour que l’IA trouve vite le code pertinent au lieu de deviner.

Concrètement, Cursor scanne vos fichiers, analyse fonctions, classes et variables, puis leur assigne des « étiquettes » mathématiques (vectorisation). Quand vous posez une question, l’IA fait correspondre en un instant les extraits les plus pertinents.

Les six étapes clés de l’indexation

Je ne rentre pas dans tous les détails techniques — ce serait ennuyeux. Mais comprendre le flux explique pourquoi l’indexation peut être lente et pourquoi .cursorignore compte.

Étape 1 : scan et prétraitement des fichiers

À l’ouverture du projet, Cursor scanne tous les fichiers en respectant .gitignore et .cursorignore. Sans .cursorignore, il peut indexer node_modules — des dizaines de milliers de fichiers inutiles.

Étape 2 : découpage du code

Cursor ne traite pas un fichier entier comme un bloc unique. Il découpe par fonctions, classes et blocs logiques. Un utilitaire de 1 000 lignes peut devenir 30 morceaux indexés séparément — meilleure précision à la requête.

Étape 3 : embeddings vectoriels (le cœur)

En termes simples : la vectorisation transforme le code en suite de nombres — une « empreinte ». Des codes similaires ont des empreintes proches. Deux fonctions de login différentes restent voisines dans l’espace mathématique.

Étape 4 : construction de la base vectorielle

Beaucoup de guides se trompent ici. En réalité, les morceaux de code sont chiffrés puis envoyés aux serveurs de Cursor pour générer les embeddings ; ces vecteurs — avec des chemins de fichiers obfusqués et des numéros de ligne — sont stockés dans une base vectorielle distante (Cursor utilise un service comme Turbopuffer), avec une synchronisation incrémentale via un arbre de Merkle. L’index n’est donc pas purement local — mais Cursor indique que le code source n’est jamais stocké en clair (rejeté après la requête), que les noms de fichiers sont obfusqués/chiffrés, et que les index sont supprimés après 6 semaines d’inactivité.

Étape 5 : correspondance à la requête

Quand vous tapez « aide-moi à optimiser la connexion », Cursor vectorise la phrase et cherche les empreintes les plus proches — en millisecondes.

Étape 6 : injection dans le contexte

Les extraits trouvés sont injectés dans le contexte envoyé au modèle. L’IA voit votre vrai code ; les réponses deviennent fiables.

Pourquoi l’indexation est-elle si importante ?

J’ai fait l’expérience : même demande, sans index Cursor ne voit que le fichier ouvert — réponses souvent à côté. Avec index, il relie 3 à 5 fichiers et propose des solutions directement utilisables.

L’écart est énorme. Un bug touchait API, couche données et UI. Sans index, j’@ais trois fichiers et expliquais leurs relations. Avec index, « pourquoi les données utilisateur ne se mettent pas à jour » — Cursor a trouvé les trois fichiers et un quatrième oublié (validation middleware).

Confidentialité et sécurité

« Upload cloud », « IA qui analyse le code » — beaucoup s’inquiètent. Moi aussi, au début.

D’abord le mécanisme (que beaucoup de guides présentent mal) : lors de l’indexation, les morceaux de code sont chiffrés puis envoyés aux serveurs de Cursor pour calculer les embeddings. Mais il y a de vraies protections :

1. Le code source n’est pas stocké en clair — le serveur ne le traite que pendant la requête puis le rejette ; la base ne contient que des vecteurs, pas votre source
2. Noms de fichiers/chemins obfusqués et chiffrés — même avec les données vectorielles, impossible de reconstituer la structure du projet
3. Suppression automatique après 6 semaines — les index longtemps inactifs sont supprimés ; rouvrir le projet relance l’indexation
4. Privacy Mode — le mode confidentialité des paramètres limite encore la rétention

Pour des projets très sensibles (finance, santé), j’active Privacy Mode et j’évalue avec soin ; pour le web courant ou les projets perso, le mode par défaut convient. Mais l’idée que « votre code ne quitte jamais votre machine » est inexacte — gardez-le en tête.

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

Commencer →Pub

Guide complet des symboles @

Au début, je pensais que @ c’était @. En réalité, chaque variante a son usage ; mal choisir fait perdre du temps ou produit des réponses absurdes.

Ce chapitre détaille les 6 symboles @ : usage, scénarios, avantages et limites.

@Codebase — contexte projet entier

Usage : faire comprendre à l’IA la structure et la logique globales.

Le @ le plus puissant, souvent sous-estimé. Avec @Codebase, Cursor interroge l’index et remonte les extraits les plus pertinents.

Scénarios :

• Débogage inter-fichiers : « pourquoi les données ne se synchronisent pas après login ? »
• Architecture : « où le projet gère-t-il l’autorisation ? »
• Nouveau projet : « comment sont organisées les routes ? »

Retour d’expérience : reprise d’un vieux projet sans doc, des milliers de fichiers. @Codebase comment est implémenté le flux de paiement ? — 5 fichiers en chaîne, de l’API au callback. Manuellement : une demi-journée.

Limites :

• Qualité de l’index ; mal configuré, résultats dégradés
• Plus lent (1-3 s) — recherche sur toute la base
• Très gros projets (100k+ lignes) : code périphérique parfois manqué

@Files — référence précise de fichiers

Usage : indiquer explicitement les fichiers concernés.

Le plus direct : @Files ouvre le sélecteur ; l’IA ne lit que votre sélection.

Scénarios :

• Vous connaissez les fichiers impliqués
• Modification ciblée
• Éviter le bruit

Exemple : refactor d’un composant (composant, styles, tests). @Files sur les trois, puis « passe ce composant en fonctionnel » — réponse focalisée.

Avantages : précision, rapidité, contrôle
Inconvénients : il faut connaître les fichiers ; risque d’oubli

@Folders — référence au niveau dossier

Usage : contexte d’un dossier entier.

Quand le problème est dans un module sans connaître le fichier exact.

Scénarios :

• « Optimiser tous les composants de /components/auth/ »
• « Vérifier la sécurité du dossier /api/ »
• Traitement par lot d’un module

Attention : un gros dossier dépasse la limite de contexte. Moins de ~10 fichiers, idéalement. Au-delà, troncature possible.

@Code — extrait de code précis

Usage : référencer une fonction, classe ou bloc.

Sélectionnez du code → « Add to Chat », ou @Code puis le nom de la fonction.

Scénarios :

• « Cette fonction validateUser a un bug »
• « Refactorise ce bloc pour plus de clarté »
• Revue de code ciblée

Usage favori : dans un utilitaire de 1 000 lignes, ne cibler qu’une fonction de 50 lignes — l’IA ignore le reste.

@Docs — documentation externe

Usage : référencer docs officielles, API, etc.

Ajouté fin 2024 — peu connu.

Scénarios :

• « Selon la doc Next.js, configure les routes dynamiques »
• « Génère le code d’appel d’après cette API »
• Apprentissage d’une techno avec la doc

Usage : @Docs, URL ou docs intégrées Cursor.

Limites :

• Frameworks mainstream seulement
• URLs custom parfois en échec (réseau, format)

@Web — recherche web en temps réel

Usage : l’IA cherche en ligne.

Pour une lib tout juste sortie, non présente dans l’entraînement.

Scénarios :

• « Cherche les nouveautés React 19 »
• « Usage de la dernière version de ce package npm »
• Bugs ou erreurs très récents

Note : plus lent (recherche live). Je l’utilise seulement quand la fraîcheur compte.

Tableau comparatif : quel @ choisir ?

Mon usage au quotidien

Au début, je n’utilisais que @Files — « plus sûr ». Puis j’ai vu que dans 80 % des cas @Codebase est plus efficace : l’IA trouve plus vite que moi et révèle des liens oubliés.

Aujourd’hui :

• @Codebase : 60 %
• @Files : 30 %
• @Code : 5 %
• Autres : 5 %

Trouvez votre rythme. L’essentiel : connaître chaque @ et le bon contexte.

Configuration .cursorignore en pratique

Il faut parler de .cursorignore. Discret, il peut accélérer l’indexation de 50 %+ et diviser le CPU par deux.

Sans ce fichier, ouverture d’un projet avec node_modules — ventilateur à fond, Cursor gelé. Il indexait 30 000 fichiers de dépendances inutiles.

Pourquoi .cursorignore ?

Tous les fichiers ne méritent pas d’être indexés.

Typiquement :

• Dépendances : node_modules, vendor, .venv — inutiles en pratique
• Build : dist, build, .next — générés, pas source
• Temporaires : .log, .cache, .DS_Store
• Gros assets : vidéos, images lourdes, polices

Exclus, l’index passe de 5 minutes à 30 secondes ; l’IA est plus précise sans bruit.

.cursorignore vs .gitignore

« J’ai déjà .gitignore, .cursorignore sert à quoi ? »

Oui, et la logique diffère.

.gitignore : ce qui ne va pas dans Git. Certains fichiers non versionnés doivent rester visibles par l’IA :

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

Obtenir -15 % →Pub

• Config locale : .env.local — pas dans Git, utile à l’IA
• Notes perso : TODO.md — pas versionné, consultable

À l’inverse, versionnés mais inutiles à l’index :

• package-lock.json
• Rapports de couverture CI

Configurez .cursorignore à part.

Modèle générique (prêt à l’emploi)

Modèle pour la plupart des projets frontend. Créez .cursorignore à la racine :

# Répertoires de dépendances
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# Artefacts de build
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# Journaux et fichiers temporaires
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

# Config IDE et éditeur
.idea/
.vscode/
*.swp
*.swo

# Couverture de tests
coverage/
.nyc_output/

# Assets statiques (optionnel, selon le projet)
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# Gros fichiers JSON (optionnel)
package-lock.json
yarn.lock
pnpm-lock.yaml

Note : base à adapter — Python : ajoutez __pycache__/ et *.pyc.

Stratégies avancées

1. Monorepo : indexation par étapes

Dizaines de packages — indexation complète lente :

# N'indexer que le package en cours
packages/*/node_modules/
packages/package-a/  # package non travaillé pour l'instant
packages/package-b/

Décommentez quand vous travaillez sur un package.

2. Mode liste blanche

Projet chaotique — mieux vaut inclure explicitement :

# Exclure tout
*

# Inclure uniquement src/
!src/
!src/**/*

# Inclure les fichiers de config
!*.config.js
!tsconfig.json

Pour les vieux gros projets — focus sur le cœur.

3. Filtrage par taille

Cursor ignore souvent les fichiers >1 Mo ; vous pouvez exclure manuellement :

# Exclure les gros fichiers de données
*.sql
*.csv
*.json  # si vous avez des JSON de plusieurs dizaines de Mo

Valider la configuration

Deux méthodes après modification de .cursorignore :

Méthode 1 : vitesse d’indexation

Fermez et rouvrez le projet ; observez « Indexing… » en bas à droite. Avant : 3-5 min ; après : 30 s - 1 min.

Méthode 2 : nombre de fichiers

Ouvrez Cursor Settings → Indexing & Docs et cliquez « View included files » pour lister ce qui est réellement indexé. De dizaines de milliers à quelques centaines : OK.

Méthode 3 : test @Codebase

@Codebase quels fichiers compte le projet ? — si node_modules apparaît, vérifiez la syntaxe.

Comparaison des performances

Test sur un vrai projet Next.js :

Les chiffres parlent. .cursorignore est la première étape pour bien utiliser Cursor.

Problèmes courants et solutions

Plus d’un an avec Cursor — index qui échoue, requêtes lentes, CPU saturé. Quatre problèmes fréquents et leurs solutions.

Problème 1 : index bloqué sur « Indexing… » ou échec

Symptômes :

• « Indexing… » des dizaines de minutes
• « Indexing failed »
• @Codebase sans effet

Causes et solutions :

Cause 1 : trop de fichiers, timeout

• Solution : .cursorignore, exclure node_modules, etc.
• Validation : rouvrir le projet — index <2 min

Cause 2 : format non supporté ou fichier corrompu

• Solution : fichiers >10 Mo ou binaires → .cursorignore
• Cas fréquents : vidéos, gros dumps SQL, binaires compilés

Cause 3 : espace disque

• Solution : ~5 Go libres minimum
• Mac : ~/Library/Application Support/Cursor/
• Windows : %APPDATA%\Cursor\

Cause 4 : réseau (sync cloud)

• Solution : tester sans Privacy Mode ou autre réseau
• Temporaire : vérifiez le réglage Privacy Mode, ou que le réseau atteint les serveurs de Cursor

Checklist rapide :

☐ .cursorignore configuré
☐ Nombre de fichiers (>1 000 → optimiser)
☐ Espace disque (≥5 Go)
☐ Redémarrer Cursor
☐ Supprimer le cache et réindexer

Problème 2 : résultats @Codebase imprécis

Symptômes :

• Code existant non trouvé
• Extraits hors sujet

Causes et solutions :

Cause 1 : index incomplet ou obsolète

• Solution : Reindex Codebase
• Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows) → « Reindex Codebase »

Cause 2 : code récent non indexé

• Solution : synchronisation auto (~5 min officiellement) ; patientez un peu ou lancez un Reindex

Cause 3 : question vague

• Solution : précisez. Pas « il y a un bug », mais « pourquoi le token n’est pas sauvé dans localStorage après login »
• ❌ « optimiser les performances »
• ✅ « liste lente, trouver la cause des re-rendus »

Cause 4 : code exclu par erreur

• Solution : vérifiez .cursorignore — pas tout src/ exclu

Astuces précision :

• Noms de fonctions, variables, fichiers concrets
• Scénario métier précis
• Si @Codebase échoue → @Files

Problème 3 : CPU / mémoire élevés

Symptômes :

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

Commencer →Pub

• Ventilateur bruyant
• CPU Cursor >80 %
• Plusieurs Go de RAM
• Système lent

Causes et solutions :

Cause 1 : indexation massive en cours

• Solution : normal en phase d’index ; sinon réduire via .cursorignore

Cause 2 : mises à jour d’index trop fréquentes

• Atténuation : Cursor synchronise par défaut en incrémental (~5 min) ; ajoutez les gros dossiers qui changent souvent à .cursorignore pour réduire la réindexation

Cause 3 : plusieurs gros projets ouverts

• Solution : fermer les fenêtres inutiles

Cause 4 : base d’index corrompue

• Solution : supprimer le cache et réindexer
• Mac : ~/Library/Application Support/Cursor/Index/
• Windows : %APPDATA%\Cursor\Index\

Optimisation :

☐ .cursorignore (<1 000 fichiers cible)
☐ Fermer projets inutiles
☐ Exclure les gros dossiers fréquemment modifiés dans .cursorignore pour réduire la réindexation
☐ Gros projet → @Files plutôt que @Codebase
☐ RAM 16 Go min, 32 Go recommandé

Problème 4 : @Codebase lent

Symptômes :

• 5-10 s d’attente
• Timeouts

Causes et solutions :

Cause 1 : base trop grande

• Solution : .cursorignore — idéal 500-2 000 fichiers

Cause 2 : réseau (modèle cloud)

• Solution : connexion ou modèle plus rapide

Cause 3 : trop de code matché

• Solution : question plus précise ou @Files / @Folders

Cause 4 : matériel faible

• Solution : recherche vectorielle gourmande — 16 Go RAM + SSD

Accélération :

• @Files ou @Folders avant @Codebase
• Nettoyer le cache périodiquement
• Modulariser le projet

Ma méthode de dépannage

90 % des soucis viennent d’un .cursorignore absent ou trop permissif.

Mon ordre :

1. Vérifier .cursorignore
2. Reindex Codebase
3. CPU/RAM — perf ou config ?
4. Supprimer le cache si besoin

Sinon, bug Cursor → issue GitHub.

Cas pratique : indexer un projet Next.js from scratch

Passons à la pratique : projet Next.js réel, de .cursorignore à la validation — 10 minutes.

Synthèse : avant / après

Projet Next.js réel (composants, API routes, BDD) :

Précision mesurée manuellement sur 20 questions réelles — de 60 % à 92 %.

Points clés

Vous savez maintenant :

1. ✅ Créer .cursorignore pour Next.js
2. ✅ Valider l’index
3. ✅ Tester les @
4. ✅ Optimiser selon le projet

Même logique pour React, Vue, Angular ou backend : exclure le bruit, laisser l’IA sur le code utile.

À lire aussi

• Guide complet du mode Agent Cursor
• Dépannage réseau Cursor complet
• Guide complet du niveau gratuit de Cursor

Conclusion

Revenons à la scène du début — une heure du matin, cinquième mauvaise suggestion. Beaucoup l’ont vécu. Sans vue d’ensemble, l’IA devine.

L’indexation règle ce problème.

Trois points essentiels :

1. Comprendre le principe évite les pièges — pourquoi exclure node_modules, pourquoi parfois lent, pourquoi du code manque.

2. .cursorignore en priorité absolue — +50 % vitesse d’index, -50 % CPU, +60 % précision : chiffres mesurés.

3. Les @ par usage, pas par cœur — 80 % @Codebase, 20 % @Files précis. L’habitude vient en pratiquant.

Trois actions maintenant :

1. Créez .cursorignore à la racine — copiez le modèle de cet article
2. Redémarrez Cursor — comparez la vitesse d’index
3. Testez @Codebase — une question que l’IA ratait avant

Dix minutes investies pour des centaines d’heures gagnées ensuite.

Si cet article vous aide, partagez-le avec ceux qui galèrent encore avec l’index Cursor.

L’indexation Cursor évolue. Ce guide a été revérifié avec la doc officielle de mi-2026, mais de nouvelles fonctions et limites peuvent apparaître ; pour tout point non couvert, consultez la doc officielle.

Allez, configurez — ne vous contentez pas de lire.