Règles d'agent (.cursorrules / CLAUDE.md / AGENTS.md)

1. Vue d'ensemble du concept et problème systémique

Les LLM modernes sont entraînés sur des gigaoctets de code open source provenant de GitHub, ce qui les amène par défaut à générer un code « moyen » : versions majeures obsolètes de bibliothèques, motifs d'importation chaotiques, usage d'any en TypeScript ou approches inefficaces pour la gestion des erreurs. Lorsqu'un ingénieur travaille dans une paradigme de vibe coding sans règles fixées, chaque nouveau prompt devient une loterie :

• L'agent installe moment.js ou axios obsolètes au lieu de date-fns natif ou fetch.
• L'agent mélange les couches architecturales (par exemple, il accède directement à la base de données depuis un composant React client).
• L'agent invente ses propres commandes de compilation ou de test au lieu d'utiliser les scripts existants du projet.

Agent Rules (fichiers .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc) résolvent le problème de dérive de la base de code. Ils transforment les conventions internes de l'équipe en un contrat système lu par l'environnement de développement ou l'agent terminal avant même le début de toute génération de code.

2. Taxonomie architecturale et modèle mental

Les règles du dépôt se divisent en trois niveaux d'isolation et d'activation :

┌─────────────────────────────────────────────────────────────┐
│                   NIVEAUX DE RÈGLES DE L'AGENT              │
├─────────────────────────────────────────────────────────────┤
│ 1. Couche Globale / Machine (~/.cursorrules, ~/.claude.json) │
│    Préférences du développeur spécifique (langue, style de   │
│    réponse)                                                  │
├─────────────────────────────────────────────────────────────┤
│ 2. Couche Centrale du Dépôt (CLAUDE.md, AGENTS.md, règles    │
│    racine)                                                   │
│    Stack global, bibliothèques interdites, commandes lint /  │
│    test                                                      │
├─────────────────────────────────────────────────────────────┤
│ 3. Règles à Portée Limitée / Pilotées par Événements         │
│    (.cursor/rules/*.mdc)                                     │
│    Activation via motif glob (par ex., routes API, UI, DB)   │
└─────────────────────────────────────────────────────────────┘

1. Règles globales du dépôt (Core Repository Contract) :
   • Situées à la racine du projet (CLAUDE.md pour Claude Code, AGENTS.md ou .cursorrules pour les éditeurs).
   • Décritent le minimum critique : versions de l'environnement (Node.js 22, Bun, Python 3.12), gestionnaire de paquets (pnpm), linter obligatoire et instructions concernant la structure des commits.
2. Règles modulaires contextuelles (Scoped Domain Rules) :
   • Fichiers avec métadonnées et patterns glob (par exemple, .cursor/rules/database.mdc avec le filtre src/db/**/*.ts).
   • Chargées dans la mémoire de travail du modèle uniquement lorsque l'agent prévoit de modifier des fichiers de migration ou des modèles ORM.
3. Garde-fous opérationnels (Operational Guardrails) :
   • Contraintes négatives claires (Negative Constraints) : « NE JAMAIS exécuter git push --force », « NE JAMAIS modifier .env.production », « NE PAS ajouter de nouvelles dépendances sans accord explicite de l'ingénieur ».

3. Pipeline technique et mécanique interne

Cycle de vie des règles lors d'une session de vibe coding :

