CLAUDE.md avancé

Pourquoi un CLAUDE.md “avancé” ?

Le thème 10 couvrait les bases : rôle du fichier, emplacement, hiérarchie. Ici, on passe au niveau suivant : comment structurer un CLAUDE.md qui reste utile à mesure que le projet grandit.

Point clé : CLAUDE.md est le Leverage Point 12 (instructions persistantes) du framework des 12 Leverage Points. C’est le levier le plus direct pour influencer le comportement de l’agent sur la durée.

Un CLAUDE.md avancé ne se contente pas de dire “utilise .NET” — il encode les conventions, les commandes, les workflows, et les interdictions spécifiques du projet.

Structurer le contenu

Sections recommandées

Un CLAUDE.md efficace pour un projet .NET en hexagonal pourrait contenir :

Point clé : L’ordre compte. Les informations en début de fichier ont plus de poids dans le contexte de l’agent. Placer les commandes build/test en premier, les conventions critiques ensuite.

Le pattern references/

Un CLAUDE.md de plus de 200 lignes commence à polluer le contexte à chaque tour. La solution : extraire les détails dans un dossier references/ et ne garder dans CLAUDE.md que les instructions essentielles + des pointeurs.

# CLAUDE.md (compact)
## Commandes
- Build : dotnet build src/
- Tests : dotnet test --no-build
- Lint : dotnet format --check

## Architecture
Hexagonal. Voir references/architecture.md pour les détails.

## Conventions
Voir references/conventions.md

## Do's / Don'ts
- NE PAS mettre de logique dans les controllers
- NE PAS utiliser de static mutable
- Toujours injecter les dépendances via le constructeur

Attention : L’agent ne lit pas automatiquement les fichiers references/. Il les consulte quand il en a besoin — ce qui est exactement le comportement voulu. Un CLAUDE.md compact + des références détaillées = un agent qui a les essentiels en mémoire permanente et les détails à portée de main.

Intégration avec hooks et slash commands

CLAUDE.md ne travaille pas seul. Il s’intègre avec d’autres mécanismes de Claude Code :

Hooks PostToolUse : un CLAUDE.md qui dit “lance les tests après chaque modification” est renforcé par un hook qui le fait automatiquement. Le CLAUDE.md donne l’intention, le hook garantit l’exécution.

Slash commands : un workflow décrit dans CLAUDE.md (“pour ajouter un aggregate, suivre ces étapes…”) peut être encapsulé dans une slash command /new-aggregate qui envoie le prompt complet.

Le trio CLAUDE.md + hooks + slash commands forme la base de ce qu’on appelle l’Agentic Layer (LP12 + LP9 + workflows capitalisés).

Maintenance et évolution

Quand mettre à jour le CLAUDE.md ?

A chaque fois que l’agent fait une erreur répétée : si l’agent place du code au mauvais endroit deux fois, c’est un signal pour ajouter une règle dans CLAUDE.md. C’est un processus itératif, pas un one-shot.

Versionner avec le projet

CLAUDE.md fait partie du code source. Il se commite, se review, et évolue avec le projet. Un CLAUDE.md obsolète est pire qu’un CLAUDE.md absent — il donne des instructions fausses à l’agent.

Attention : Ne pas copier-coller la documentation officielle dans CLAUDE.md. Il doit contenir les conventions spécifiques au projet, pas des rappels génériques du langage. L’agent connaît déjà C# — il ne connaît pas vos conventions.