Services Projets Tarifs Blogue À propos Appel gratuit →

CLAUDE.md : que mettre dans le fichier de Claude Code?

Ce qu’il faut écrire dans CLAUDE.md, ce qu’il faut laisser de côté, où le placer et comment le garder court, selon la documentation de Claude Code.

CLAUDE.md est un fichier texte que Claude Code lit au début de chaque séance. Il doit contenir ce que l’outil ne peut pas deviner en lisant votre code : les commandes de build et de test, les conventions de l’équipe, la structure du projet et quelques règles du type « toujours faire X ». Gardez-le court, précis et à jour. Un fichier long ou contradictoire donne de moins bons résultats qu’un fichier mince.

Voici comment décider quoi y mettre, selon la documentation officielle sur la mémoire de Claude Code (état de novembre 2026).

Pourquoi ce fichier existe-t-il?

Chaque séance de Claude Code repart d’une fenêtre de contexte vide. Le CLAUDE.md est l’un des deux mécanismes qui transportent le savoir d’une séance à l’autre. L’autre, la mémoire automatique, regroupe des notes que Claude écrit lui-même à partir de vos corrections.

La documentation précise un point important : Claude traite ces fichiers comme du contexte, non comme une configuration appliquée de force. Plus les instructions sont précises et concises, plus elles sont suivies de façon constante. Pour bloquer une action quoi que Claude décide, la documentation renvoie vers un hook PreToolUse ou vers les paramètres gérés.

Que faut-il y écrire?

La documentation dit de garder les faits dont Claude a besoin à chaque séance : commandes de build, conventions, organisation du projet, règles « toujours faire X ». Pour une équipe, voici une liste de départ :

  • la commande exacte pour lancer les tests, et celle pour la vérification de style;
  • la structure des dossiers, en quelques lignes (où vit l’API, où vivent les migrations);
  • les conventions qui ne se voient pas dans le code (nommage, gestion des erreurs, format des messages de commit);
  • les pièges connus : « ne jamais modifier les migrations déjà déployées »;
  • la définition de « terminé » : quelles vérifications doivent passer.

Ce qui n’y a pas sa place :

  • une procédure en plusieurs étapes, ou une consigne qui ne vaut que pour une partie du code. La documentation recommande plutôt une compétence (skill) ou une règle ciblée par chemin;
  • ce que l’outil découvre seul en lisant le dépôt;
  • les secrets. Le fichier est versionné et lu par tout le monde.

Où le placer?

Les emplacements, selon la documentation :

  • Projet : ./CLAUDE.md ou ./.claude/CLAUDE.md, partagé avec l’équipe par le contrôle de version.
  • Local : ./CLAUDE.local.md, pour vos préférences personnelles dans ce projet. À ajouter au .gitignore.
  • Politique gérée : un fichier au niveau du système (sous Linux, /etc/claude-code/CLAUDE.md), pour les normes de l’organisation. Les développeurs ne peuvent pas l’exclure avec claudeMdExcludes.

Les fichiers CLAUDE.md placés dans des sous-dossiers ne sont pas chargés au démarrage. Claude Code les charge quand il lit ou modifie un fichier de ce sous-dossier. Dans un monorepo, chaque équipe peut donc avoir ses propres consignes.

Quelle longueur viser?

La documentation donne une cible : moins de 200 lignes par fichier CLAUDE.md. Au-delà, le fichier consomme plus de contexte et le respect des consignes diminue.

Deux nuances utiles pour une équipe qui grandit :

  • Les imports ne réduisent pas le coût. On peut importer un fichier avec la syntaxe @chemin/du/fichier, mais le contenu importé est chargé avec le fichier qui l’importe. C’est un outil d’organisation, pas d’économie.
  • Les règles ciblées par chemin, oui. Dans .claude/rules/, un fichier avec un champ paths ne se charge que lorsque Claude travaille sur des fichiers correspondants. C’est l’endroit pour les consignes qui ne concernent que le front-end ou que les migrations.

Comment éviter qu’il pourrisse?

Un CLAUDE.md qui n’est pas entretenu devient un problème. La documentation avertit que, si deux consignes se contredisent, Claude peut en choisir une au hasard. Elle recommande de revoir périodiquement les fichiers, y compris ceux des sous-dossiers et .claude/rules/, pour retirer ce qui est périmé ou contradictoire.

Quelques habitudes simples :

  1. Traitez-le comme du code. Les changements passent par une revue, comme le reste du dépôt.
  2. Ajoutez une ligne quand Claude se trompe deux fois pareil. Pas avant.
  3. Retirez une ligne quand elle ne change plus rien. Retirez aussi les doublons avec la documentation du projet.
  4. Partez de /init. La documentation indique que cette commande génère un fichier de départ à partir de votre code, puis qu’on l’affine avec ce que Claude ne découvrirait pas seul.
  5. Lancez la vérification de vos consignes. La documentation mentionne un audit de prompt (/doctor prompt-audit) qui couvre les fichiers de consignes.

CLAUDE.md ou paramètres : lequel pour quoi?

Pour une organisation, la documentation sépare les deux rôles. Les paramètres gérés servent à l’application technique : bloquer des outils, des commandes ou des chemins avec permissions.deny, imposer l’isolation (sandbox). Le CLAUDE.md sert aux consignes de comportement : style de code, rappels sur le traitement des données, exigences de conformité.

Autrement dit, une règle que personne ne doit pouvoir contourner n’a pas sa place seulement dans un fichier de texte. Nous avons détaillé l’autre moitié dans notre article sur les règles de permissions pour toute l’équipe.

Par où commencer?

Chez Korvaed, nous commencerions par une séance d’une heure avec l’équipe : lister les cinq corrections que les développeurs répètent le plus souvent à l’agent, les écrire en une ligne chacune, puis mesurer si elles cessent. Nous séparerions ensuite ce qui est vrai pour tout le dépôt de ce qui ne l’est que pour un dossier. Si vous voulez un avis senior sur l’adoption des agents de code, voyez notre offre de CTO fractionnel.

Information générale. Les fonctions de Claude Code évoluent vite : confirmez-les dans la documentation officielle avant de déployer, et ne mettez jamais de secrets dans un fichier versionné.