Bonnes pratiques et dépannage des règles MDC dans Cursor

Cursor MDC Rules

Les règles MDC (Markdown Configuration) sont le moyen puissant de Cursor pour imposer des normes de codage, des conventions de projet et des directives de comportement de l'IA. Lorsqu'elles sont correctement configurées, elles améliorent considérablement la qualité et la cohérence du code. Ce guide couvre les bonnes pratiques pour créer, organiser et dépanner les règles MDC.

Que sont les règles MDC ?

Les règles MDC sont des fichiers Markdown avec un front matter YAML qui indiquent à Cursor comment se comporter lorsqu'il travaille avec des fichiers spécifiques ou dans des contextes spécifiques. Elles peuvent :

Imposer des normes de codage
Définir des modèles d'architecture de projet
Spécifier des exigences de documentation
Contrôler le comportement de l'IA pour des types de fichiers spécifiques

Exigences de format de fichier

Les règles MDC doivent suivre ce format exact :

---
description: 'Description de la règle ici'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---

# Titre de la règle

Contenu de votre règle ici...

## Directives spécifiques

- Directive 1
- Directive 2

Exigences critiques

Exigence	Détails
Extension	Doit être `.mdc` (pas `.md`)
Front matter	Doit utiliser le format YAML entre les délimiteurs `---`
Emplacement	Doit être dans le répertoire `.cursor/rules/`
globs	Tableau de motifs de fichiers auxquels cette règle s'applique
alwaysApply	Booléen - s'applique sans correspondance de fichier

Convention de nommage

Utilisez un système de préfixe numéroté pour l'organisation :

.cursor/rules/
  001-core-coding-standards.mdc
  002-typescript-conventions.mdc
  003-react-patterns.mdc
  100-api-design.mdc
  101-database-models.mdc
  200-testing-requirements.mdc
  201-documentation-rules.mdc

Système de numérotation

