Introduction aux Cursor Rules

Cursor Rules est un module de l'éditeur Cursor conçu pour permettre aux développeurs de définir des règles structurées et contextuelles. Ces règles aident l'IA à mieux appréhender l'architecture du projet, la pile technologique, les conventions et les pratiques de développement, afin de générer un code plus précis et maintenable.

Emplacement et Nomenclature des Fichiers de Règles

Cursor identifie automatiquement les fichiers de règles situés dans le chemin .cursor/rules/ :

Répertoire racine du projet/
└── .cursor/
    └── rules/
        └── *.mdc   ← Fichiers de règles (extension .mdc obligatoire)

• Le chemin est fixe : il doit être .cursor/rules/
• L'extension est fixe : elle doit être .mdc
• Plusieurs fichiers sont autorisés, chaque règle recommandée est dédiée à un thème spécifique, comme standards-codage.mdc, structure-projet.mdc, conventions-nommage.mdc, etc.

Rôle des Ficihers de Règles

• Spécifier la pile technologique du projet (ex. : Vue 3, TypeScript, Pinia, Vite)
• Définir les conventions du projet (nommage des composants/fichiers, nomenclature CSS, ordre des imports)
• Réduire les erreurs : minimiser les suggestions incorrectes de l'IA ou les réimplémentations inutiles
• Améliorer l'intelligence : aider l'IA à générer du code conforme au style, à la structure et aux conventions du projet

Création de Fichiers de Règles .mdc

Méthode Manuelle

1. Créer le répertoire des règles

mkdir -p .cursor/rules

2. Créer un fichier de règles

touch .cursor/rules/directives-projet.mdc

Remarque : le nom du fichier est personnalisable, mais l'extension doit être .mdc.

Génération Rapide via Cursor

Dans l'éditeur Cursor, ouvrez la fenêtre de Chat, tapez / et sélectionnez l'option Generate Cursor Rules pour générer automatiquement le répertoire .cursor/rules/ et un fichier de règles par défaut.

Structure et Contenu Recommandé des Fichiers de Règles

Les fichiers .mdc sont essentiellement des documents Markdown avec une structure spécifique. Voici un exemple de modèle adapté à un projet Vue 3 + TypeScript, inspiré d'une application générique :

Description Générale du Projet

• Ce projet est construit avec Vue 3, TypeScript et Vite.
• Il utilise l'API Composition () pour le développement.
• La gestion d'état est assurée par Pinia, organisée par modules.
• Le routage utilise Vue Router avec une configuration dynamique basée sur les permissions.
• Les requêtes API sont encapsulées dans @/utils/requete.ts

- Les composants de tableau et de formulaire sont basés sur une bibliothèque UI pour une réutilisabilité accrue.

# Conventions de Nommage pour Composants et Fichiers

- Les fichiers de composants utilisent le format ```
PascalCase
```, par exemple : ```
TableauUtilisateur.vue
```, ```
FormulaireConnexion.vue

• Les composants communs sont placés dans src/components/, les composants métier dans ``` src/views/monModule/components/

- Les dossiers et les fichiers non composants (```
.ts/.scss
```) utilisent le format ```
kebab-case
```, par exemple : ```
api-utilisateur.ts
```, ```
formulaire-connexion.scss

• Les fichiers de page correspondent aux routes en format kebab-case, par exemple : liste-utilisateurs.vue, ``` edition-role.vue

# Conventions pour les Styles et le CSS

- **Priorité aux classes atomiques :** Utilisez les classes atomiques de UnoCSS pour la mise en page et le style, comme les flexbox courants (```
flex justify-center items-center
```, etc.). Cela améliore la sémantique et la maintenabilité.
- **Extraction des combinaisons fréquentes :** Pour les combinaisons d'atomiques utilisées couramment, définissez des classes globales dans ```
unocss.config.ts
``` via ```
shortcuts
```. Par exemple : associer ```
flex justify-center items-center
``` en ```
flex-center
``` pour une réutilisation dans tout le projet. La nomination doit être concise et sémantique.
- **Combinaisons spécifiques en classes locales :** Pour les combinaisons peu courantes dans un composant spécifique (plus de 3 classes atomiques), utilisez des classes CSS locales dans un bloc ```
<style scoped=""></style>
``` pour éviter la pollution de l'espace de noms global.
- **Éviter le code dupliqué :** Que ce soit via des ```
shortcuts
``` globaux ou des classes locales, évitez de répéter les mêmes listes de classes atomiques à plusieurs endroits, en respectant le principe DRY (Don't Repeat Yourself).
- **Priorité des styles :** Privilégiez les solutions UnoCSS (classes atomiques ou combinées), puis le CSS traditionnel. Si nécessaire, suivez la convention BEM, format ```
block__element--modifier
```.

# Ordre Standard des Imports (Structure Unifiée)

1. API liées à Vue (ex. : ```
ref
```, ```
computed
```, ```
onMounted
```)
2. Bibliothèques tierces (ex. : ```
element-plus
```, ```
axios
```)
3. Fonctions utilitaires (ex. : ```
@/utils/*
```)
4. Gestion d'état (ex. : ```
@/store/*
```)
5. Composants et modules internes du projet (ex. : ```
@/components
```, ```
@/views
```)
6. Fichiers de style

# Notes de Développement

- Utilisez TypeScript, évitez l'usage de ```
any
``` ;
- Les composants doivent avoir une responsabilité unique et une structure claire ;
- Tous les composants doivent utiliser l'API Composition ;
- Ajoutez des commentaires appropriés pour améliorer la compréhension par l'IA.

Astuces et Recommandations

• Thématiser les règles : Créez des fichiers de règles pour différents modules, comme directives-styles.mdc, architecture-projet.mdc, conventions-composants.mdc, pour faciliter la consultation contextuelle par l'IA.
• Détaillez au maximum : Plus les règles sont explicites, plus Cursor pourra fournir du code conforme à vos attentes.
• Évitez les règles vagues : Concentrez-vous sur des règles exécutables, opérationnelles et vérifiables. Par exemple, préférez « les noms de classes suivent la convention BEM avec des lettres minuscules séparées par des tirets » plutôt que « les noms doivent être clairs ».
• Mettez à jour les règles avec le projet : Les règles doivent évoluer avec le code, surtout lors de l'introduction de nouvelles bibliothèques, outils ou changements de style.

Application Pratique et Exemple

Considérons un projet hypothétique où un fichier de règles .cursor/rules/ordre-imports.mdc est ajouté.

Étapes d'utilisation :

• Dans la vue « Chat » de l'éditeur Cursor, ouvrez un fichier, par exemple dashboard/index.vue.
• Saisissez l'instruction : « Ajustez l'ordre des imports selon les règles définies ».
• L'agent Cursor lit le fichier de règles ordre-imports.mdc et réorganise automatiquement les imports du fichier courant.

Cette fonctionnalité améliore significativement la cohérence du code et l'efficacité de maintenance, réduisant le besoin d'ajustements manuels.

Bonnes Pratiques Résumées