Guide complet .cursorignore Cursor : 3 stratégies pour optimiser l'indexation des grands projets

Mise à jour du 2026-06-08 : revérifié avec la doc officielle de Cursor (juin 2026). Cursor respecte déjà votre .gitignore plus une liste d’exclusion par défaut intégrée (node_modules, lockfiles, artefacts de build, binaires/médias sont déjà largement exclus de l’indexation) ; .cursorignore sert donc surtout de blocage d’accès strict plus exclusions supplémentaires, tandis que .cursorindexingignore ne bloque que l’indexation (la mention @ permet encore de lire le fichier). Par ailleurs, le fichier unique .cursorrules à la racine est désormais legacy (ignoré en mode Agent) — placez vos règles de projet dans .cursor/rules/*.mdc.

Mardi dernier après-midi, j’ouvre le monorepo de l’entreprise — plus de 500 000 lignes. L’icône Syncing de Cursor tourne en bas à droite. Cinq minutes… toujours là. Dix minutes… toujours en indexation. Je reviens avec un café : ça tourne encore, lentement.

Le pire arrive après. L’indexation finit enfin ; je demande à l’IA d’optimiser un composant React. Sa proposition : « modifiez directement node_modules/react-dom/cjs/react-dom.development.js ». Je fixe l’écran trois secondes — l’IA prenait le code des dépendances pour le mien.

J’ai cru un moment que Cursor n’était pas fait pour les gros projets. Puis j’ai découvert .cursorignore. Tout a changé : l’index est passé de 12 à 3 minutes, et l’IA ne propose plus de toucher à node_modules.

Si l’indexation Cursor est lente ou que l’IA se trompe de périmètre, cet article vous donne 3 stratégies immédiates et un modèle de configuration prêt à copier.

Pourquoi l’indexation Cursor est si lente

Commençons par le mécanisme. À l’ouverture du projet, Cursor transforme les fichiers en vecteurs d’embedding — une représentation numérique que l’IA peut exploiter. Chaque fichier est parcouru, vectorisé, stocké. Plus il y a de fichiers, plus c’est long.

La vraie question : est-ce que l’IA doit vraiment tout comprendre ?

La plupart des dépôts contiennent des masses de fichiers peu utiles pour l’assistance au code :

node_modules — le trou noir des dépendances
Un front-end moyen peut compter des dizaines de milliers de fichiers dans node_modules. Cursor les indexe tous, alors que vous n’avez pas besoin que l’IA décortique l’implémentation interne de lodash.

dist/build — déchets de compilation
Code minifié sur une ligne : inutile à indexer, illisible pour l’IA.

.git — l’historique
Des centaines de Mo, parfois des Go. Indexer l’historique Git, c’est du temps perdu.

Gros assets statiques
Vidéos, images, polices — l’IA ne les lit pas ; les indexer ne sert à rien.

Test personnel : projet Next.js ~100k lignes avec node_modules et .next complets → 8 minutes d’index. Après .cursorignore : 2 minutes. Rapport 1:4.

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

Commencer →Pub

La précision compte autant. Quand le contexte est noyé sous node_modules, l’IA mélange votre code et les libs — d’où les suggestions de modifier des packages ou de confondre des API tierces avec les vôtres.

Guide complet de configuration .cursorignore

Bonne nouvelle : la syntaxe est identique à .gitignore. Si vous maîtrisez l’un, l’autre est trivial.

Syntaxe de base

Créez .cursorignore à la racine (avec le point) :

# Commentaire avec #

# Fichier précis
config.json

# Dossier (slash final)
node_modules/
dist/

# Wildcards
*.log          # tous les logs
**/*.test.js   # tests à tous niveaux

# Négation (réinclure)
!important.log

Modèle prêt à l’emploi

Configuration de base pour la majorité des projets :

# Dépendances
node_modules/
.pnp/
.pnp.js
vendor/
packages/

# Builds
dist/
build/
out/
.next/
.nuxt/
.cache/
.vite/
.turbo/

