Accueil › Cursor › @Docs

Cursor @Docs : indexer et utiliser la documentation dans votre éditeur IA

La fonctionnalité @Docs de Cursor vous permet d’indexer n’importe quelle documentation web et de l’utiliser comme contexte dans vos conversations avec l’agent IA, directement depuis l’éditeur.

Quand l’IA de Cursor génère du code, la qualité du résultat dépend directement du contexte qu’elle reçoit. Un agent qui travaille avec la documentation officielle et à jour de votre framework produit un code conforme aux bonnes pratiques. Un agent qui s’appuie uniquement sur ses données d’entraînement peut générer du code obsolète ou des patterns dépréciés. C’est exactement le problème que résout @Docs.

Ce guide couvre l’ensemble du système de contexte de Cursor : l’indexation de documentation (@Docs), les autres symboles @ (@file, @codebase, @web, @git, etc.), l’indexation de la codebase, et les stratégies pour maximiser la pertinence des réponses de l’agent.

Pourquoi @Docs change la donne

Les LLM qui alimentent Cursor (Composer 2, Claude, GPT-5.4, Gemini) ont été entraînés sur des données avec une date de coupure. Quand vous utilisez un framework récent ou une version majeure sortie après cette date, l’IA risque de produire du code basé sur des API obsolètes.

@Docs résout ce problème en injectant la documentation officielle et à jour directement dans le contexte de la requête. L’agent ne devine plus : il lit la documentation que vous lui fournissez et génère du code conforme.

Exemple concret : vous développez avec Google Agent Development Kit (ADK), un framework trop récent pour figurer dans les données d’entraînement. Sans @Docs, l’agent inventerait des API inexistantes. Avec @Docs pointant vers la documentation ADK, il génère du code fonctionnel qui suit les patterns officiels.

Les bénéfices mesurables sont significatifs. Selon les retours de la communauté Cursor, l’utilisation des symboles @ (dont @Docs) fait passer la précision des réponses de l’IA d’environ 62 % à 91 % sur des tâches de codage contextuelles. L’explication est simple : plus le contexte est précis et pertinent, moins l’IA hallucine.

Documentation pré-indexée par Cursor

Cursor est livré avec un ensemble de documentations déjà crawlées, indexées et prêtes à l’emploi pour les frameworks et bibliothèques les plus populaires. Vous n’avez rien à configurer pour ces docs. Il suffit de taper @Docs dans le chat et de sélectionner le framework voulu.

Parmi les docs pré-indexées, on trouve typiquement : React, Next.js, Vue, Nuxt, Angular, Svelte, Tailwind CSS, Prisma, Supabase, Firebase, Express, Django, Flask, FastAPI, Ruby on Rails, Laravel, Spring Boot, MDN Web Docs, Node.js, Python, TypeScript, et bien d’autres. La liste évolue régulièrement.

Ajouter votre propre documentation

Si le framework ou l’outil que vous utilisez n’est pas dans la liste pré-indexée, vous pouvez ajouter votre propre documentation en quelques clics. Cursor crawlera le site, indexera les pages et rendra le contenu disponible via @Docs.

Méthode 1 : depuis le chat

C’est la méthode la plus rapide :

1. Ouvrez le chat Cursor (Cmd/Ctrl + L) ou le Composer (Cmd/Ctrl + I).
2. Tapez @Docs dans la zone de saisie.
3. Cliquez sur « Add new doc » en bas du menu déroulant.
4. Collez l’URL de la documentation (ex : https://docs.astro.build/).
5. Cursor affiche une modale vous demandant de nommer la doc. Donnez un nom clair (ex : « Astro »).
6. Confirmez. Cursor commence l’indexation.

L’indexation peut prendre de quelques secondes à plusieurs minutes selon la taille du site. Un indicateur visuel (point vert) confirme quand la doc est prête.

Méthode 2 : depuis les paramètres

Pour une gestion plus complète de vos documentations :

1. Ouvrez les paramètres Cursor (Cmd/Ctrl + ,).
2. Allez dans Indexing & Docs (ou Features > Docs selon la version).
3. Cliquez sur « + Add new doc ».
4. Entrez l’URL et le nom.
5. Depuis cette interface, vous pouvez aussi modifier, supprimer ou re-indexer vos docs existantes.

Profondeur d’indexation : ce qu’il faut savoir

L’indexation de Cursor ne crawle pas toujours l’intégralité d’un site de documentation. Plusieurs utilisateurs ont signalé que seules les pages de surface (10 à 16 pages) sont indexées quand le site en contient 50 ou plus. Cursor n’a pas documenté officiellement la profondeur de crawl, mais voici ce qui fonctionne :

Pointez vers la racine avec slash final. Utilisez https://docs.example.com/ et non une sous-page spécifique.

Essayez des sous-sections ciblées. Si la racine ne suffit pas, ajoutez plusieurs entrées ciblées : une pour /getting-started/, une pour /api/, une pour /guides/. Chaque entrée déclenche un crawl séparé.

Vérifiez le nombre de pages indexées. Cliquez sur l’icône livre à côté de la doc dans vos paramètres pour voir le nombre de pages effectivement indexées.

Re-indexez si nécessaire. Cursor re-indexe automatiquement et périodiquement, mais vous pouvez forcer une re-indexation depuis les paramètres. C’est recommandé après une mise à jour majeure du framework.

Documentation privée et interne

La fonctionnalité @Docs ne supporte que les URLs accessibles publiquement. Pour de la documentation interne (wiki Confluence, docs derrière un login, API privées), Cursor ne peut pas crawler directement. Les solutions de contournement :

Fichiers Markdown locaux. Extrayez les sections pertinentes de votre wiki interne, convertissez-les en fichiers .md et placez-les dans votre projet (ex : /docs/ ou /.cursor/docs/). L’agent pourra les lire via @file ou l’indexation de la codebase.

Fichiers Cursor Rules (.cursor/rules/). Pour les conventions de code, standards architecturaux et patterns spécifiques à votre équipe, le format MDC (Markdown-based) des fichiers Rules est plus adapté. L’agent les consulte automatiquement à chaque requête.

MCP (Model Context Protocol). Pour connecter Cursor à des sources de données dynamiques (base de données, API interne, outil de gestion de projet), utilisez des serveurs MCP. C’est la solution la plus puissante pour les données vivantes.

Partager des docs avec votre équipe

Sur les plans Teams et Enterprise, activez l’option « Share with team » pour rendre une doc indexée disponible à tous les membres de l’équipe. C’est un levier puissant pour standardiser le contexte : tout le monde travaille avec les mêmes références, les mêmes versions de documentation, et l’agent produit du code cohérent à travers l’équipe.

Depuis la mise à jour 2.6 de mars 2026, les administrateurs Teams et Enterprise peuvent aussi créer des marketplaces privés pour distribuer des plugins et configurations de documentation avec une gouvernance centralisée.

Tous les symboles @ de Cursor expliqués

@Docs n’est qu’un des nombreux symboles @ disponibles dans Cursor pour enrichir le contexte de l’agent. Maîtriser l’ensemble de ces symboles est le levier le plus efficace pour améliorer la qualité des réponses. Voici la référence complète.

@file vs @codebase : quand utiliser lequel ?

C’est la question la plus fréquente des nouveaux utilisateurs de Cursor. La règle est simple :

Utilisez @file quand vous savez exactement quels fichiers sont pertinents. C’est plus précis et consomme moins de tokens dans la fenêtre de contexte. Par exemple : « Refactorise la fonction processOrder dans @file:src/services/orders.ts pour utiliser le pattern dans @file:src/services/users.ts« .

Utilisez @codebase quand vous ne savez pas où chercher ou quand la question touche à l’architecture globale. Cursor effectue une recherche sémantique en trois étapes : collecte des fichiers pertinents, re-classement par pertinence, puis raisonnement pour planifier l’utilisation du contexte. Par exemple : « Pourquoi les données utilisateur ne se mettent pas à jour ? » laissera Cursor trouver les fichiers API, base de données et UI impliqués.

@web vs @Docs : quelle différence ?

@web effectue une recherche web en temps réel. C’est utile pour les informations très récentes (dernière version sortie, bug connu signalé cette semaine) ou quand vous avez besoin de scraper rapidement plusieurs sites.

@Docs accède à une documentation déjà indexée et structurée. Le résultat est plus fiable et plus cohérent qu’une recherche web, parce que Cursor a déjà crawlé, découpé et organisé le contenu. Pour la documentation de référence de vos frameworks, @Docs est toujours préférable à @web.

La bonne pratique : utilisez @Docs comme source principale pour les frameworks de votre stack, et @web pour les questions ponctuelles sur des sujets hors de votre documentation indexée.

L’indexation de la codebase : le fondement du contexte

Avant même de parler de @Docs, il faut comprendre l’indexation de la codebase. C’est le moteur qui alimente @codebase et l’assemblage automatique du contexte par Cursor.

Quand vous ouvrez un projet dans Cursor pour la première fois, l’éditeur scanne l’ensemble de votre code avec un modèle d’embedding dédié. Il crée un index sémantique qui permet à l’agent de comprendre les relations entre les fichiers, les dépendances, les patterns et l’architecture globale.

Comment ça fonctionne

L’indexation suit un processus en trois couches :

Couche 1 : Scan structurel. Cursor identifie les fichiers, les imports, les exports, les classes, les fonctions et les variables à travers tout le projet.

Couche 2 : Embedding sémantique. Chaque snippet de code est converti en vecteur sémantique. Quand vous posez une question, Cursor compare le vecteur de votre requête aux vecteurs du code pour trouver les sections les plus pertinentes.

Couche 3 : Assemblage contextuel. À chaque requête, Cursor assemble automatiquement un contexte composite incluant : le fichier actif, les fichiers récemment consultés, les résultats de la recherche sémantique, les erreurs de linter/compilateur actives, et l’historique d’édition récent. Tout cela sans que vous ayez à spécifier quoi que ce soit.

C’est ce pipeline qui explique pourquoi Cursor produit souvent de meilleurs résultats qu’un chatbot générique même sans utiliser de symboles @. Le contexte assemblé automatiquement est structuré et pertinent.

Configurer l’indexation

Par défaut, Cursor indexe tout votre projet. Pour les gros projets, vous voudrez exclure certains fichiers pour accélérer l’indexation et améliorer la pertinence des résultats.

Créez un fichier .cursorignore à la racine de votre projet (même niveau que package.json). La syntaxe est identique à .gitignore :

# Dépendances
node_modules/
vendor/
.venv/

# Build
dist/
build/
.next/

# Données volumineuses
data/
logs/
*.sqlite

Cursor respecte aussi votre .gitignore existant. Si vous avez déjà un .gitignore bien configuré, les fichiers ignorés par Git sont aussi ignorés par l’indexation Cursor par défaut. Le .cursorignore sert à ajouter des exclusions supplémentaires spécifiques à l’IA.

Stratégies avancées de gestion du contexte

Combiner les sources de contexte

Le vrai pouvoir de Cursor émerge quand vous combinez plusieurs sources de contexte dans une même requête. Voici les combinaisons les plus efficaces :

Pour implémenter une feature avec un framework récent :

@Docs:Astro + @file:src/layouts/BaseLayout.astro + instruction détaillée. L’agent voit la doc officielle ET votre code existant, et produit du code cohérent avec les deux.

Pour débugger un problème cross-layer :

@codebase + description du symptôme. L’agent scanne tout le projet et identifie les fichiers impliqués, y compris ceux auxquels vous n’auriez pas pensé.

Pour adopter les dernières API d’une bibliothèque :

@Docs:React + @web « React 19 migration guide » + @file:src/components/App.tsx. L’agent combine la doc indexée, les infos web les plus récentes, et votre code actuel.

Cursor Rules : le complément essentiel de @Docs

Tandis que @Docs fournit la documentation externe, les fichiers Cursor Rules (.cursor/rules/) codifient vos conventions internes. C’est le duo gagnant :

@Docs dit à l’agent comment fonctionne React ou Prisma. Cursor Rules dit à l’agent comment votre équipe utilise React ou Prisma, quels patterns sont préférés, quelles erreurs sont interdites, quelle structure de dossiers suivre.

Les fichiers Rules sont au format MDC (Markdown-based) et sont consultés automatiquement par l’agent à chaque requête. Vous n’avez pas besoin de les mentionner avec @. C’est transparent et systématique.

Exemple d’un fichier .cursor/rules/react-patterns.mdc :

---
description: Conventions React du projet
globs: ["src/components/**/*.tsx", "src/hooks/**/*.ts"]
---

# Conventions React

- Utiliser des composants fonctionnels uniquement (pas de classes)
- Hooks custom dans /src/hooks/ avec le préfixe "use"
- État global via Zustand (pas Redux)
- Styles via Tailwind CSS (pas de CSS modules)
- Tests avec Vitest + Testing Library
- Props typées via interface (pas type alias)

MCP pour les données dynamiques

@Docs est idéal pour la documentation statique. Pour les données qui changent en temps réel (état d’une base de données, tickets Jira, CI/CD, schéma API), les serveurs MCP sont la solution. Cursor supporte le Model Context Protocol comme mécanisme d’extensibilité principal.

Les cas d’usage MCP les plus courants : interroger une base de développement pour comprendre le schéma, vérifier le statut des PR GitHub, accéder à une API interne, lancer des tests automatisés via un navigateur. Pour les tâches purement code (refactoring, écriture de tests, correction de bugs), l’indexation de la codebase et @Docs suffisent.

Bonnes pratiques pour maximiser la qualité du contexte

La précision du prompt est le levier numéro un

Tous les symboles @ du monde ne compenseront pas un prompt vague. Les études de la communauté Cursor montrent que des prompts détaillés augmentent la précision de 50 % tout en réduisant la consommation totale de tokens de 30 %, parce qu’un bon prompt en un tour remplace 3 à 5 tours de corrections.

Structure recommandée pour un prompt efficace :

Tâche : ce que vous voulez accomplir, en termes spécifiques.
Contexte : les fichiers concernés via @file, la doc via @Docs.
Contraintes : technologies, patterns, limites.
Résultat attendu : format, structure, critères de succès.

Gardez les conversations courtes

Les conversations longues accumulent du contexte qui finit par polluer les requêtes suivantes. La bonne pratique : une conversation par feature ou par bug. Quand vous terminez une tâche, ouvrez un nouveau chat. Cela repart avec un contexte propre et évite les conflits entre les intentions de requêtes précédentes.

Documentez votre projet pour l’IA

Un README.md bien structuré n’est pas seulement utile pour les humains. Quand vous redémarrez une conversation, Cursor lit le README pour comprendre l’état et la structure du projet. Investir 30 minutes dans un README complet (stack technique, structure de dossiers, commandes principales, conventions) améliore durablement la qualité de toutes vos sessions Agent.

Utilisez le Debug Mode pour les erreurs

Quand vous rencontrez une erreur, ne copiez-collez pas manuellement le message d’erreur dans le chat. Utilisez le Debug Mode de Cursor (amélioré dans la version 2.6, mars 2026) qui capture automatiquement le message d’erreur, la stack trace, et le contexte des fichiers impliqués. L’IA reçoit un contexte structuré bien plus riche qu’un copier-coller brut.

Résolution de problèmes courants

Exemples concrets d’utilisation de @Docs

La théorie, c’est bien. Voyons comment @Docs s’utilise dans des scénarios réels de développement.

Scénario 1 : migration vers une nouvelle version de framework

Vous migrez un projet Next.js 14 vers Next.js 15. Les API de routing, le système de cache et les conventions de fichiers ont changé. Sans contexte à jour, l’agent produirait du code Next.js 14.

La solution : indexez la documentation Next.js 15 via @Docs (elle fait partie des docs pré-indexées, vérifiez que la version est à jour). Puis utilisez un prompt structuré :

@Docs:Next.js @file:src/app/layout.tsx @file:src/app/page.tsx

Migre ces fichiers vers les nouvelles conventions Next.js 15.
Utilise le nouveau système de cache et les Server Actions.
Garde la structure existante mais adapte les imports et patterns.

L’agent lit la documentation officielle, comprend les changements entre les versions, et applique les modifications à vos fichiers existants en respectant les nouvelles conventions.

Scénario 2 : travailler avec un framework de niche

Vous utilisez Effect-TS, une bibliothèque TypeScript pour la programmation fonctionnelle. Ce framework n’est pas dans les données d’entraînement classiques des LLM. Sans @Docs, l’agent inventerait des API ou confondrait avec d’autres bibliothèques.

Ajoutez la documentation Effect-TS : @Docs > Add new doc > https://effect.website/docs/ > nommez « Effect-TS ». Après indexation (quelques minutes pour un site de cette taille), vous pouvez demander :

@Docs:Effect-TS

Crée un service HTTP avec Effect qui gère les erreurs
de connexion et les timeouts via le système de layers.
Utilise les patterns recommandés dans la doc officielle.

L’agent génère du code Effect-TS idiomatique avec les bons imports, le bon système d’erreurs et les bons patterns, parce qu’il lit la documentation plutôt que de deviner.

Scénario 3 : documenter une API interne

Votre entreprise a une API REST interne dont la documentation est sur un wiki Confluence privé. @Docs ne peut pas y accéder. Voici la démarche :

1. Exportez les endpoints de l’API dans un fichier Markdown structuré : docs/internal-api.md.
2. Incluez les schémas de données, les codes d’erreur, les exemples de requêtes/réponses.
3. Créez un fichier Cursor Rules (.cursor/rules/api-conventions.mdc) avec les conventions d’appel, les headers requis, le format d’authentification.
4. Dans vos prompts, référencez @file:docs/internal-api.md pour que l’agent connaisse les endpoints.

Cette approche Markdown local + Rules est presque aussi efficace que @Docs pour la documentation interne, avec l’avantage supplémentaire de versionner la doc dans Git aux côtés du code.

@Docs vs les alternatives dans d’autres éditeurs

Comment se positionne @Docs face aux fonctionnalités similaires dans les éditeurs concurrents ?

Cursor a l’avantage d’offrir le système de documentation externe le plus complet : crawl automatique, catalogue pré-indexé, re-indexation périodique et partage d’équipe. Claude Code compense avec une approche différente : les fichiers CLAUDE.md dans le projet contiennent les instructions et le contexte, ce qui est plus adapté aux workflows terminal-first. GitHub Copilot mise sur l’intégration GitHub (issues, PR, wikis) plutôt que sur l’indexation de documentation externe.

Pour un développeur qui travaille avec plusieurs frameworks et bibliothèques, @Docs reste la solution la plus fluide : vous ajoutez une URL, Cursor s’occupe du reste, et la doc est disponible dans chaque conversation.