Cursor Rules : Comment écrire des fichiers .cursor/rules qui fonctionnent vraiment

Tout utilisateur de Cursor finit par se heurter au même obstacle. L'IA génère du code qui fonctionne techniquement, mais ignore les conventions de votre projet — mauvais chemins d'import, patterns obsolètes, composants qui ne ressemblent en rien au reste de votre base de code. Les Cursor Rules règlent ce problème en donnant à l'IA un contexte persistant sur le fonctionnement de votre projet.

Que sont les Cursor Rules et pourquoi sont-elles importantes ?

Les Cursor Rules sont des fichiers Markdown qui servent de prompt système permanent injecté avant chaque interaction avec l'IA — chat, autocomplétion, génération de code, tout y passe. Considérez-les comme la documentation d'onboarding de votre IA. Au lieu de corriger les mêmes erreurs à chaque session, vous écrivez l'instruction une fois et elle reste en place.

L'ancienne approche consistait en un seul fichier .cursorrules à la racine du projet. Ça fonctionne encore, mais c'est déprécié. Le système actuel utilise un répertoire .cursor/rules/ avec des fichiers .mdc individuels (Markdown Cursor), chacun adapté à des situations spécifiques. C'est une bien meilleure organisation, car vous n'entassez plus toutes les instructions dans un seul fichier géant — vous séparez les règles par responsabilité, et Cursor ne charge que celles pertinentes à ce que vous faites en ce moment.

Si vous avez travaillé avec le context engineering pour les outils IA, le concept est familier : un meilleur contexte d'entrée produit des sorties nettement meilleures. Les règles, c'est du context engineering pour tout votre workflow de développement.

Configurer votre premier fichier de règles

Créez le répertoire .cursor/rules/ à la racine de votre projet :

mkdir -p .cursor/rules

Chaque règle est un fichier .mdc avec un frontmatter YAML suivi de contenu Markdown. Voici le squelette :

---
description: "Quand cette règle doit s'appliquer"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

Vos instructions ici en Markdown simple.

Trois champs de frontmatter contrôlent tout :

Vous pouvez aussi créer des règles directement dans Cursor — tapez /create-rule dans le chat et décrivez ce que vous voulez. Mais les écrire manuellement vous donne plus de contrôle.

Les quatre types de règles expliqués

La façon dont une règle s'active dépend de sa configuration frontmatter. Il existe quatre modes, et choisir le bon compte pour votre budget de fenêtre de contexte.

Toujours appliquée

---
alwaysApply: true
---

Chargée dans chaque requête IA sans exception. À utiliser avec parcimonie — pour les fondamentaux à l'échelle du projet comme la déclaration de votre stack ou les conventions critiques qui s'appliquent partout. Chaque règle toujours active consomme des tokens à chaque interaction, qu'elle soit pertinente ou non.

