Bonnes pratiques pour CLAUDE.md : les règles pour que votre agent les respecte

Un fichier CLAUDE.md est chargé à chaque session de Claude Code. Un bon fichier démultiplie vos résultats, tandis qu’un fichier surchargé vous ralentit discrètement à chaque tâche. Voici les bonnes pratiques qui font vraiment la différence, par ordre d’importance.

1. Ne dépassez pas environ 200 lignes

C’est la règle qui sauve la plupart des fichiers CLAUDE.md inefficaces. Les modèles de pointe ne peuvent suivre qu’un nombre limité d’instructions de manière fiable, et le prompt système de Claude Code consomme déjà une partie de ce budget avant même la lecture de votre fichier. Un fichier CLAUDE.md de 600 lignes n’est pas six fois plus utile. C’est un fichier que l’agent va survoler, en noyant vos règles importantes au milieu. Ici, la concision n’est pas un choix esthétique : c’est ce qui rend le fichier efficace.

2. Donnez la priorité aux comportements, pas à la documentation

L’erreur la plus fréquente consiste à traiter CLAUDE.md comme une base de connaissances : architecture, conventions complètes, ou simple copier-coller du README. L’agent sait déjà coder. Ce qui lui manque, c’est de la retenue. Le début du fichier doit donc regrouper les règles de comportement, c’est-à-dire les erreurs qu’il commettrait par réflexe.

3. Documentez uniquement ce qui diffère des standards

Chaque ligne écrite pour dire à l’agent ce qu’il sait déjà est une ligne de perdue pour les règles cruciales. Ne lui dites pas que React utilise des composants. Dites-lui que vous utilisez uniquement des exports nommés, que vous n’ajoutez jamais de dépendance sans demander, ou que les tests doivent être placés à un endroit précis. Donnez-lui le contexte qu’il ne peut pas deviner, et rien d’autre.

4. Placez les règles prioritaires en premier

Le fichier est lu de haut en bas, et le début reçoit l’attention la plus constante. Si une règle est non négociable, placez-la tout en haut, pas à la ligne 180. L’ordre est un levier puissant, utilisez-le.

5. Traitez-le comme un fichier vivant

L’habitude la plus payante : chaque fois que vous corrigez l’agent, ajoutez cette correction sous forme de règle pour qu’il ne refasse plus jamais la même erreur. En quelques semaines, votre fichier CLAUDE.md devient une cartographie précise des faiblesses de votre agent, et il cesse de commettre ces erreurs. Terminez vos corrections par une instruction simple lui demandant de mettre à jour le fichier.

6. Commitez-le, et séparez le personnel du projet

Les règles du projet vont dans ./CLAUDE.md à la racine du dépôt, un fichier commité dans git, pour que toute votre équipe bénéficie du même comportement de l’agent au lieu que chacun ajuste le sien de son côté. Vos préférences personnelles, la façon dont vous aimez que l’agent travaille sur tous vos projets, vont dans ~/.claude/CLAUDE.md et restent locales sur votre machine.

Le plus difficile, c’est la formulation

Aucune de ces pratiques n’est compliquée. Tout le travail réside dans la formulation : rédiger des règles de comportement auxquelles un agent obéit vraiment, plutôt que des consignes qu’il approuve avant de les ignorer, demande de nombreux ajustements. C’est exactement ce que propose kitstarter : un fichier CLAUDE.md et un ensemble de commandes optimisés pour que l’agent pose des questions avant de coder et reste concis, prêts à l’emploi. Rédigez le vôtre en suivant les règles ci-dessus, ou partez d’une base qui a déjà fait ses preuves.

Questions fréquentes

Quelle doit être la longueur d’un fichier CLAUDE.md ? Moins de 200 lignes environ. Au-delà, l’agent survole le texte et vos règles perdent de leur impact.

Quelle est l’erreur la plus fréquente ? Le remplir de documentation au lieu de règles de comportement. Donnez la priorité aux comportements et limitez le contexte à ce qui diffère des standards.

Faut-il ajouter CLAUDE.md dans git ? Oui pour les règles du projet (./CLAUDE.md). Vos préférences personnelles vont dans ~/.claude/CLAUDE.md, en local.