Bien rédiger son fichier CLAUDE.md

Le fichier CLAUDE.md est le moyen le plus simple de faire travailler Claude Code selon vos règles. Bien rédigé, il évite de répéter les mêmes consignes à chaque session. Cet article rassemble les bonnes pratiques, en complément de la leçon Le fichier CLAUDE.md du cours Claude Code en action.

À quoi sert le fichier CLAUDE.md

À chaque démarrage, Claude Code lit le CLAUDE.md placé à la racine du projet et l'intègre à son contexte. C'est une note d'accueil permanente : vous y décrivez le projet, sa technologie, vos conventions et vos interdits. L'agent en tient compte sans que vous ayez à le rappeler.

Pensez-y comme à l'intégration d'un nouveau collègue : ce que vous lui diriez le premier jour a sa place dans le fichier.

Le principe directeur : concis et hiérarchisé

L'erreur la plus fréquente est le fichier fourre-tout. Un CLAUDE.md de plusieurs pages noie les consignes critiques. Visez un document court, organisé en sections claires avec des titres. L'agent, comme un lecteur humain, repère mieux l'information dans un texte structuré.

Préférez les règles actionnables aux généralités. « Écrire du bon code » n'aide personne ; « Ne jamais utiliser le type any » est une consigne nette que l'agent peut appliquer.

Que mettre dans le fichier

Voici les sections qui apportent le plus de valeur.

Présentation du projet

Quelques phrases sur la nature du projet, son objectif et son public. Ce cadrage aide l'agent à formuler des propositions cohérentes avec l'intention générale.

Stack technique

Listez les technologies, versions et bibliothèques imposées. Si votre projet utilise une version précise d'un framework, indiquez-la : l'agent évitera des suggestions obsolètes ou inadaptées.

Conventions de code

C'est souvent la section la plus utile : style, nommage, structure des dossiers, règles de typage, gestion des erreurs. Tout ce qui doit rester homogène mérite d'y figurer.

Commandes du projet

Indiquez comment lancer les tests, le build ou la vérification du code. L'agent saura ainsi vérifier son travail avec les bons outils.

Interdits et points de vigilance

Énoncez clairement ce qu'il ne faut jamais faire : fichiers à ne pas toucher, pratiques bannies, zones sensibles. Une interdiction explicite vaut mieux qu'un sous-entendu.

Un exemple de structure

Un CLAUDE.md clair peut s'organiser ainsi :

• Projet — nature, objectif, public en deux ou trois phrases.
• Stack — langages, frameworks, versions, contraintes.
• Commandes — installer, lancer, tester, vérifier.
• Conventions — style, nommage, organisation des fichiers.
• Règles — interdits explicites et points de vigilance.
• Structure — où se trouve quoi, ou renvoi vers un autre document.

Cette ossature couvre l'essentiel sans alourdir. Chaque section reste courte ; si l'une déborde, c'est le signe qu'un document dédié serait plus adapté.

Les erreurs à éviter

Le fichier obsolète. Un CLAUDE.md qui décrit une stack abandonnée induit l'agent en erreur. Mettez-le à jour comme le reste du code.

Les consignes contradictoires. Si une règle en contredit une autre, l'agent hésite. Relisez le fichier pour traquer les incohérences.

Le ton vague. « Faire attention à la performance » n'oriente rien. Préférez une règle mesurable ou un exemple concret.

L'oubli du versionnement. Un CLAUDE.md versionné se partage avec toute l'équipe et garde l'historique de vos décisions.

Faire vivre le fichier

Un bon CLAUDE.md n'est jamais figé. Quand une consigne donnée à l'oral revient souvent, ajoutez-la au fichier. Quand l'agent répète une erreur, c'est qu'une règle manque ou manque de clarté. Le fichier s'affine ainsi au fil du projet.

Pour aller plus loin, suivez la leçon Le fichier CLAUDE.md et notre guide Débuter avec Claude Code. Si vous préparez la certification CCA-F, savoir cadrer un agent IA par des consignes claires est une compétence directement valorisée.

En résumé

Le fichier CLAUDE.md guide Claude Code de façon permanente. Gardez-le concis et hiérarchisé, couvrez le projet, la stack, les commandes, les conventions et les interdits, bannissez le flou et les contradictions, versionnez-le et faites-le évoluer. Un fichier bien tenu transforme l'agent en collaborateur parfaitement aligné sur votre projet.