CLAUDE.md : le contrat avec l'agent

Qu’est-ce que CLAUDE.md ?

CLAUDE.md est un fichier Markdown placé à la racine d’un projet (ou dans ~/.claude/ pour des instructions globales). Claude Code le lit automatiquement au démarrage de chaque session. C’est l’équivalent d’un briefing écrit donné à un nouveau collègue avant qu’il touche au code.

Point clé : Sans CLAUDE.md, l’agent part de zéro à chaque session. Avec un bon CLAUDE.md, il connaît vos conventions, vos patterns, et vos interdits dès le premier tour.

Dans le cadre des 12 Leverage Points, CLAUDE.md correspond au LP12 : instructions persistantes. C’est le levier qui donne de la continuité à l’agent entre les sessions, sans répéter le même contexte dans chaque prompt.

Que mettre dans un CLAUDE.md ?

Les conventions du projet

Langages, frameworks, versions du SDK, patterns architecturaux (hexagonal, DDD, CQRS…), conventions de nommage. L’agent doit savoir dans quel cadre il opère.

Les commandes essentielles

Comment builder, lancer les tests, linter. L’agent a besoin de ces commandes pour vérifier son travail dans la boucle agentique.

# Build & test
dotnet build src/MyApp.sln
dotnet test tests/ --no-build

# Lint
dotnet format src/MyApp.sln --verify-no-changes

Les do’s and don’ts

Les règles non négociables : pas de var partout, pas de logique métier dans les controllers, toujours un test pour chaque nouvelle méthode publique. Ces instructions agissent comme des garde-fous permanents.

Les pointeurs vers la documentation

Plutôt que de tout mettre dans CLAUDE.md, pointer vers des fichiers de référence : references/architecture.md, references/conventions.md. L’agent les lira à la demande.

Point clé : Un bon CLAUDE.md est un sommaire orienté action, pas une encyclopédie. Il dit quoi faire et où trouver les détails.

Hiérarchie des fichiers CLAUDE.md

Claude Code supporte plusieurs niveaux de CLAUDE.md. Ils se cumulent, du plus général au plus spécifique :

En cas de conflit, le fichier le plus proche du contexte de travail prend le dessus. Cette hiérarchie permet d’avoir des règles globales sans polluer chaque sous-module avec du contenu non pertinent.

Pièges courants

Attention : Un CLAUDE.md de 2000 lignes est contre-productif. Chaque token du fichier est injecté dans le contexte de l’agent à chaque session. Plus le fichier est long, plus il consomme de la fenêtre de contexte et dilue les instructions importantes.

Le CLAUDE.md fantôme

Un fichier écrit une fois et jamais mis à jour. Les conventions changent, le fichier ne suit pas, et l’agent applique des règles obsolètes. Traiter CLAUDE.md comme du code : il doit être révisé à chaque changement significatif du projet.

Le CLAUDE.md trop vague

“Écris du bon code” n’est pas une instruction exploitable. L’agent a besoin de règles concrètes : “Utilise decimal pour les montants, jamais double”, “Chaque commande CQRS a son propre handler”.

Le CLAUDE.md qui duplique la doc

Recopier la documentation officielle de .NET ou d’un framework dans CLAUDE.md est du gaspillage de tokens. L’agent connaît déjà ces frameworks. Le fichier doit contenir ce que l’agent ne peut pas deviner : vos conventions spécifiques, vos choix architecturaux, vos exceptions aux règles habituelles.