Cursor @Codebase, @Docs, @Files : lequel choisir ? Guide de décision par scénario

Le système de symboles @ de Cursor paraît simple : @Codebase, @Files, @Docs — un clic et l’IA reçoit du contexte. En pratique, beaucoup butent sur la même question : on sait quel code chercher, mais pas quel symbole utiliser.

Mauvais choix : l’IA injecte du contenu hors sujet, ou ne trouve pas le bon fichier. Au fil du temps, l’historique se remplit de requêtes répétées, les tokens s’envolent, et le problème reste flou.

Cet article ne liste pas les définitions. Il traite une seule chose : comment décider rapidement quel @ utiliser selon le scénario. À la fin, vous aurez une logique claire — sans hésiter à chaque fois.

1. Comparaison des six @ : l’essentiel en un coup d’œil

Commençons par une conclusion clé : selon les statistiques de BetterLink Blog, 80 % du temps de développement devrait utiliser @Codebase plutôt que de sélectionner les fichiers à la main. Ce chiffre semble exagéré, mais la logique est simple : l’avantage de @Codebase n’est pas la recherche, c’est de laisser l’IA découvrir du code associé que vous pourriez ignorer.

Voici les six symboles, classés par fréquence d’usage :

@Codebase (60-80 %) : recherche sémantique sur tout le dépôt. Vous posez une question, l’IA trouve automatiquement les fichiers, fonctions et types les plus pertinents. Pas besoin de connaître l’emplacement ni de sélectionner manuellement. Cas d’usage : compréhension de l’architecture, refactoring, diagnostic inter-fichiers. Consommation de tokens élevée, car l’index couvre tout le dépôt.

@Docs (10-15 %) : référence à la documentation externe. Documentation intégrée (React, Vue, Astro) ou sources personnalisées via URL. Cas d’usage : bibliothèque récemment publiée, dernière spécification API, base de connaissances d’équipe.

@Files (5-10 %) : référence précise au contenu complet d’un fichier. Quand vous connaissez le nom du fichier ou devez modifier une config (comme vite.config.ts). Au-delà de 600 lignes, @Files est plus précis que @Codebase. Coût : tokens élevés, car tout le fichier entre dans le contexte.

@Code (5-10 %) : référence à un extrait de code précis. Seule la sélection est injectée, pas le fichier entier. Cas d’usage : optimisation locale, débogage d’un petit bloc, éviter la pollution du contexte au niveau fichier. Consommation de tokens la plus faible.

@Folders (moins de 5 %) : aperçu de la structure et du contenu d’un répertoire entier. Cas d’usage : refactoring de module, génération de composants, cohérence architecturale. Consommation élevée, plusieurs fichiers impliqués.

@Repo (scénarios spécifiques) : contexte de dépôt. Cas d’usage : projets multi-dépôts, analyse de l’historique des versions, diagnostic inter-repo. Consommation modérée.

Ces six symboles ne s’excluent pas : vous pouvez les combiner dans une même conversation. Par exemple : @Codebase pour la vue globale, @Files pour verrouiller un fichier clé, @Docs pour la doc officielle. L’essentiel : choisir selon le type de question, pas empiler aveuglément.

2. Arbre de décision : type de question → choix du @

La logique repose sur une seule question : connaissez-vous l’emplacement du code ?

Si non → @Codebase. Si oui → @Files ou @Code. S’il manque de la documentation → ajoutez @Docs.

En détail :

Scénario 1 : emplacement inconnu

Vous refactorisez un projet Next.js et voulez modifier le format de retour d’une API, sans savoir où se trouve la définition de type — peut-être dans types/, dans components/, ou dans un utils.ts défini à la volée.

Utilisez @Codebase. Dans le Chat : « Trouve la définition du type ApiResponse et modifie le format de retour. » L’IA scanne le dépôt, trouve toutes les références, y compris ce utils.ts que vous aviez oublié.

Scénario 2 : nom de fichier connu

Vous devez modifier le proxy dans vite.config.ts ou refactoriser une fonction dans src/utils/auth.ts. Chemin clair, fichier long (plus de 600 lignes).

Utilisez @Files. Cliquez sur @Files, sélectionnez le fichier : l’IA reçoit le contenu complet. Plus précis que @Codebase, sans fichiers « pertinents mais hors sujet ».

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

Commencer →Pub