1. Initialisation de la session et scan du dépôt : L'IDE ou l'agent CLI scanne le dossier racine et les répertoires de service .cursor/rules/ ou .agents/rules/ au démarrage.
2. Analyse de l'intention et correspondance des masques (Glob Matching) : L'utilisateur soumet une requête (« Créer un nouvel endpoint pour le paiement d'abonnement »). L'agent prédit des modifications de fichiers dans src/app/api/stripe/route.ts. Le moteur de règles active les règles pour src/app/api/**/*.ts et stripe.mdc.
3. Assemblage du prompt système étendu : Le moteur concatène :
   • Le System Prompt de base du modèle ;
   • Le contenu du fichier de contrat global ;
   • Les règles modulaires trouvées ;
   • L'arbre actuel des fichiers ouverts et la requête utilisateur.
4. Génération de code avec respect forcé des invariants : Le modèle forme un appel d'outil ou du code en référençant les règles comme contexte système obligatoire.
5. Validation post-génération : Si l'agent a accès au terminal, il exécute la commande de validation spécifiée dans les règles (par exemple, pnpm typecheck) avant de retourner le rapport final à l'ingénieur.

4. Scénarios d'ingénierie pratiques en production

01. Frontières architecturales dans Next.js 15+ App Router

Le fichier .cursor/rules/nextjs.mdc avec le masque src/app/**/*.tsx prévient les erreurs classiques d'utilisation des composants serveur et client :

---
description: Standards architecturaux pour Next.js App Router
globs: src/app/**/*.tsx, src/components/**/*.tsx
---
- Par défaut, tous les composants sont des Server Components.
- La directive 'use client' ne doit être ajoutée QUE si le composant utilise useState, useEffect ou des gestionnaires d'événements onClick/onChange.
- Il est INTERDIT d'importer des utilitaires serveur (db, secret d'authentification) dans les fichiers contenant la directive 'use client'.
- Toutes les mutations de données doivent être effectuées exclusivement via des Server Actions situées dans le répertoire `src/actions/`.

02. Exécution déterministe des tests pour Claude Code

La configuration CLAUDE.md garantit que l'agent terminal utilise exclusivement les scripts de test corrects, sans tenter de lancer un jest global incompatible :

# Lignes directrices du dépôt pour Claude Code

## Commandes
- Build : `pnpm build`
- Vérification des types : `pnpm tsc --noEmit`
- Tests unitaires : `pnpm test:unit`
- Tests E2E : `pnpm test:e2e`

## Discipline de workflow
Avant d'indiquer que la tâche a été exécutée avec succès :
1. Exécutez `pnpm tsc --noEmit`. S'il y a des erreurs de typage, corrigez-les.
2. Exécutez `pnpm test:unit` pour les modules modifiés.
3. Ne créez pas de nouveaux fichiers sans avoir vérifié au préalable l'existence d'utilitaires dans `src/lib/`.

03. Sécurité typographique forcée et validation Zod dans l'API

La règle backend empêche l'utilisation de payloads JSON non typés dans les contrôleurs :

---
description: Standardisation des points de terminaison backend
globs: src/server/api/**/*.ts
---
- Tous les arguments d'entrée des requêtes doivent être validés via des schémas Zod (`schema.parseAsync(req.body)`).
- Le type `any` est strictement interdit ; lors du traitement de données inconnues, utiliser `unknown` suivi d'un narrowing de type.
- En cas d'erreurs métier, lever un `TRPCError` ou un `HttpError` typé avec le code de statut approprié.

5. Pièges, erreurs courantes et sécurité

• Encombrement des règles (Rule Bloat & Attention Saturation) : Tenter de consigner toute la documentation du projet dans le fichier de règles conduit à des fichiers dépassant 500 lignes. Cela dilue l'attention du modèle (« Lost in the Middle ») et pousse le modèle à ignorer les directives clés. Divisez les règles en scopes modulaires.
• Règles contradictoires ou en conflit : Si le CLAUDE.md global exige l'utilisation de pnpm, tandis qu'un vieux README.md ou une règle locale contient npm install, le modèle peut boucler dans des hallucinations de gestionnaire de paquets.
• Danger de fuite de données sensibles : Ne spécifiez jamais de tokens d'accès, de mots de passe de bases de test ou de clés API personnelles dans les règles du dépôt. Toutes les variables d'environnement doivent être décrites uniquement sous forme de noms abstraits (par exemple, DATABASE_URL is required in .env.local).
• Absence de versioning : Les règles des agents doivent évoluer conjointement avec la base de code dans le système de contrôle de version Git. Un changement de stack technologique doit s'accompagner d'une mise à jour atomique des fichiers de règles correspondants dans le même commit.