# Tests et couverture
coverage/
.nyc_output/
*.spec.js
*.test.js
__tests__/

# Logs et temporaires
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.swp
*.swo
*~

# Environnement (sécurité)
.env
.env.local
.env.*.local
credentials.json
*.key
*.pem

# Contrôle de version
.git/
.svn/
.hg/

# IDE (optionnel)
.vscode/
.idea/
*.sublime-*

# Gros fichiers (ajuster selon besoin)
*.mp4
*.mov
*.avi
*.zip
*.tar.gz
*.pdf
public/videos/

Couvre ~90 % des cas. Enregistrez, puis Settings > Features > Codebase Indexing → Refresh.

Config avancée par scénario

React/Vue — exclure les gros fichiers sous public/ :

public/assets/
public/images/*.png
public/fonts/

Monorepo — exclure les packages hors périmètre :

apps/mobile/
apps/admin/
packages/backend-utils/

Full-stack — séparer front et back :

# Plutôt front
server/
api/
database/
migrations/

# Plutôt back
client/
public/
src/components/

Astuce debug : même si la commande est Git, la syntaxe étant la même :

git check-ignore -v [chemin-du-fichier]

.cursorignore vs .cursorindexingignore — le bon outil

Au début, les deux noms me semblaient interchangeables. En réalité : .cursorignore = blocage total ; .cursorindexingignore = blocage partiel.

Différence essentielle

.cursorignore : l’IA n’y accède pas — pas d’index, pas de lecture. Fichiers sensibles (.env, clés) ou inutiles (node_modules, builds).

.cursorindexingignore : hors des recherches codebase, mais lecture possible à la demande (par mention @ ou glisser-déposer). Ajouté plus tard pour la performance, sans fermer la porte.

Exemple : dossier legacy/ de trois ans — vous ne voulez pas polluer la recherche, mais l’IA peut parfois s’y référer → .cursorindexingignore.

Tableau des usages

Priorité des règles

1. .gitignore du projet (respect automatique)
2. .cursorignore (peut surcharger avec !)
3. .cursorindexingignore

Exemple : logs/ ignoré par Git mais un fichier de debug doit rester visible pour l’IA :

!logs/important-debug.log

« Hierarchical Cursor Ignore » (dans Settings) : Cursor remonte les .cursorignore parents — pratique pour un monorepo avec config racine + règles par sous-projet.

Ma stratégie

Dans 90 % des cas, .cursorignore suffit. .cursorindexingignore est un affinage pour projets très lourds ou structures complexes.

Approche progressive :

• D’abord .cursorignore pour l’évident
• Une semaine d’observation
• Puis .cursorindexingignore si besoin

Ne surchargez pas dès le départ.

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

Obtenir -15 % →Pub

3 stratégies d’optimisation pour les monorepos

Les monorepos sont ceux qui font le plus souvent « planter » l’expérience Cursor : front, back, mobile, admin… L’IA se perd.

Sur un monorepo de 12 apps, l’IA m’a conseillé d’importer une util du package API dans un composant front — logique en apparence, impossible à l’exécution (environnements séparés).

Trois stratégies qui tiennent la route :

Stratégie 1 : découper l’index par zone de travail

Excluez ce que vous ne touchez pas.

Équipe front sur apps/web :

apps/mobile/
apps/admin/
apps/api/
packages/backend-utils/
packages/database/
services/

Index plus rapide, moins de bruit. Chez moi : deux packages gardés → 15 min → 4 min.

Full-stack qui alterne : .cursorignore.frontend / .cursorignore.backend, copier le bon fichier vers .cursorignore.

Stratégie 2 : Project Rules pour la structure

L’IA ne devine pas toujours les liens entre dossiers. Utilisez les Project Rules comme carte du projet. Note : l’ancien fichier unique .cursorrules à la racine est désormais legacy et ignoré en mode Agent ; pour les nouveaux projets, utilisez des fichiers .mdc dans .cursor/rules/ (pas .cursorignore). Créez par exemple .cursor/rules/project-structure.mdc avec un frontmatter YAML (description, globs, alwaysApply) :

---
description: structure du monorepo et règles d'import
alwaysApply: true
---

# Structure du projet

Monorepo avec :

- apps/web: front Next.js, port 3000
- apps/api: API Node.js + Express, port 8000
- apps/admin: admin React, port 3001
- packages/ui: composants partagés
- packages/utils: utilitaires communs

## Règles d'import

- web/admin → packages/ui et packages/utils uniquement
- pas d'import direct de apps/api depuis le front
- packages/* ne dépendent pas des apps/*

## Focus actuel

Développement sur apps/web — suggestions centrées sur le front.

L’IA lit ces règles ; les recommandations hors frontière deviennent rares.

Stratégie 3 : une fenêtre par sous-application

Monorepo énorme (20+ apps) : même avec .cursorignore, une seule fenêtre reste trop large.

• Fenêtre 1 : apps/web
• Fenêtre 2 : apps/api
• Fenêtre 3 : packages/ui

Index et contexte séparés, suggestions plus précises. Coût : changer de fenêtre — souvent rentable.

Dépendance entre apps (web → ui) : dans la fenêtre web, citez explicitement :

@folder packages/ui Vérifiez la définition des props du composant Button

Léger par fenêtre, accès aux packages quand il faut.

Idée directrice monorepo

Ne montrer à l’IA que ce qu’elle doit voir.

Plus le dépôt est grand, plus il faut soustraire. Aidez-la à tracer des frontières — elle répondra mieux.

Vérifier et maintenir la configuration

.cursorignore n’est pas « configure et oublie ». Il faut valider et entretenir.

Vérifier que ça marche

Le plus simple : comparer la durée Syncing avant/après.

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

Commencer →Pub

Méthodes plus précises :

1. État de l’index — Settings > Features > Codebase Indexing : le nombre de fichiers doit baisser.
2. Périmètre IA — @codebase : après exclusion de node_modules, « quels composants React » ne doit pas lister node_modules/react.
3. Recherche — Cmd/Ctrl + P sur un fichier dans un dossier exclu : introuvable = OK.

Quand rafraîchir manuellement

L’incrémental ne suffit pas toujours :

• modification de .cursorignore
• gros changement de branche Git
• ajout/suppression massif de fichiers
• réponses IA incohérentes (index peut-être périmé)

Settings > Features > Codebase Indexing > Refresh, attendre la fin du Syncing.

Maintenance courante

Checklist mensuelle :

• nouveaux dossiers de build (ex. .output/ après upgrade)
• nouveaux gros répertoires à exclure
• règles obsolètes à retirer

Équipe :

• règles communes (node_modules, dist) → Git
• préférences perso → .git/info/exclude ou .cursorignore.local

Dans .gitignore :

.cursorignore.local

Commentaires dans le fichier :

# 2025-01-15: données d'entraînement IA, trop volumineux
data/training/

# 2025-01-10: perf-tests, logs massifs
perf-tests/

Dans trois mois, vous serez content d’avoir documenté.

À lire aussi

• Indexation de la base de code Cursor : principes, configuration et symbole @
• Cursor sur les gros projets : garder l’Agent sur les rails dans un grand dépôt
• Guide complet du quota gratuit de Cursor

Synthèse

Indexation lente, IA à côté de la plaque — ce n’est pas forcément que l’outil est mauvais. Souvent, on n’a pas dit à l’IA quoi regarder et quoi ignorer.

.cursorignore est simple et puissant. Cinq minutes de setup peuvent économiser des heures d’attente et améliorer nettement la qualité des suggestions.

Trois actions :

1. Maintenant : copier le modèle de base, créer .cursorignore à la racine
2. Adapter : règles React/Vue/monorepo selon votre cas
3. Itérer : une semaine d’observation, noter les écarts, ajuster

Pas besoin de la perfection du premier coup — 80 % avec le modèle de base, le reste au fil de l’usage.

Sur un gros projet avec Cursor, essayez ces pistes. Partagez vos configs ou galères en commentaire — ça peut aider d’autres développeurs dans la même situation.