Scénario 3 : consulter la documentation récente

Bibliothèque sortie la semaine dernière, ou dernière syntaxe API d’un framework (données d’entraînement peut-être obsolètes).

Utilisez @Docs. Saisissez @Docs, choisissez la doc intégrée ou collez une URL. Point clé : insistez dans le prompt sur l’utilisation de la syntaxe la plus récente de la documentation, sinon l’IA risque d’employer une ancienne version mémorisée.

Scénario 4 : focus sur un extrait de code

Vous déboguez une fonction et ne voulez optimiser que quelques lignes, sans injecter tout le fichier.

Utilisez @Code. Sélectionnez l’extrait, Cmd+K pour l’édition inline, ou @Code dans le Chat. Tokens minimaux, contexte le plus propre.

Scénario 5 : refactoring de module ou nouveau composant

Refactoriser tout components/ ou générer un module features/ en respectant l’architecture existante.

Utilisez @Folders. Structure du répertoire et contenu clé : l’IA comprend l’organisation du module et génère du code cohérent avec le style existant.

Scénario 6 : multi-dépôts ou analyse d’historique

Projet avec plusieurs dépôts Git, ou analyse de l’impact d’un commit.

Utilisez @Repo. Contexte de dépôt : historique des versions, dépendances inter-dépôts.

En résumé : incertain sur l’emplacement → @Codebase ; emplacement connu → @Files/@Code ; doc manquante → @Docs. @Folders et @Repo complètent des cas spécifiques.

3. @Codebase vs @Files : différence clé et cas pratiques

Ces deux symboles se confondent le plus souvent. La différence : l’IA cherche pour vous, ou vous désignez vous-même.

La valeur de @Codebase n’est pas la « recherche », c’est la « découverte ». Vous posez une question, l’IA fait une correspondance sémantique sur tout le dépôt et renvoie fichiers, fonctions et types. Elle peut renvoyer des fichiers auxquels vous n’aviez pas pensé. Par exemple, pour « comment modifier le format de retour de l’API », l’IA peut renvoyer :

• le handler API (attendu)
• le fichier de définition de types (probablement connu)
• un alias de type défini à la volée dans un utils.ts (facile à oublier)
• des mock dans un fichier de test (souvent ignorés)

C’est l’avantage de @Codebase : l’IA découvre du code associé que vous auriez pu manquer.

@Files, c’est la « précision ». Vous désignez le fichier, l’IA reçoit tout le contenu, sans ambiguïté. Contrepartie : vous devez connaître l’emplacement et accepter une consommation de tokens plus élevée.

Cas pratique 1 : modification du format de retour API (@Codebase préférable)

Scénario : une API Next.js renvoie actuellement :

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

Vous voulez passer à { users, count }, sans savoir où sont les définitions de types.

Avec @Files, vous devez trouver manuellement route.ts, un éventuel types.ts, le composant frontend — risque d’oublier des fichiers.

Avec @Codebase, dans le Chat :

@Codebase
Modifie le format de retour de l'API utilisateurs : de { data, total } à { users, count }.
Synchronise toutes les définitions de types et les appels frontend associés.

L’IA renvoie par exemple :

