Guide Complet .cursorrules : De Débutant à Expert

.cursorrules est un fichier texte simple que vous placez à la racine de votre projet pour indiquer à l'IA de Cursor comment se comporter -- quel style de codage adopter, quels frameworks vous utilisez, quels modèles éviter. Pensez-y comme à un prompt système spécifique au projet qui est injecté dans chaque interaction avec l'IA.

Si vous avez passé du temps sur le Forum Cursor, vous avez sûrement vu la même question revenir chaque semaine : "Comment configurer .cursorrules correctement ?" La documentation officielle couvre les bases, mais il y a beaucoup de subtilités qui ne se découvrent qu'en l'utilisant au quotidien. Ce guide synthétise ce que la communauté a appris jusqu'à présent.

Trois Types de Règles : Lequel Choisir ?

C'est la source de confusion numéro 1 sur le forum. Cursor propose en réalité trois mécanismes de règles différents, qui servent des objectifs distincts. Voici le détail :

Règles pour l'IA (Globales)

Accessible via Paramètres > Général > Règles pour l'IA. Ce sont des règles globales qui s'appliquent à tous les projets que vous ouvrez dans Cursor. Elles résident dans vos paramètres locaux, pas dans un répertoire de projet.

Idéal pour :

• Les préférences personnelles ("toujours utiliser le mode strict TypeScript")
• Les conventions universelles que vous suivez sur tous vos projets
• Les ajustements de comportement du modèle ("répondre de manière concise, pas d'explications sauf demande")

Règles pour l'IA (Globales)

Toujours utiliser des composants fonctionnels avec TypeScript.
Préférer les exports nommés aux exports par défaut.
Lors de la correction de bugs, expliquer brièvement la cause racine avant de montrer la solution.

.cursorrules (Niveau Projet)

Un fichier nommé .cursorrules placé à la racine de votre projet. C'est l'approche classique -- un seul fichier, en texte brut ou markdown, qui décrit comment l'IA doit travailler dans ce projet spécifique.

Idéal pour :

• La stack technique et les conventions spécifiques au projet
• Les règles partagées en équipe (à commiter dans git)
• Les modèles propres à un framework (Next.js, Django, Rails, etc.)

Règles .mdc (Moderne, Ciblée)

Le format plus récent. Vous placez les fichiers .mdc dans le répertoire .cursor/rules/. Chaque fichier peut être ciblé sur des motifs de fichiers spécifiques, et vous pouvez activer/désactiver individuellement chaque règle depuis l'interface.

Idéal pour :

• Un contrôle fin sur l'application des règles
• Les grands projets où différents répertoires ont des conventions différentes
• Les équipes qui souhaitent activer/désactiver sélectivement les règles

Structure de projet avec règles .mdc

.cursor/
  rules/
    react-components.mdc
    api-endpoints.mdc
    database.mdc
    testing.mdc

Tableau Comparatif

Fonctionnalité	Règles pour l'IA	.cursorrules	Règles .mdc
Portée	Globale (tous les projets)	Projet unique	Projet unique
Emplacement	Paramètres Cursor	Racine du projet	.cursor/rules/
Motif de fichiers	N/A	N/A	Ciblage par règle
Activation dans l'UI	Oui	Non	Oui
Partage via git	Non	Oui	Oui
Fichiers multiples	Non	Non (fichier unique)	Oui
Statut	Stable	Stable (legacy)	Recommandé

astuce

Vous pouvez utiliser les trois simultanément. Les Règles pour l'IA définissent votre base personnelle, les fichiers .cursorrules ou .mdc gèrent les spécificités du projet. En cas de conflit, les règles au niveau projet ont la priorité.

Rédiger un Fichier .cursorrules Efficace

La plupart des tutoriels vous conseillent d'écrire votre .cursorrules en markdown. Cela fonctionne, mais l'utilisateur du forum razbakov a plaidé en faveur du JSON structuré. Son raisonnement : les LLM analysent les données structurées de manière plus fiable que la prose, donc vos règles sont suivies plus constamment.

Voici un vrai fichier .cursorrules pour un projet Next.js + TypeScript utilisant l'approche JSON :

.cursorrules

{
  "project": {
    "name": "My SaaS App",
    "stack": ["Next.js 14", "TypeScript", "Tailwind CSS", "Prisma"],
    "packageManager": "pnpm"
  },
  "conventions": {
    "naming": {
      "components": "PascalCase",
      "functions": "camelCase",
      "files": "kebab-case",
      "constants": "SCREAMING_SNAKE_CASE"
    },
    "imports": {
      "order": ["react", "next", "lib/*", "components/*", "relative paths"],
      "noCircularImports": true,
      "alias": "@/ for src/"
    },
    "components": {
      "preferFunctional": true,
      "folderByFeature": true,
      "colocateStyles": true
    }
  },
  "rules": [
    "Always define TypeScript interfaces for component props",
    "Use 'use client' directive only when component needs interactivity or hooks",
    "Prefer server components by default in Next.js app router",
    "No default exports -- use named exports for everything",
    "API routes go in app/api/ following REST conventions",
    "Database queries use Prisma client from lib/db.ts only",
    "Error handling: use try/catch with proper error types, never swallow errors",
    "Environment variables must be validated with zod in env.ts"
  ],
  "antiPatterns": [
    "Never use 'any' type -- use 'unknown' and narrow with type guards",
    "Never put business logic in page.tsx files",
    "Never use inline styles -- use Tailwind classes or CSS modules",
    "Never import from relative paths like '../../' -- use @/ alias"
  ]
}

