Règles Cursor : comment aligner l’IA sur votre base de code

Vous ouvrez une nouvelle discussion dans Cursor et collez le même bloc d’instructions que vous avez déjà utilisé des centaines de fois. Votre stack, vos conventions de nommage et l’arborescence de dossiers que l’IA se trompe sans cesse. Puis elle génère une classe de 40 lignes avec trois couches d’abstraction là où une simple fonction suffisait.

Il est temps de sortir de ce cauchemar. Les règles Cursor sont des fichiers projet qui rendent ces copier-coller inutiles. Écrivez vos conventions une fois, et la sortie de l’IA s’aligne sur votre codebase au lieu de s’y opposer.

Ce tutoriel construit un ensemble de fichiers de règles .mdc pour un projet web Python utilisant FastAPI et pytest, en couvrant le contexte du projet, la simplicité du code et le formatage des erreurs d’API. Si vous découvrez Cursor, nous vous recommandons de suivre d’abord notre cours Software Development with Cursor, puis d’ouvrir un projet et de suivre pas à pas.

Qu’est-ce que les règles Cursor ?

Les règles Cursor sont des fichiers Markdown avec un front matter spécifique MDC, situés dans votre projet à .cursor/rules/. Avant que votre invite n’atteigne le modèle, Cursor vérifie quelles règles correspondent et préfixe leur contenu dans la fenêtre de contexte. Vos instructions arrivent en premier, à chaque fois.

Chaque fichier .mdc comporte trois champs de front matter qui contrôlent son activation : description, globs et alwaysApply. Une règle peut se déclencher dans toutes les conversations ou seulement quand certains fichiers sont ouverts. Une troisième option, Appliquer intelligemment, permet à l’agent de lire la description et de décider lui-même si la règle est pertinente. La section suivante couvre chaque type, en pratique.

Cursor prend en charge quatre catégories de règles :

Les règles de projet ont remplacé l’ancien fichier .cursorrules, un unique fichier à la racine sans périmètre ni métadonnées, en scindant les règles en plusieurs fichiers .mdc avec front matter.

AGENTS.md est l’alternative plus simple pour les projets qui n’ont pas besoin de périmètres via globs. C’est du Markdown pur, reconnu par d’autres outils de codage IA que Cursor ; et des fichiers plus profonds dans les sous-dossiers remplacent ceux des dossiers parents.

Pour en savoir plus sur la manière dont les workflows pilotés par des agents s’intègrent à votre processus de développement, consultez notre parcours de compétences AI Agent Fundamentals.

Créer et configurer des règles de projet Cursor

La suite de ce tutoriel crée des fichiers de règles pour un projet FastAPI avec pytest. Les schémas s’adaptent à n’importe quelle stack.

Mettre en place le dossier et les fichiers de règles

Créez un dossier .cursor/rules/ à la racine de votre projet. Chaque fichier .mdc que vous y placez devient une règle immédiatement prise en compte par Cursor, sans redémarrage.

Le premier fichier de règle, project-context.mdc, donne à l’IA une connaissance persistante de votre stack et de la structure des dossiers :

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Saisir /create-rule dans une discussion avec un Agent est une autre porte d’entrée : Cursor en génère une ébauche via un panneau de chat.

Le front matter alwaysApply: true signifie que cette règle est chargée dans chaque conversation. Nommez les fichiers en kebab-case par thème (project-context.mdc, simplicity.mdc, error-responses.mdc) et gardez chacun sous 500 lignes. Un fichier de règle trop volumineux consomme l’espace de fenêtre de contexte dont vous avez besoin pour votre vrai code et vos invites. Validez le dossier .cursor/rules/ dans git.

Configurer les métadonnées de règle pour une correspondance fiable

La règle project-context.mdc ci-dessus utilise alwaysApply: true, le mode le plus simple : chaque conversation la charge, quels que soient les fichiers sur lesquels vous travaillez. C’est le bon choix pour un contexte à l’échelle du projet.

