CLAUDE.md : des consignes utiles plutôt qu’un fichier interminable

Répéter à chaque session comment tester le projet, quels fichiers éviter et ce qui compte vraiment finit par coûter du temps. Un fichier CLAUDE.md peut conserver ces repères pour Claude Code. Son utilité dépend toutefois davantage de la précision des consignes que du nombre de lignes accumulées.

Écrire ce que le code ne raconte pas

La structure des dossiers et les conventions évidentes sont généralement accessibles dans le projet. Le fichier d’instructions doit surtout expliquer les particularités difficiles à deviner : une intégration fragile, une contrainte métier, une zone volontairement inchangée ou la procédure de validation attendue.

Par exemple, « ne pas modifier le calcul des commissions sans vérifier les cas historiques » est plus utile que « écrire du bon code ». L’instruction devient encore meilleure lorsqu’elle indique où trouver ces cas. L’objectif est de transmettre les décisions, pas de recopier un manuel de programmation.

Garder un noyau court et stable

Une base pratique tient en quelques rubriques : rôle de l’application, commandes de contrôle vérifiées, contraintes importantes et critères de fin de tâche. Ajoutez seulement des consignes qui doivent réellement s’appliquer à la plupart des interventions.

Les bonnes pratiques officielles de Claude Code recommandent un fichier concis et pertinent. Les procédures détaillées peuvent rester dans leur documentation dédiée, avec une indication pour les consulter au bon moment. Cela évite que chaque petite correction transporte tout l’historique technique du projet.

Préférer les instructions vérifiables

« Faire attention à la qualité » laisse beaucoup de place à l’interprétation. « Vérifier le formulaire avec un champ vide, une adresse invalide et une soumission réussie » décrit un résultat observable. De même, demander de préserver les modifications existantes est plus concret qu’une injonction générale à la prudence.

Dans un exemple fictif de portail, une instruction précise que les clients ne doivent jamais consulter les documents d’un autre compte. Elle renvoie à un test d’autorisation et demande d’en rapporter le résultat. Le lien entre exigence métier et contrôle technique devient explicite.

Ne pas confondre consignes et sécurité

CLAUDE.md donne du contexte ; il ne remplace ni les permissions de l’outil ni l’isolation de l’environnement. Une interdiction écrite de toucher à la production ne justifie pas de laisser des accès administrateur disponibles sans nécessité.

N’y stockez pas de mots de passe ou de clés d’API. Indiquez plutôt comment obtenir un environnement de test et quels accès sont requis. Pour reprendre un projet existant avec Claude Code, la première étape reste de comprendre l’état actuel avant toute modification.

Entretenir le fichier comme une petite documentation

Après une erreur répétée, demandez-vous quelle information manquait. Ajoutez une règle courte si elle corrige réellement le problème. Supprimez ou actualisez les consignes obsolètes : un ancien chemin de test peut être plus nuisible qu’une instruction absente.

Une revue périodique peut tenir en trois questions : chaque règle sert-elle encore, peut-elle être vérifiée et existe-t-il une contradiction ? Faites aussi relire le fichier par une personne qui découvre le projet. Si elle ne comprend pas les attentes, un assistant risque également de mal les interpréter.

Le bénéfice attendu n’est pas un agent qui connaît magiquement tout le contexte. C’est une exécution plus régulière, moins de corrections évitables et une meilleure continuité. Cette discipline sert un développement orienté résultat, qu’il soit assisté par l’IA ou non.