Fichiers trouvés :
1. src/app/api/users/route.ts - handler API
2. src/types/api.ts - définition ApiResponse
3. src/components/UserList.tsx - composant frontend (appelle l'API)
4. src/utils/mock.ts - mock de test (même format)

Vous voyez tout de suite que mock.ts utilise aussi ce format — un fichier que vous n’aviez pas remarqué.

Cas pratique 2 : optimisation de vite.config.ts (@Files préférable)

Scénario : modifier la config proxy, chemin connu : vite.config.ts.

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

Objectif : proxy multi-environnements (dev, test, prod).

@Files convient mieux :

1. Emplacement clair
2. Fichier court (souvent 50-200 lignes)
3. Pas de recherche inter-fichiers

Dans le Chat :

@Files vite.config.ts
Modifie la config proxy pour supporter plusieurs environnements (dev, test, prod).
Les variables viennent de .env.development, .env.test, .env.production.

L’IA reçoit tout vite.config.ts et propose par exemple :

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

En résumé : emplacement inconnu ou découverte de liens cachés → @Codebase ; emplacement connu ou fichier long à comprendre entièrement → @Files.

4. @Docs : nouvelles bibliothèques et intégration documentaire

@Docs résout un problème : les données d’entraînement de l’IA ne suivent pas la cadence des mises à jour documentaires.

Bibliothèque publiée la semaine dernière, API modifiée (nouveaux hooks React 19, Turbopack par défaut dans Next.js 15) : les données d’entraînement datent peut-être de plusieurs mois, et le code généré utilise une ancienne API.

Principe de @Docs : récupération en temps réel de la documentation que vous indiquez, parsing, injection dans le contexte. L’IA privilégie alors les spécifications les plus récentes.

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

Voir les tarifs →Pub

Mode d’emploi

1. Saisissez @Docs dans le Chat
2. Choisissez une doc intégrée (React, Vue, Astro, Tailwind, Next.js, etc.)
3. Ou collez une URL pour une source personnalisée

Les sources personnalisées sont utiles : base de connaissances interne (Feishu, GitHub Wiki) — l’IA peut suivre vos conventions d’équipe.

Cas pratique : nouveaux hooks React 19

Vous voulez utiliser useOptimistic dans React 19, sans être sûr de la syntaxe actuelle.

@Docs React
Implémente une mise à jour optimiste avec le hook useOptimistic de React 19.
Scénario : bouton like, affichage immédiat +1, puis confirmation serveur.

L’IA consulte d’abord la doc React officielle, puis génère par exemple :

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // affichage immédiat +1
    await onSubmit();     // attente confirmation serveur
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

Attention : les données d’entraînement peuvent écraser @Docs

Piège : l’IA peut mélanger données d’entraînement et @Docs. Si l’ancienne syntaxe est trop ancrée, le code généré mélange parfois ancien et nouveau.

Solution : insistez dans le prompt sur l’utilisation de la syntaxe la plus récente de la documentation.

@Docs React
Utilise la syntaxe la plus récente de la documentation (React 19), pas l'ancienne API des données d'entraînement.

L’IA privilégiera alors @Docs.

Quand utiliser @Docs ?

Règle simple : si la bibliothèque ou le framework est postérieur à la date de coupure des données d’entraînement, ou si l’API a changé de façon majeure → @Docs.

Exemples :

• React 19 (fin 2024, mises à jour API majeures)
• Next.js 15 (fin 2024, Turbopack par défaut)
• Dernières fonctionnalités Supabase (doc mise à jour en continu)
• Conventions internes d’équipe (absentes des données d’entraînement)

Pour des stacks stables (React 18, Vue 3, Tailwind 3), les données d’entraînement suffisent souvent — @Docs est moins indispensable.

5. Bonnes pratiques de gestion du contexte

Bien choisir les @ n’est qu’une première étape. Ensuite : gérer le contexte. Piège fréquent : plus l’historique s’allonge, plus l’IA dévie, et le code généré s’éloigne de l’intention initiale.

Principe clé : conversations courtes, une fonctionnalité à la fois

Une fonctionnalité terminée → redémarrez la conversation. Ne mélangez pas « refactor API », « corriger un bug » et « nouvelle fonctionnalité » dans le même fil.

Pourquoi ? Chaque tâche exige un contexte différent. Refactor API : types, handlers, appels frontend. Correction de bug : logs, extraits, tests. Mélangés, le contexte se dilue et la compréhension de l’IA se brouille.

Action simple : « Clear Chat » en haut à droite du panneau Chat, ou raccourci pour une nouvelle conversation.

Petite modification vs tâche complexe

Petite modification (une ligne, un paramètre) : édition inline (Cmd+K). Sélectionnez le code, Cmd+K, saisissez l’instruction. Fichier courant et sélection servent de contexte automatiquement.

Tâche complexe (refactor de module, nouveau composant) : Chat + @-mentions. @Codebase pour la vue globale, @Files pour les fichiers clés, puis description claire de la tâche.

Optimisation de l’index : .cursorignore

L’index @Codebase couvre tout le dépôt, mais tout n’a pas besoin d’être visible par l’IA :

• node_modules/ (dépendances)
• dist/, build/ (artefacts compilés)
• .env, .env.local (config sensible)
• gros assets statiques (images, vidéos)

Excluez-les avec .cursorignore. Séparé de .gitignore : l’IA a-t-elle besoin de voir ce fichier ?

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

Index plus ciblé, requêtes plus rapides (de 5-10 s à 2-3 s), résultats plus pertinents.

Mettre à jour README.md régulièrement

Habitude souvent négligée : documenter l’état et la structure du projet dans README.md.

Pourquoi ? README.md est un fichier clé de l’index @Codebase. Pour comprendre l’architecture, l’IA s’y réfère en priorité. Si votre README précise :

• structure du projet (rôle des répertoires)
• modules centraux (quels fichiers font quoi)
• changements récents (nouvelles fonctionnalités, plans de refactor)

… l’IA comprend plus vite le global et répète moins les mêmes requêtes.

Avantage Cursor Pro : index plus large

Les utilisateurs Pro peuvent indexer sémantiquement tout le dépôt ; la version Free a des limites. Au-delà de 500 fichiers, @Codebase est nettement plus efficace en Pro.

Cela ne signifie pas que Free est inutilisable. L’essentiel reste : gérer le contexte, choisir le bon symbole, exclure le bruit. Pro est un plus, pas une condition sine qua non.

6. FAQ : problèmes courants et solutions

Problème 1 : @Codebase incohérent avec le dépôt

Symptôme : vous venez de modifier un fichier, @Codebase renvoie encore l’ancien contenu. Ou un fichier existant n’apparaît pas.

Cause : index non synchronisé.

Solution :

1. Cursor Settings → « Reindex Codebase »
2. Ou retirer puis réajouter le dossier du projet (plus radical)

Attendre 1 à 2 minutes après réindexation.

Problème 2 : mauvaise correspondance @Codebase

Symptôme : vous demandez « modifier UserService », l’IA renvoie utils/user.ts au lieu de services/UserService.ts.

Cause : ambiguïté sémantique.

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

Commencer →Pub

Solution :

1. @Files pour désigner le bon fichier
2. Ou chemin explicite dans le prompt : « modifier src/services/UserService.ts »

@Codebase découvre automatiquement, mais avec une marge d’erreur. Tâches précises → @Files.

Problème 3 : ancienne API malgré @Docs

Symptôme : @Docs React ajouté, code généré encore en style React 18.

Cause : empreinte forte des données d’entraînement.

Solution dans le prompt :

@Docs React
Utilise la syntaxe la plus récente de la documentation (React 19), pas l'ancienne API des données d'entraînement.

Problème 4 : @Codebase trop lent (5-10 secondes)

Symptôme : attente longue à chaque requête.

Cause : index trop large (node_modules, dist, etc.).

Solution : vérifiez .cursorignore :

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

Requêtes typiquement à 2-3 secondes après exclusion.

Problème 5 : historique trop long, IA qui dévie

Symptôme : après trois ou quatre sujets, les réponses s’éloignent de votre intention.

Cause : pollution du contexte.

Solution : Clear Chat, nouvelle conversation, une fonctionnalité par fil.

Problème 6 : consommation de tokens excessive

Symptôme : chaque conversation consomme beaucoup, quota Pro vite épuisé.

Cause : mauvais choix de symboles, trop de contenu hors sujet.

Solution :

1. Petites modifs : Cmd+K sans @-mentions
2. Tâches précises : @Files/@Code plutôt que @Codebase avec fichiers « pertinents mais hors sujet »
3. .cursorignore pour exclure les gros dossiers

Principe : référencer avec précision, éviter la recherche sur tout le dépôt.

Conclusion

Le système @ de Cursor se résume ainsi : incertain sur l’emplacement → @Codebase ; emplacement connu → @Files/@Code ; doc manquante → @Docs.

80 % du temps devrait utiliser @Codebase — pas par excès, mais parce que sa vraie valeur est la découverte : l’alias de type dans utils.ts, les mock dans un test, etc.

@Codebase n’est pas universel. Fichier de plus de 600 lignes ou emplacement connu → @Files. Petit extrait à déboguer → @Code. Nouvelle bibliothèque ou API récente → @Docs.

La gestion du contexte compte autant. Conversations courtes, tâches séparées. Clear Chat après chaque livrable. .cursorignore et README.md à jour : l’IA comprend mieux.

La prochaine fois, demandez-vous : est-ce que je connais l’emplacement du fichier, ou est-ce que j’ai besoin que l’IA trouve le code associé ? Si vous hésitez, commencez par @Codebase. Si vous savez, référencez avec précision.

Maîtrisé, Cursor devient un vrai partenaire de code — pas un moteur de recherche qui renvoie des piles de contenu.