Conventions C# dans CLAUDE.md

Le CLAUDE.md, contrat de conventions chargé à chaque session

Le CLAUDE.md est un fichier Markdown placé à la racine du projet. Claude Code le lit automatiquement au démarrage de chaque session : c’est le Leverage Point 12, les instructions persistantes. C’est l’endroit naturel pour encoder vos conventions C# afin que l’agent les applique dès le premier tour, sans qu’on les répète dans chaque prompt.

On peut le voir comme un contrat : il aligne l’agent sur le projet en disant ce qu’on attend et ce qu’on proscrit. Mais un contrat n’est utile que s’il est lu et compris. Un CLAUDE.md court et concret tient ce rôle ; une encyclopédie de style le trahit.

Point clé : Le CLAUDE.md est injecté dans le contexte à chaque session. Tout ce qu’on y met coûte des tokens, à chaque tour, pour toute la durée de la session.

Quoi mettre : ce que l’agent ne peut pas deviner

Le modèle a déjà vu d’énormes quantités de C# idiomatique. Il connaît le PascalCase pour les méthodes, le préfixe underscore pour les champs privés, le suffixe Async. Recopier la convention de nommage officielle de Microsoft ne lui apprend rien et gaspille du contexte.

Ce qui mérite d’y figurer, c’est ce que l’agent ne peut pas inférer : vos choix maison, vos exceptions, le vocabulaire métier de votre domaine. Et les commandes pour vérifier son travail.

Le squelette utile d’un CLAUDE.md C#

# Commandes
- Build : dotnet build src/MyApp.sln
- Tests : dotnet test --no-build
- Format : dotnet format --verify-no-changes

# Conventions specifiques
- Tout montant monetaire : decimal, jamais double ni float
- Suffixe Handler pour les command handlers
- Pas de logique metier dans les controllers

# Exemples a imiter
- Handler de reference : src/Application/Orders/PlaceOrderHandler.cs

# Details
- Voir references/conventions-csharp.md

Point clé : Une convention exploitable est concrète et vérifiable : « pour tout montant, decimal, jamais double ». « Respecte les bonnes pratiques » n’aligne rien — l’agent doit deviner la règle.

Attention — recopier la documentation officielle du langage ou d’un framework dans le CLAUDE.md. L’agent connaît déjà C# et .NET. Le fichier doit porter vos conventions, pas un rappel générique que le modèle a déjà intégré.

Montrer plutôt que décrire : l’exemple comme convention

Pour un pattern récurrent — un command handler, un value object, un endpoint — un exemple de code existant aligne l’agent bien mieux qu’une longue règle en prose. C’est le Leverage Point 11. Un fichier réel montre d’un coup le nommage, l’injection par constructeur, le style de retour et les détails implicites que vous oublieriez de verbaliser.

Pointez vers un fichier représentatif et dites « imite ce modèle ». C’est plus court à écrire, plus difficile à mal interpréter, et le résultat colle au reste de la codebase. Le langage ubiquitaire vit alors dans les noms : quand les classes s’appellent Order, Deliver, Cancel, le prompt se réduit presque à une phrase métier.

Point clé : Montre, ne décris pas. Un exemple concret porte plus d’information utile qu’un paragraphe abstrait, et l’agent s’y aligne naturellement.

Les types comme feedback : ce que le contrat délègue

Écrire « ne laisse jamais de référence nulle non gérée » dans le CLAUDE.md exprime une intention. Mais le texte ne contraint rien à l’exécution : l’agent peut très bien produire un bug qu’on lui a interdit par écrit. Le vrai garde-fou, c’est le système de types — le Leverage Point 6.

Avec les nullable reference types activés et les warnings traités comme des erreurs, une déréférence potentiellement nulle casse le build. L’agent voit l’erreur de compilation dans la sortie console et se corrige dans la boucle. Le type fort transforme une convention molle en signal dur et automatique.

Point clé : Ce qui est déjà mécanisable (nullabilité, format, conventions standard) revient au compilateur, à l’EditorConfig et aux analyseurs Roslyn. Le répéter par écrit gaspille du contexte et crée deux sources de vérité.

Le garder court : le piège du CLAUDE.md de 2000 lignes

Un guide de style C# complet peut faire 1500 lignes : nommage détaillé, ordre des membres, usage des records, conventions LINQ, exemples. Collé intégralement dans le CLAUDE.md, il sature le contexte et dilue les instructions importantes — l’agent commence à oublier les règles citées au milieu du fichier.

Le remède est le pattern references/. On garde un CLAUDE.md compact avec l’essentiel et des pointeurs, et on déplace le détail dans un fichier que l’agent consulte à la demande.

# CLAUDE.md (compact)
## Conventions critiques
- decimal pour les montants, jamais double
- Suffixe Handler, pas de logique dans les controllers

## Detail
Voir references/conventions-csharp.md (lu a la demande)

Attention — diviser en CLAUDE-1.md et CLAUDE-2.md, ou dupliquer les règles en début et fin de fichier. Claude Code ne lit que les fichiers nommés CLAUDE.md, et dupliquer ne fait qu’aggraver la taille. Le bon réflexe : extraire vers references/, pas multiplier les fichiers.

Point clé : L’essentiel en mémoire permanente, le détail à portée de main. Un contrat utile dit l’intention, fixe les frontières, et fait confiance aux outils déterministes pour le reste.