Attachée automatiquement (basée sur glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

Ne s'active que lorsque vous éditez des fichiers correspondant aux patterns glob. C'est le type de règle le plus utile au quotidien. Vos conventions de composants React se chargent quand vous êtes dans les fichiers de composants, vos patterns d'API quand vous êtes dans les handlers de routes, vos règles de tests quand vous écrivez des tests.

Demandée par l'agent (intelligente)

---
description: "Patterns de migration de base de données avec Drizzle ORM"
alwaysApply: false
---

Pas de globs, pas d'always-apply — juste une description. L'agent de Cursor lit la description et décide si la règle est pertinente pour la tâche en cours. Si vous lui demandez d'écrire une migration, il charge cette règle. Si vous stylisez un bouton, il l'ignore. Ça fonctionne étonnamment bien pour les règles qui ne se mappent pas nettement sur des chemins de fichiers.

Manuelle

---
---

Aucun champ frontmatter défini (ou frontmatter vide). Ces règles ne s'activent que lorsque vous les mentionnez explicitement avec @nom-de-règle dans le chat. Idéal pour les instructions rarement utilisées mais importantes — comme les checklists de déploiement ou les guides de refactoring dont vous n'avez besoin qu'occasionnellement.

Les patterns glob qui fonctionnent vraiment

Les globs déterminent quels fichiers déclenchent les règles attachées automatiquement. Mal configurés, vos règles ne se déclenchent jamais ou se déclenchent partout. Voici ce qui fonctionne :

# Tous les fichiers TypeScript dans src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# Uniquement les fichiers de composants
globs: ["**/components/**/*.tsx"]

# Fichiers Python, en excluant les tests
globs: ["**/*.py", "!**/test_*.py"]

# Plusieurs répertoires spécifiques
globs: ["src/api/**", "src/services/**"]

Quelques pièges tirés de l'usage réel :

• src/* ne correspond qu'à un seul niveau de répertoire. Vous voulez presque toujours src/**/* pour la correspondance récursive.
• *.js ne correspond pas aux fichiers .jsx ou .ts. Soyez explicite sur les extensions.
• Les globs doivent être une liste YAML. La syntaxe avec accolades comme {src,lib}/**/*.ts peut échouer silencieusement — préférez des entrées de liste séparées.
• Le préfixe ! exclut des patterns, ce qui est utile pour ignorer les fichiers générés ou le code legacy.

Exemples de règles concrets

C'est là que la théorie rencontre la réalité. Ce sont des règles que vous pouvez intégrer dans un projet et voir immédiatement de meilleures sorties IA.

Règle de base à l'échelle du projet (Toujours appliquée)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

Gardez ça sous 30 lignes. C'est chargé à chaque requête, donc chaque mot coûte des tokens.

Règle pour les composants React (Attachée automatiquement)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### Règle API Python (Attachée automatiquement)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### Règle de service Go (Attachée automatiquement)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## Gérer la taxe en tokens

Voici quelque chose que la plupart des guides Cursor passent sous silence : chaque règle que vous écrivez coûte des tokens. Un projet avec 20 règles toujours actives peut brûler **plus de 2 000 tokens par requête** rien que pour les instructions — avant même que l'IA regarde votre code.

C'est important parce que le contexte de chat de Cursor représente environ 20 000 tokens en mode standard. Si vos règles en consomment 25 %, vous avez perdu un quart de l'"espace de réflexion" de l'IA pour votre vraie question. Vous remarquerez une dégradation de la qualité des sorties à mesure que les règles s'accumulent, surtout dans les conversations longues.

Trois principes pour maintenir un budget de tokens sain :

**1. Utilisez les règles attachées automatiquement et demandées par l'agent sans retenue.** Seule la déclaration de votre stack devrait être toujours active. Tout le reste devrait se charger conditionnellement. Cette règle sur les composants React ? Elle n'a pas besoin d'être en contexte quand vous écrivez des migrations SQL.

**2. Écrivez dense, pas verbeux.** Remplacez "Il est fortement recommandé que les développeurs utilisent les interfaces TypeScript plutôt que les alias de type pour définir les contrats d'API publics" par "Prefer `interface` over `type` for public APIs." L'IA n'a pas besoin d'être convaincue — elle a besoin d'instructions.

**3. Appliquez la règle des trois.** Ne codifiez un pattern en règle qu'après que l'IA s'est trompée trois fois. Si Cursor gère déjà vos conventions de nommage correctement sans règle, sautez la règle. Chaque règle inutile est du contexte gaspillé.

Vous pouvez surveiller l'utilisation des tokens dans la barre de statut en bas du panneau de chat de Cursor. Guettez quand elle approche les 100 % — c'est le signal qu'il faut élaguer.

## Organiser les règles pour un vrai projet

Un projet en production nécessite généralement 5 à 8 fichiers de règles. Voici une structure qui fonctionne bien :

```text
.cursor/rules/
  base.mdc            # Stack tech, always-apply (< 30 lignes)
  components.mdc      # Patterns React/Vue, glob vers les répertoires de composants
  api.mdc             # Conventions backend, glob vers les répertoires API
  database.mdc        # Patterns ORM, glob vers models/migrations
  testing.mdc         # Conventions de test, glob vers les fichiers de test
  deployment.mdc      # Patterns CI/CD, déclenchement manuel
  personal.mdc        # Vos préférences (gitignored)

Committez tout en contrôle de version sauf personal.mdc. Ainsi toute votre équipe bénéficie du même comportement IA — c'est tout le but. Comme le dit un utilisateur du forum Cursor, de bonnes règles signifient que vous "acceptez plus de suggestions telles quelles, avec des sorties qui correspondent à vos conventions dès le premier essai."

Si vous travaillez avec d'autres outils de développement IA aux côtés de Cursor, les concepts se transfèrent directement. Claude Code utilise CLAUDE.md, GitHub Copilot a des fichiers d'instruction, et Windsurf a son propre format — mais le principe sous-jacent est identique.

Comment fonctionne la priorité des règles

Quand plusieurs règles s'appliquent au même fichier, Cursor suit une hiérarchie claire :

Les Team Rules sont disponibles dans les plans Team et Enterprise. Elles sont définies dans le tableau de bord Cursor par les admins et appliquées dans toute l'organisation — les développeurs individuels ne peuvent pas les désactiver.

Au sein des règles de projet, si deux règles s'appliquent au même fichier et entrent en conflit, le comportement n'est pas strictement défini. En pratique, les règles chargées plus tard ont tendance à l'emporter. Numéroter vos fichiers (001-base.mdc, 002-components.mdc) vous donne un ordre prévisible.

Erreurs courantes et comment les corriger

Après avoir parcouru des dizaines de fils de discussion communautaires et testé des règles dans divers projets, voici les erreurs qui font le plus trébucher les gens :

Écrire des règles trop vagues. "Écrivez du code propre" ne dit rien à l'IA. "Utilisez des exports nommés, pas des exports par défaut. Structurez les composants comme suit : imports, types, fonction, sous-composants" lui donne quelque chose d'actionnable.

Mettre tout en always-apply. Le premier réflexe est de mettre alwaysApply: true sur chaque règle. Résistez-y. Auditez vos règles trimestriellement — si vous avez plus de 2-3 règles toujours actives, vous gaspillez probablement des tokens.

Oublier de tester les règles. Après avoir écrit une règle, ouvrez un fichier pertinent et demandez à Cursor de générer quelque chose qui devrait la respecter. Si ce n'est pas le cas, votre pattern glob est peut-être incorrect, ou l'instruction n'est pas assez claire.

Ne pas documenter les anti-patterns. Dire à l'IA ce qu'il faut faire représente la moitié du travail. Lui dire ce qu'il ne faut pas faire représente l'autre moitié. Incluez dans chaque règle une section "Ne jamais faire cela" avec des exemples explicites de la mauvaise approche.

Ignorer les sauvegardes de règles dans l'UI. Un bug connu provoque la disparition des modifications de règles. Si les changements disparaissent, fermez Cursor complètement, sélectionnez "Remplacer" dans le popup des changements non sauvegardés, et rouvrez-le.

Cursor Rules vs CLAUDE.md vs AGENTS.md

Cursor n'est pas le seul outil à utiliser des fichiers d'instructions. Voici comment les formats se comparent pour quiconque travaille avec plusieurs assistants IA de développement :

L'avantage de Cursor est la granularité. CLAUDE.md et AGENTS.md sont plus simples — ils chargent tout en permanence. Cursor vous permet de charger les bonnes règles au bon moment, ce qui compte vraiment quand votre ensemble d'instructions dépasse quelques centaines de lignes.

Pour une analyse approfondie de la façon dont le contexte façonne les sorties IA dans ces outils, notre guide du context engineering détaille les principes qui s'appliquent quel que soit l'éditeur que vous utilisez.

FAQ

Est-ce que .cursorrules est déprécié ?

Oui. Le fichier .cursorrules unique à la racine de votre projet fonctionne encore, mais Cursor recommande de migrer vers des fichiers .cursor/rules/*.mdc. Le nouveau format supporte les patterns glob, le chargement conditionnel et une meilleure organisation. Migrez en découpant votre fichier monolithique en règles ciblées.

Quelle extension de fichier utiliser — .mdc ou .md ?

Utilisez .mdc pour les fichiers qui incluent du frontmatter YAML (description, globs, alwaysApply). Les fichiers .md simples fonctionnent aussi dans le répertoire rules, mais ne supportent pas les métadonnées frontmatter qui permettent le chargement conditionnel.

Combien de règles un projet devrait-il avoir ?

Cinq à huit est la zone idéale pour la plupart des projets. Une règle de base toujours active, trois à quatre règles attachées automatiquement par type de fichier, et une ou deux règles manuelles pour des tâches spéciales. Plus de 10 règles signifie généralement que certaines peuvent être consolidées ou supprimées.

Les Cursor Rules affectent-elles l'autocomplétion et la complétion par tabulation ?

Les règles s'appliquent aux interactions chat et agent. Les User Rules ne s'appliquent pas aux modifications inline (Cmd/Ctrl+K), et les règles n'impactent généralement pas les suggestions de Cursor Tab. Elles sont plus efficaces dans les sessions chat et Composer.

Puis-je partager des règles entre plusieurs projets ?

Oui, via la fonctionnalité Remote Rules de Cursor. Allez dans Cursor Settings > Rules, Commands, sélectionnez "Remote Rule (GitHub)" et collez une URL de dépôt. Les règles se synchronisent automatiquement quand le dépôt source se met à jour. Vous pouvez aussi maintenir un dépôt de règles partagé et créer des liens symboliques dans chaque projet.

Quelle est la longueur maximale recommandée pour une règle ?

La documentation de Cursor suggère de garder les règles individuelles sous 500 lignes. En pratique, visez moins de 100 lignes par règle. Des règles plus courtes sont plus faciles à maintenir et coûtent moins de tokens. Si une règle dépasse 150 lignes, divisez-la en deux règles ciblées.

Les règles fonctionnent-elles avec tous les modèles IA dans Cursor ?

Les règles fonctionnent avec chaque modèle supporté par Cursor — Claude, GPT-4o, Gemini et autres. Les règles sont injectées comme contexte au niveau système, quel que soit le modèle sélectionné. Le comportement du modèle peut varier, mais les règles elles-mêmes sont agnostiques au modèle.

Comment déboguer une règle qui ne fonctionne pas ?

Vérifiez d'abord que le pattern glob correspond à votre fichier — ouvrez le fichier et vérifiez si la règle apparaît dans le panneau de contexte. Ensuite, testez avec une question directe qui devrait déclencher la règle. Essayez ensuite de mettre alwaysApply: true temporairement pour confirmer que le contenu de la règle fonctionne lui-même. Si oui, le problème vient de votre pattern glob.

Dois-je committer .cursor/rules dans git ?

Absolument. Tout le principe des règles de projet est la cohérence à l'échelle de l'équipe. Committez tout dans .cursor/rules/ sauf les fichiers de préférences personnelles. Ajoutez personal.mdc au .gitignore pour les paramètres individuels qui ne devraient pas s'appliquer à tout le monde.

Puis-je utiliser Cursor Rules avec des serveurs MCP ?

Oui, et ils se complètent très bien. Les règles définissent comment l'IA doit écrire le code, tandis que les serveurs MCP donnent à l'IA accès à des outils et des données externes. Une règle pourrait dire "utilisez toujours notre client API interne", tandis qu'un serveur MCP permet à l'IA d'interroger réellement cette API pendant le développement.

Si des fonctionnalités IA figurent sur votre feuille de route, c'est notre spécialité : l'équipe d'intégration IA de Techsy fait passer les systèmes LLM du prototype à la production. Besoin d'un second avis sur votre stack ? Demandez une consultation gratuite.

Sources

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub