Les Cursor Rules permettent de guider l’agent IA de Cursor grâce à des instructions adaptées à chaque projet. Elles servent à définir des conventions de code, à cibler certains fichiers et à partager des règles avec une équipe. Voici comment les créer, les configurer et les utiliser efficacement.
Avec Cursor AI, les développeurs peuvent générer du code, modifier des fichiers et automatiser certaines tâches. Pourtant, l’agent ne respecte pas toujours les conventions techniques d’un projet. Il peut proposer une architecture différente ou ignorer des règles de nommage déjà établies. Les Cursor Rules permettent de limiter ces écarts sans répéter les mêmes consignes dans chaque prompt. Leur efficacité dépend toutefois du choix des instructions et de leurs conditions d’activation. Il faut donc comprendre les différents types de règles, leur fonctionnement et les bonnes pratiques pour les configurer correctement. ette approche complète les possibilités de Cursor, qui permet de coder avec l’intelligence artificielle.
Cursor Rules, de quoi s’agit-il exactement ?
Les Cursor Rules sont des instructions destinées à guider le comportement de l’agent IA intégré à Cursor. Elles précisent les conventions, les pratiques et les méthodes de travail attendues dans un environnement de développement. Concrètement, un développeur peut demander à Cursor de privilégier TypeScript, de respecter une architecture existante ou d’utiliser un outil de test particulier. Ces consignes sont conservées dans des règles réutilisables, plutôt que répétées dans chaque prompt.
Le fonctionnement repose sur le contexte transmis au modèle. Les grands modèles de langage ne conservent pas toujours une mémoire permanente entre leurs différentes requêtes. Cursor peut donc intégrer le contenu des règles applicables au début du contexte fourni à l’agent. Cette méthode aide l’IA à retrouver les mêmes instructions au fil des tâches. Elle ne garantit toutefois pas que toutes les directives seront respectées sans exception. Le code produit nécessite toujours une vérification.
Les règles peuvent aussi concerner des parties précises du projet. Par exemple, un fichier peut définir les conventions React du frontend. Un autre peut encadrer les services backend. Cette séparation permet de limiter les instructions aux tâches concernées. D’après la documentation officielle de Cursor, les Project Rules sont enregistrées dans le dépôt et peuvent être partagées avec Git.
Quels sont les différents types de règles ?
Cursor distingue plusieurs catégories d’instructions. Elles ne possèdent pas toutes la même portée ni les mêmes conditions d’utilisation. Les User Rules correspondent aux préférences générales du développeur. Elles s’appliquent à son environnement Cursor, indépendamment du projet ouvert. Elles conviennent aux consignes personnelles qui doivent accompagner les conversations avec l’agent.
Les Project Rules concernent un dépôt de code particulier. Elles sont stockées dans le dossier .cursor/rules/, généralement sous forme de fichiers .mdc. Elles permettent de documenter les choix techniques propres au projet et de les partager avec les collaborateurs. Les Team Rules s’adressent aux organisations utilisant les offres Teams ou Enterprise. Les administrateurs peuvent gérer ces instructions depuis le tableau de bord Cursor. Certaines règles peuvent être rendues obligatoires, tandis que d’autres restent désactivables par les membres de l’équipe.
Cursor reconnaît les fichiers AGENTS.md, qui constituent une alternative plus simple aux Project Rules. Ils utilisent directement le format Markdown, sans nécessiter les métadonnées d’activation propres aux fichiers .mdc. Il existe aussi un ancien format appelé .cursorrules. Ce fichier unique, placé à la racine du projet, appartient à une méthode historique de configuration. Cursor recommande de privilégier les Project Rules pour les nouvelles configurations. Le choix dépend donc du besoin : préférences personnelles, consignes propres au dépôt ou règles communes à une organisation.
Comment fonctionnent les règles dans Cursor ?
Toutes les règles ne sont pas prises en compte automatiquement. Cursor propose quatre modes d’application pour déterminer à quel moment les instructions rejoignent le contexte de l’agent. Le premier, Always Apply, applique la règle à chaque conversation avec l’agent. Cette option convient aux conventions générales du projet, comme l’interdiction de modifier les fichiers générés. En revanche, multiplier les règles permanentes augmente le volume d’instructions transmis au modèle.
Le deuxième mode, Apply to Specific Files, utilise des motifs appelés globs. Ils identifient les chemins ou extensions de fichiers concernés. Par exemple, src/**/*.tsx cible les fichiers TSX présents dans le répertoire src et ses sous-répertoires. La règle est attachée lorsque des fichiers correspondants sont présents dans le contexte. Le troisième, Apply Intelligently, laisse l’agent déterminer si une règle est pertinente. Il s’appuie alors sur sa description. Vous pourrez ensuite selectionner une consigne dédiée aux API pour une tâche correspondant à ce domaine.
Apply Manually nécessite une intervention explicite. Le développeur mentionne la règle avec @ dans sa conversation pour demander son application. Ces modes correspondent respectivement aux anciennes appellations Always, Auto Attached, Agent Requested et Manual.
Dans les fichiers .mdc, les champs alwaysApply, globs et description définissent ce comportement. Les valeurs utilisées doivent correspondre au mode souhaité. Une règle permanente n’a notamment pas besoin d’un motif globs pour fonctionner. La documentation de Cursor détaille ces combinaisons et leurs conditions d’activation.
Comment créer et configurer une Cursor Rule ?
Pour créer une Project Rule, ouvrez d’abord votre projet dans Cursor. La méthode la plus directe consiste à accéder à la rubrique Customize, puis à sélectionner Rules et Add Rule. Vous pouvez également saisir /create-rule dans la conversation avec l’agent. Celui-ci génère alors un fichier de configuration à partir de votre demande.
Les règles du projet sont enregistrées dans le répertoire .cursor/rules/, situé à sa racine. Chaque fichier possède l’extension .mdc. Le Project Rule ne reconnait pas toujours un simple fichier .md placé dans ce dossier.
Le format .mdc combine des métadonnées YAML et des instructions Markdown. Les métadonnées précisent les conditions d’activation. Le contenu décrit les conventions que l’agent doit suivre. Prenons un projet React utilisant TypeScript. Vous souhaitez que Cursor applique des consignes particulières aux composants situés dans le dossier src.
Créez le fichier .cursor/rules/react-patterns.mdc, puis ajoutez cette configuration :
—
globs: src/**/*.tsx
alwaysApply: false
—
– Utiliser des composants fonctionnels React.
– Privilégier les exports nommés.
– Définir les types des propriétés avec TypeScript.
– Respecter la structure des composants existants.
– Éviter les imports inutilisés.
Le champ globs indique les fichiers concernés. Avec src/**/*.tsx, la règle cible les fichiers TSX présents dans src et ses sous-répertoires. Le paramètre alwaysApply: false signifie qu’elle n’est pas imposée à toutes les conversations.
Pour utiliser ce comportement, choisissez le mode Apply to Specific Files. Cursor pourra alors joindre ces instructions au contexte si les fichiers sont concernés.
Si vous préférez laisser l’agent sélectionner la règle selon la tâche, ajoutez une description et utilisez Apply Intelligently, sans motif globs. Une fois le fichier enregistré, vous pouvez effectuer un essai. Demandez à l’agent de modifier un composant concerné et vérifiez que les conventions sont respectées. La rubrique Rules permet de consulter les règles et leur état. Si une règle ne s’applique pas, contrôlez son mode d’activation et son motif de fichiers. Enfin, ajoutez le fichier au dépôt Git pour le partager avec votre équipe. Ces procédures sont décrites dans la documentation d’aide officielle de Cursor.
Quels usages concrets pour les développeurs ?
Les Cursor Rules sont surtout utiles dans les projets qui possèdent déjà des conventions techniques. Elles permettent de transmettre ces contraintes à l’agent sans réécrire constamment les mêmes instructions. Cette méthode trouve notamment son intérêt pour créer une première application web avec Cursor, même sans expérience préalable en programmation.
Sur une application React, une règle react-patterns.mdc peut demander l’utilisation de composants fonctionnels et d’exports nommés. Si le projet utilise Tailwind CSS, elle peut également préciser les conventions de mise en forme. L’agent dispose ainsi d’indications cohérentes avec le code existant.
Les tests constituent un deuxième cas d’usage. Un fichier testing.mdc peut demander de privilégier Vitest, d’utiliser les utilitaires de test déjà présents et de couvrir certains comportements. Cela oriente la génération des tests, sans garantir leur exécution ni leur réussite. Ces vérifications restent nécessaires.
Les règles peuvent aussi encadrer le développement d’API. Dans un projet qui utilise Zod, elles peuvent demander la validation des données entrantes avec les schémas existants. Une autre instruction peut imposer un format commun pour les réponses d’erreur. Pour les équipes, l’intérêt réside surtout dans le partage des conventions. Les règles enregistrées dans Git accompagnent le code du projet. Lorsqu’une pratique change, les développeurs peuvent modifier le fichier correspondant.
Ces exemples illustrent des configurations possibles. Cursor ne choisit pas automatiquement React, Vitest ou Zod à votre place. Les règles servent à lui communiquer les outils et les méthodes réellement adoptés par votre projet.
Comment rédiger des règles vraiment efficaces ?
Une bonne Cursor Rule doit être précise, facile à comprendre et limitée à un objectif identifiable. Les formulations générales produisent souvent des résultats difficiles à vérifier. Par exemple, demander à l’agent de « produire un code de qualité » n’indique aucune action concrète. Une consigne comme « utiliser les schémas Zod existants pour valider les entrées des API » définit une attente beaucoup plus claire.
La documentation officielle recommande de conserver des règles courtes et ciblées, sous 500 lignes. Ce chiffre constitue une recommandation de bonnes pratiques, pas une garantie de performance. Pour les projets volumineux, mieux vaut répartir les instructions entre plusieurs fichiers.
Le ciblage joue aussi un rôle important. Une convention propre aux composants React ne devrait pas être transmise aux tâches concernant la base de données. Les modes d’activation permettent justement de limiter les règles à leur domaine d’application. Cursor conseille aussi de faire référence aux fichiers existants plutôt que de recopier toute leur documentation. Une mention comme @service-template.ts permet à l’agent de retrouver un modèle lorsqu’il en a besoin. Son contenu n’est pas automatiquement injecté dans le contexte.
Les règles doivent suivre les évolutions du projet. Après une modification d’architecture ou de framework, vérifiez les instructions concernées. Une règle obsolète risque d’orienter l’agent vers des pratiques abandonnées. Cette vigilance concerne aussi les environnements où Cursor Cloud Agents automatise des tâches de développement.
Cursor Rules et AGENTS.md, quelles différences ?
Cursor accepte deux approches pour documenter les consignes d’un projet : les fichiers .mdc et AGENTS.md. Elles poursuivent un objectif comparable, mais proposent des mécanismes de configuration différents.
Les Cursor Rules au format .mdc permettent de définir précisément les conditions d’application. Le développeur peut utiliser un motif globs, demander une activation manuelle ou laisser l’agent sélectionner une règle selon sa description. Le fichier AGENTS.md privilégie la simplicité. Il contient directement des instructions Markdown et ne nécessite pas de frontmatter YAML. Il convient surtout aux projets dont les consignes restent faciles à organiser.
Contrairement à certaines anciennes explications, AGENTS.md n’est pas limité à la racine du dépôt. Cursor prend aussi en charge les fichiers placés dans des sous-répertoires. Les instructions propres à un dossier s’appliquent aux fichiers situés dans cette partie du projet. Elles peuvent compléter les consignes définies à un niveau supérieur. Les deux formats peuvent donc couvrir différents répertoires. La distinction tient surtout aux mécanismes de sélection et aux métadonnées disponibles dans les fichiers .mdc.
Pour un projet simple, AGENTS.md peut suffire. Si vous souhaitez cibler des extensions particulières ou contrôler certaines instructions de façon manuelle, les Project Rules offrent davantage de possibilités. Les deux approches peuvent cohabiter dans un même dépôt. Dans tous les cas, leurs consignes doivent rester cohérentes pour éviter de transmettre des instructions contradictoires à l’agent.
- Partager l'article :