Pourquoi Cela Fonctionne Mieux Que le Texte Simple

Lorsque vous rédigez des règles sous forme de paragraphes en langage naturel, l'IA doit interpréter ce que vous voulez dire. Avec du JSON structuré :

• Chaque règle est une instruction discrète et non ambiguë
• L'IA n'a pas à deviner quelles parties sont des règles et quelles parties sont du contexte
• Vous pouvez organiser par catégorie, ce qui facilite la maintenance
• Ajouter ou supprimer des règles ne casse pas le format

Note : Si vous préférez le markdown, c'est aussi bien. L'idée clé est la structure plutôt que la prose. Même en markdown, utilisez des puces et des titres clairs plutôt que de longs paragraphes.

Une Alternative en Markdown

Si le JSON vous semble trop rigide, voici une version bien structurée en markdown qui évite toujours le problème du "mur de texte" :

.cursorrules (Version Markdown)

# Règles du Projet

## Stack Technique
- Next.js 14 (App Router)
- TypeScript (mode strict)
- Tailwind CSS
- Prisma ORM

## Conventions de Nommage
- Composants : PascalCase (UserProfile.tsx)
- Utilitaires : camelCase (formatDate.ts)
- Constantes : SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)
- Fichiers : kebab-case (user-profile.tsx)

## Règles Strictes
- Toujours utiliser des exports nommés
- Chaque composant doit avoir des types de props TypeScript
- Composants serveur par défaut, ajouter 'use client' uniquement si nécessaire
- Pas de type `any`, jamais
- Toutes les variables d'environnement validées avec zod

## Structure des Fichiers
- Composants dans src/components/[feature]/
- Hooks dans src/hooks/
- Utilitaires API dans src/lib/
- Types dans src/types/

Laisser l'IA Rédiger Votre .cursorrules

Voici une astuce de l'utilisateur du forum tomredman qui est vraiment utile : au lieu de rédiger les règles from scratch, utilisez le mode Agent de Cursor pour analyser votre codebase et les générer automatiquement.

La Méthode

1. Ouvrez le panneau de chat de Cursor
2. Passez en mode Agent
3. Donnez-lui ce prompt :

Analyse cette codebase et génère un fichier .cursorrules complet.
Examine :
- Les fichiers et la structure de répertoires existants
- Les dépendances du package.json
- Les fichiers de config (tsconfig, eslint, prettier, etc.)
- Les modèles et conventions de code existants

Produis un fichier .cursorrules qui capture les conventions réellement
utilisées dans ce projet. Utilise le format JSON avec des catégories claires
pour la stack technique, les conventions de nommage, les règles de codage et les anti-patterns.

4. Revoyez attentivement le résultat -- l'IA détectera des modèles que vous ne réalisiez même pas suivre
5. Éditez le fichier généré pour supprimer tout ce qui est inexact et ajouter ce qui manque
6. Enregistrez-le à la racine de votre projet sous .cursorrules

info

Cela fonctionne mieux sur des projets qui existent depuis un certain temps avec des modèles cohérents. Pour les projets tout neufs, il vaut mieux rédiger les règles manuellement ou partir d'un modèle.

Itérer sur les Règles Générées

N'attendez pas un résultat parfait du premier coup. Voici mon workflow :

1. Générer avec le mode Agent
2. Tester en demandant à Cursor d'écrire un nouveau composant -- est-ce qu'il suit les règles ?
3. Noter les écarts et ajouter des règles explicites pour ces cas
4. Répéter sur quelques itérations jusqu'à ce que le résultat soit constamment correct

Tout le processus prend environ 15-20 minutes et fait gagner des heures de va-et-vient "corrige ça, non pas comme ça" par la suite.

Ressources Communautaires

Vous n'êtes pas obligé de partir de zéro. La communauté a créé plusieurs bibliothèques de règles qui valent le détour :

cursor.directory

cursor.directory est une collection curée de fichiers .cursorrules organisés par framework et langage. C'est la ressource la plus populaire sur le forum pour trouver des règles de démarrage.

cursorrules.agnt.one

cursorrules.agnt.one se concentre sur les règles spécifiques à l'agent. Si vous utilisez beaucoup le mode Agent, cela vaut la peine d'y jeter un œil.