Certaines règles ne s’appliquent qu’à des parties spécifiques du code. Définissez alwaysApply: false et ajoutez des motifs glob, séparés par des virgules, pour les borner. Une règle avec globs: app/routers/**/*.py se déclenche uniquement lorsque des fichiers correspondants (ici : fichiers Python dans app/routers/ ou ses sous-dossiers) sont présents dans le contexte, évitant d’appliquer des conventions d’API à des discussions sans rapport.

Appliquer intelligemment ignore totalement les motifs de fichiers. Vous laissez globs vide et vous écrivez une description détaillée ; l’agent décide alors si la règle est pertinente pour la conversation en cours. La qualité de la description compte : "Error handling rules" est trop vague pour un appariement fiable, tandis que "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" fournit des signaux clairs.

Les règles sans globs, sans description utile et avec alwaysApply: false deviennent manuelles uniquement, chargées lorsque vous tapez @rule-name dans le chat. Pratique pour du matériel de référence à invoquer à la demande.

Rédiger le contenu et les contraintes des règles

Des règles rédigées au conditionnel (« essayez de garder les fonctions courtes », « privilégiez les endpoints async ») donnent à l’IA la permission de les ignorer. Écrivez des consignes impératives : « Les fonctions doivent faire moins de 30 lignes. Tous les endpoints doivent être async. »

L’introduction évoquait l’IA générant une classe de 40 lignes avec trois couches d’abstraction. La règle qui empêche ce comportement est simplicity.mdc :

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

La différence est immédiate. L’IA cesse de proposer des classes abstraites lorsqu’il n’existe qu’une seule implémentation, et utilise des if lorsque deux cas suffisent.

La troisième règle, error-responses.mdc, est limitée par des globs pour ne se déclencher que lorsque vous travaillez sur des fichiers de routes d’API :

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Dans la mesure du possible, référencez des fichiers existants de votre code au lieu de copier du code dans les règles. Une ligne comme « Voir app/routers/users.py pour la structure d’endpoint de référence » reste exacte à mesure que le code évolue, alors qu’un extrait copié devient obsolète dès que l’original est refactoré.

Tester et vérifier l’attachement des règles

Cursor n’a pas d’indicateur natif montrant quelles règles sont actives dans une conversation. Vous vérifiez en testant le comportement.

Ouvrez une nouvelle discussion avec un Agent et écrivez une invite censée déclencher l’une de vos règles. Pour error-responses.mdc, essayez : « Ajoutez un endpoint DELETE pour supprimer un utilisateur par ID dans app/routers/users.py. » Si la gestion d’erreurs générée ne ressemble en rien à la structure JSON de votre règle ou évite HTTPException avec le dictionnaire detail, quelque chose cloche dans l’appariement.

Les règles restreintes par globs nécessitent un fichier correspondant mentionné dans votre invite ou ouvert dans l’éditeur. Tester error-responses.mdc sans mentionner de fichier sous app/routers/ signifie que la règle ne s’activera jamais. 

Les règles « Appliquer intelligemment » sont basées sur le sujet : essayez d’abord une invite liée à la description de la règle, puis une qui ne l’est pas, et comparez les sorties. L’agent doit suivre la règle dans le premier cas et l’ignorer dans le second.

Garder vos règles Cursor efficaces

Des règles efficaces le mois dernier peuvent induire l’IA en erreur après un refactoring ou un renommage de dossier.

Dépanner les échecs d’appariement

La raison la plus fréquente d’une règle qui ne se déclenche pas est l’extension de fichier : les règles doivent utiliser .mdc, et les simples fichiers .md dans .cursor/rules/ sont ignorés silencieusement.

Au-delà de ça :

• Des globs trop larges comme **/*.py attachent la règle à chaque fichier Python du projet. Restreignez à app/routers/**/*.py ou tests/**/*.py pour ne déclencher la règle que là où elle est pertinente.

• Vous remarquerez que les règles « Appliquer intelligemment » passent à côté de conversations quand la description est trop générique. Les bons/mauvais exemples de la section métadonnées s’appliquent ici aussi.