Plage	Catégorie	Exemple
`001-099`	Règles de base (s'appliquent à tous les fichiers)	Normes de codage, formatage
`100-199`	Règles d'intégration (domaines spécifiques)	API, base de données, authentification
`200-299`	Règles de modèle/rôle	Tests, documentation
`300-399`	Spécifiques à une technologie	React, Vue, Angular

Rédiger des règles efficaces

Soyez spécifique et actionnable

Mauvais :

Écrivez du bon code.

Bon :

## Gestion des erreurs

Toutes les fonctions asynchrones doivent utiliser des blocs try/catch :

```typescript
async function fetchUser(id: string): Promise<User> {
  try {
    const response = await api.get(`/users/${id}`);
    return response.data;
  } catch (error) {
    logger.error(`Failed to fetch user ${id}`, error);
    throw new UserNotFoundError(id);
  }
}

### Inclure des exemples

Montrez toujours des exemples corrects et incorrects :

```markdown
## Gestion d'état

✅ FAIRE : Utiliser React Query pour l'état serveur
```typescript
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

❌ NE PAS FAIRE : Utiliser useEffect pour la récupération de données

// Éviter ce modèle
useEffect(() => {
  fetchUser(userId).then(setUser);
}, [userId]);

### Utiliser efficacement les motifs glob

```yaml
# S'appliquer à tous les fichiers TypeScript
globs: ['**/*.ts', '**/*.tsx']

# S'appliquer uniquement au code backend
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']

# S'appliquer aux fichiers de test spécifiques
globs: ['**/*.test.ts', '**/*.spec.ts']

# Exclure certains fichiers
globs: ['src/**/*.ts', '!src/generated/**']

Catégories de règles courantes

1. Règles de style de code

---
description: 'Imposer un style de code cohérent'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---

# Normes de style de code

## Imports
- Grouper les imports : React, libs externes, modules internes, types
- Utiliser des imports absolus pour les modules src/
- Trier par ordre alphabétique au sein des groupes

## Nommage
- Composants : PascalCase (UserProfile)
- Hooks : camelCase commençant par 'use' (useAuth)
- Constantes : UPPER_SNAKE_CASE
- Fichiers : kebab-case (user-profile.tsx)

2. Règles d'architecture

---
description: 'Imposer des modèles d'architecture propre'
globs: ['src/**/*.ts']
alwaysApply: false
---

# Directives d'architecture

## Dépendances de couche
- Couche domaine : Aucune dépendance externe
- Couche application : Dépend uniquement du domaine
- Couche infrastructure : Dépend de l'application

## Organisation des fichiers

src/ domain/ # Logique métier, entités application/ # Cas d'utilisation, DTOs infrastructure/ # DB, API, services externes presentation/ # Composants UI

3. Règles de test

---
description: 'Exigences et modèles de test'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---

# Normes de test

## Tests requis
- Tests unitaires pour toutes les fonctions utilitaires
- Tests de composants pour tous les composants React
- Tests d'intégration pour les points de terminaison API
- Tests E2E pour les flux utilisateurs critiques

## Structure des tests
Suivre le modèle AAA :
1. Arrange : Configurer les données de test et les mocks
2. Act : Exécuter la fonction testée
3. Assert : Vérifier les résultats

Dépannage des problèmes courants

Problème 1 : Les modifications ne sont pas enregistrées

Symptôme : Vous modifiez un fichier .mdc, l'enregistrez, mais Cursor n'applique pas les modifications.

Solution :

Fermez complètement Cursor (pas seulement la fenêtre - quittez l'application)
Rouvrez Cursor
Les modifications devraient maintenant être appliquées

Pourquoi cela se produit : Les règles MDC sont mises en cache au démarrage de Cursor. Elles ne se rechargent pas à chaud.

Problème 2 : Les règles ne sont pas appliquées

Symptôme : Cursor ignore vos règles lors de l'édition de fichiers.

Liste de vérification :

L'extension du fichier est .mdc (pas .md)
Le fichier est dans le répertoire .cursor/rules/
Le front matter a une syntaxe YAML valide
Le motif globs correspond à vos fichiers cibles
Pas d'erreurs de syntaxe dans le contenu Markdown

Commande de débogage :

# Vérifier si Cursor reconnaît vos règles
ls -la .cursor/rules/
# Vérifier les extensions de fichier
file .cursor/rules/*

Problème 3 : Règles en conflit

Symptôme : Plusieurs règles donnent des instructions contradictoires.

Ordre de résolution :

Les règles avec des motifs glob plus spécifiques ont la priorité
Les règles avec alwaysApply: true sont évaluées en premier
Les règles ultérieures dans l'ordre alphabétique remplacent les précédentes

Bonne pratique : Utilisez le champ priority (si supporté) :

---
description: 'Règle de haute priorité'
globs: ['src/**/*.ts']
priority: 100
---

Problème 4 : Règles trop longues

Symptôme : Cursor ne suit pas toutes les instructions d'une règle longue.

Solution : Divisez en plusieurs règles ciblées :

.cursor/rules/
  001-general-style.mdc       # Directives courtes et générales
  002-error-handling.mdc      # Spécifique à la gestion des erreurs
  003-performance.mdc         # Optimisations de performance

Techniques avancées

Règles conditionnelles

Utilisez les globs pour appliquer différentes règles à différentes parties de votre code :

# Règles frontend
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
Utiliser le modèle React hooks. Préférer les composants fonctionnels.

# Règles backend
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
Utiliser l'injection de dépendances. Suivre les principes SOLID.

Héritage des règles

Créez une règle de base et étendez-la :

---
description: 'Normes TypeScript de base'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---

# Règles TypeScript de base

- Utiliser une configuration TypeScript stricte
- Pas de types `any` sans commentaire justificatif
- Préférer `interface` à `type` pour les formes d'objets

---
description: 'Extensions spécifiques à React'
globs: ['src/**/*.tsx']
alwaysApply: false
---

# Règles React

En plus des règles TypeScript de base :
- Utiliser des composants fonctionnels avec hooks
- Les interfaces de props doivent être exportées
- Utiliser React.FC avec parcimonie (préférer le typage explicite des props)

Règles dynamiques avec variables

Certaines configurations avancées supportent les variables de modèle :

---
description: 'Conventions spécifiques au projet'
globs: ['**/*.ts']
---

# Conventions du projet

## URL de base de l'API
Utiliser : {{API_BASE_URL}}

## Authentification
En-tête de token : {{AUTH_HEADER_NAME}}

Référence rapide : Modèle de règle MDC

---
description: ''
globs: ['']
alwaysApply: false
---

# Titre

## Section 1
- Directive 1
- Directive 2

## Section 2
```typescript
// Exemple de code

Références

Lien vers la doc

## Ressources connexes

- [Utiliser efficacement les règles Cursor](using-cursor-rules-effectively.mdx)
- [Bonnes pratiques pour les règles Cursor](best-practices-for-cursor-rules.mdx)
- [Guide de configuration CursorRules](cursorrules-setup-guide.mdx)

Que sont les règles MDC ?​

Exigences de format de fichier​

Exigences critiques​

Convention de nommage​

Système de numérotation​

Rédiger des règles efficaces​

Soyez spécifique et actionnable​

Catégories de règles courantes​

1. Règles de style de code​

2. Règles d'architecture​

3. Règles de test​

Dépannage des problèmes courants​

Problème 1 : Les modifications ne sont pas enregistrées​

Problème 2 : Les règles ne sont pas appliquées​

Problème 3 : Règles en conflit​

Problème 4 : Règles trop longues​

Techniques avancées​

Règles conditionnelles​

Héritage des règles​

Règles dynamiques avec variables​

Référence rapide : Modèle de règle MDC​

Références​