Collections GitHub

Recherchez .cursorrules sur GitHub et vous trouverez des milliers d'exemples du monde réel :

Requête de recherche GitHub

filename:.cursorrules stars:>5

Filtrez par langage ou framework pour trouver des règles de projets similaires au vôtre.

Discussion Forum : Partagez Votre .cursorrules

Il y a une discussion épinglée sur le Forum Cursor intitulée "Share your .cursorrules" où les utilisateurs partagent leurs configurations avec des explications. C'est une mine d'or pour voir ce qui fonctionne en production.

attention

Ne copiez jamais un fichier .cursorrules tel quel dans votre projet. Adaptez-le toujours à votre stack et vos conventions réelles. Un fichier de règles React Native fera plus de mal que de bien dans un projet Django.

Pièges Courants

Après avoir lu des dizaines de discussions sur le forum, voici les problèmes qui reviennent le plus souvent :

1. Des Règles Trop Longues = Moins de Performance

Il existe un mythe persistant selon lequel plus de règles = un meilleur comportement de l'IA. C'est l'inverse. Cursor injecte vos règles dans la fenêtre de contexte aux côtés de votre code et de la conversation. Des règles plus longues signifient moins de place pour le contexte de code réel.

Gardez-le sous 2000 caractères si possible. Si vous dépassez 5000+, vous devez couper sans pitié.

Mauvais : Trop verbeux

When you are writing React components in this project, you should always make sure
to use functional components instead of class components, and you should define
your prop types using TypeScript interfaces rather than PropTypes, and you should...

Bon : Concis et direct

- Use functional React components only
- TypeScript interfaces for all props
- Named exports, no defaults

2. Règles en Conflit

Lorsque vous avez des Règles pour l'IA définies globalement ET un fichier .cursorrules dans votre projet, les conflits sont inévitables. Par exemple :

• Règle globale : "Utiliser une indentation de 2 espaces"
• Règle projet : "Utiliser une indentation de 4 espaces"

Cursor résout cela en donnant la priorité aux règles au niveau projet, mais l'IA peut toujours être confuse lorsque les deux sont présentes. La solution : gardez les règles globales minimales et génériques, placez les spécificités dans les fichiers projet.

3. Des Règles Qui Disent à l'IA Ce Qu'Elle Sait Déjà

Ne gaspillez pas votre budget de règles sur des choses que le modèle fait déjà bien :

Règles inutiles à éviter

- Write clean, readable code          # Le modèle fait déjà ça par défaut
- Follow best practices               # Trop vague pour être utile
- Use proper error handling          # Déjà le comportement par défaut
- Comment your code                  # Souvent du bruit inutile

Concentrez-vous plutôt sur ce qui rend votre projet différent des paramètres par défaut du modèle :

Règles qui apportent réellement de la valeur

- Use Zod schemas for all API input validation
- All database queries go through the repository pattern
- GraphQL resolvers must have @authenticated directive
- Use pnpm workspaces for monorepo package management

4. Oublier de Committer .cursorrules

Si vous êtes en équipe et que le fichier .cursorrules n'est pas sous contrôle de version, vous êtes le seul à en bénéficier. Ajoutez-le à git et faites-en partie de votre processus d'intégration.

Ajouter .cursorrules à git

git add .cursorrules
git commit -m "Add project AI rules for Cursor"

Note : Certaines équipes préfèrent garder .cursorrules hors de git si différents développeurs ont des préférences différentes. Dans ce cas, utilisez .cursorrules.example comme modèle et ajoutez .cursorrules à .gitignore.

5. Ne Pas Tester Vos Règles

Rédigez vos règles, puis testez-les immédiatement. Demandez à Cursor de :

• Générer un nouveau composant
• Refactoriser une fonction existante
• Corriger un bug

Si le résultat ne correspond pas à vos attentes, vos règles nécessitent un ajustement. N'attendez pas d'être au cœur d'une fonctionnalité pour découvrir que vos règles ne fonctionnent pas.

Checklist de Démarrage Rapide

Si vous configurez .cursorrules pour la première fois, voici le chemin minimal :

• Choisir entre .cursorrules (fichier unique) ou .mdc (fichiers multiples)
• Utiliser le mode Agent pour analyser votre codebase et générer un premier jet
• Réduire à moins de 2000 caractères
• Se concentrer sur les règles spécifiques au projet, pas les conseils génériques
• Tester en demandant à Cursor de générer un composant ou une fonction
• Itérer jusqu'à ce que le résultat soit cohérent
• Commiter dans le contrôle de version
• Partager avec votre équipe

Articles Connexes

• Bonnes Pratiques pour .cursor/rules
• Bonnes Pratiques pour les Règles MDC
• Utiliser les Règles Cursor Efficacement
• Comment Ignorer les Fichiers Sensibles dans Cursor