• Les conflits entre règles sont plus subtils. Lorsque deux règles se contredisent pour les mêmes fichiers, l’IA en choisit une (souvent celle chargée en dernier). Corrigez en resserrant la portée des globs pour éviter les chevauchements, ou fusionnez les consignes liées dans un seul fichier.

Une bizarrerie à connaître : des modifications de fichiers .mdc disparaissent parfois sans être enregistrées. Si vos éditions ne persistent pas, fermez complètement Cursor, choisissez « Override » dans la fenêtre des modifications non enregistrées, puis rouvrez.

Faire respecter les règles au milieu d’une conversation

Une règle peut se déclencher correctement au début d’une conversation puis être ignorée cinq messages plus tard. La cause est le biais de récence de la fenêtre de contexte : à mesure que la conversation s’allonge, le modèle privilégie les messages récents par rapport aux instructions injectées au début. C’est la plainte la plus courante dans la communauté Cursor, et il n’existe pas de réglage magique pour y remédier.

Le contournement, c’est le renforcement. Lorsque la sortie commence à s’éloigner de vos règles, ajoutez une ligne comme « suivez les règles du projet pour les réponses d’erreur » à votre prochaine invite. Cela remet l’instruction dans le contexte récent du modèle. 

Pour les règles qui comptent à chaque réponse (formatage, nommage), une formulation courte et directe résiste mieux aux longues conversations que des paragraphes détaillés.

Les règles avec des exemples de code résistent aussi mieux à la dérive que les consignes purement textuelles. Plutôt que d’écrire « utilisez des retours anticipés pour la gestion d’erreurs », incluez un petit avant/après montrant le schéma souhaité. Le modèle s’ancre plus solidement sur du code réel que sur de la prose, surtout lorsque le contexte s’accumule.

Maintenir et élaguer les règles

Revoyez les règles après tout refactoring majeur, mise à jour de dépendances ou réorganisation de dossiers. Une règle qui fait référence à des API obsolètes ou à des fichiers supprimés enverra de mauvaises consignes à l’IA. Les globs périmés échouent encore plus discrètement : renommez app/api/ en app/routers/ et une règle bornée à l’ancien chemin cesse simplement de se déclencher, sans avertissement.

L’élagage va aussi dans l’autre sens. À mesure que les modèles progressent, ils intègrent d’eux-mêmes les conventions courantes. Si l’IA suit déjà une consigne sans la règle, supprimez-la et récupérez des tokens de contexte. Un ensemble de règles sain a tendance à rétrécir avec le temps, pas seulement à grossir.

Passer à l’échelle en environnement d’équipe

Traitez les règles comme du code applicatif. Les changements passent par des pull requests, et l’équipe s’accorde sur un schéma avant intégration dans .cursor/rules/.

Pour les organisations en offres Business ou Enterprise, Team Rules permet aux administrateurs d’imposer des règles à tous les membres depuis le tableau de bord Cursor. « Enable immediately » rend une règle active par défaut tout en laissant la possibilité de la désactiver. « Enforce this rule » supprime l’option de refus, utile pour les conventions non négociables comme la sécurité et la conformité.

Conclusion

Commencez par une ou deux règles visant les schémas que vous corrigez le plus souvent. Si vous modifiez sans cesse le même type de sortie de l’IA à chaque session (mauvais format d’erreur, abstractions inutiles), c’est une règle qui n’attend que d’être écrite. Ajoutez-en d’autres au fil des erreurs récurrentes, et retirez celles qui ne sont plus utiles.

Les fichiers .mdc de ce tutoriel conviennent à un projet FastAPI. Les vôtres seront différents pour un frontend Next.js ou un outil CLI en Rust ; et c’est tout l’intérêt : ils encodent les conventions de votre équipe, pas des bonnes pratiques génériques. 

Pour aller plus loin avec Cursor, consultez notre guide Cursor 2.0. Pour une comparaison avec d’autres assistants de codage IA, nous vous recommandons ces analyses comparatives :

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf