CLAUDE.md (et AGENTS.md) : les meilleures pratiques pour un meilleur code
Par défaut, les agents de code produisent du code générique et peu adapté au contexte d'un projet existant. Pour guider l'IA avec précision, le fichier CLAUDE.md, ou AGENTS.md pour les autres agents de code du marché, joue un rôle clé. Chargé avant chaque nouvelle conversation, il permet de paramétrer les normes de codage, le niveau de qualité attendu, les commandes spécifiques à votre projet ou encore les règles de sécurité à respecter. Comment le structurer ? Que faut-il y mettre ? Réponse.
Un fichier rédigé en langage naturel, court et compréhensible
On le rappelle, CLAUDE.md s'utilise uniquement avec l'agent de code d'Anthropic, Claude Code. Le fichier AGENTS.md, lancé par OpenAI, est de son côté devenu une norme quasi universelle, adoptée par la plupart des agents de code du marché (Codex, Cursor, Aider, Jules, Factory…). Les conseils donnés dans cet article, bien qu'ils s'appliquent prioritairement à CLAUDE.md, restent valables pour AGENTS.md.
Dans sa documentation, Anthropic précise que le fichier CLAUDE.md doit être rédigé entièrement en langage naturel. Il doit rester court, pour éviter de noyer l'agent dans des complexités inutiles, et structuré en sections. Seules les consignes générales applicables à l'ensemble du code de votre projet doivent y figurer. Pour des règles spécifiques à un sous-projet, préférez des skills ou des fichiers CLAUDE.md imbriqués au niveau du sous-dossier concerné. Anthropic recommande par ailleurs d'éviter les consignes trop générales, qui n'apportent rien que Claude n'aurait pu déduire de lui-même en lisant votre code.
Si certaines instructions de votre CLAUDE.md, par exemple des interdictions, ne sont pas respectées par Claude, cela tient généralement à deux causes. La première : le fichier est beaucoup trop long. Retaillez-le pour ne garder que l'essentiel. La seconde : les instructions sont formulées de façon imprécise ou ambiguë. Réécrivez-les. Anthropic conseille également d'ajouter des marqueurs d'emphase pour hiérarchiser les instructions et accentuer les plus critiques. Exemples : “TRES IMPORTANT” avant une règle cruciale, ou “VOUS DEVEZ ABSOLUMENT FAIRE X OU Y”. L'éditeur de Claude recommande enfin de traiter CLAUDE.md comme du code : modifiez, testez dans Claude, itérez. C'est à ce prix que vous obtiendrez le meilleur résultat.
Les instructions à éviter et celles à préciser
Les instructions à bannir
Nous venons de le voir, il faut absolument bannir les instructions imprécises et trop générales. Pas d'instruction que Claude peut comprendre nativement en analysant votre système ou votre base de code. Pas de convention de codage standard qu'il est susceptible de connaître par défaut. Autre exemple : ne détaillez pas le fonctionnement d'une API ou d'un service largement documenté. Pas d'information susceptible de changer en cours de projet non plus, sous peine de voir ces consignes devenir obsolètes, vous les oublierez dans votre CLAUDE.md, mais pas Claude, qui continuera à les appliquer. Pas de tutoriel ni de longue explication de code. Enfin, et c'est notable, car c'était un conseil largement diffusé jusqu'ici, y compris par certains éditeurs eux-mêmes : évitez au maximum les formulations prescriptives purement rhétoriques. Exit les “Rédige du code propre”, “ne fais aucune erreur”, “n'oublie pas de commenter le code”…
Les instructions à ajouter
La liste des instructions à éviter est certes longue. Mais que faut-il alors mettre dans CLAUDE.md ? Ajoutez tout ce que Claude ne peut pas deviner de lui-même. Des commandes bash spécifiques à votre projet ? Ajoutez-les. Des conventions de codage propres à votre entreprise ? Ecrivez-les. Précisez également l'ensemble des conventions de nommage, votre charte graphique, vos règles de revue de code et vos exigences de sécurité internes. L'environnement de développement (versions spécifiques des packages, contraintes matérielles ou réseau…), s'il est complexe ou atypique, peut également être documenté. Mentionnez de même les choix architecturaux de votre projet s'ils s'écartent significativement des pratiques courantes. Enfin, si vous constatez des erreurs récurrentes de Claude sur un même point, ajoutez une instruction dans le CLAUDE.md pour lui indiquer le comportement attendu.
Le fichier CLAUDE.md permet par ailleurs d'inclure des références à des fichiers locaux ou à des ressources en ligne. Vous pouvez ainsi pointer, par exemple, vers la documentation interne de votre projet pour que Claude la consulte avant chaque conversation. Exemple : “regarde dans /var/www/html/monprojet/documentation.md pour comprendre l'ensemble du projet”.
Les conseils du JDN pour votre CLAUDE.md
Une fois les conseils génériques mais très utiles donnés, voici quelques recommandations glanées après près d'un an de pratique de Claude Code. Nous vous conseillons a minima d'ajouter dans votre CLAUDE.md :
- la charte graphique désirée ou déjà appliquée (sans instructions explicites, Claude génère des designs génériques) ;
- les choix de documentation souhaités (pour que Claude complète votre documentation à chaque ajout ou modification de fonctionnalité) ;
- le développement de tests unitaires systématiques pour chaque modification ou ajout de code structurel ;
- le développement de tests d'UX avec Playwright sur les parcours critiques (authentification, paiement, formulaires) ;
- l'audit par sous-agents du code structurel produit, décliné en trois passes : fonctionnelle, qualité et sécurité ;
- pour les projets personnels uniquement : le commit atomique systématique après revue du code, et le push manuel en fin d'unité de travail cohérente sur le dépôt GitHub.
Partant de ces conseils, voici un CLAUDE.md de bonne facture selon nos retours d’expérience :
## Contexte projet [Une à trois phrases : nature du projet, stack, environnement de déploiement.] ## Environnement - Versions imposées : [Node X, Python X, etc.] - Contraintes spécifiques : [VPS, RAM, réseau…] ## Charte graphique - Palette : principale `[#XXXXXX]`, secondaire `[#XXXXXX]`, accent `[#XXXXXX]` - Typographies : titres `[police]`, corps `[police]` TRÈS IMPORTANT : ne jamais générer de design générique. Respecter strictement la charte. ## Documentation interne A chaque ajout ou modification fonctionnelle, mettre à jour la documentation correspondante dans `/docs`. Format : Markdown. ## Tests unitaires VOUS DEVEZ écrire un test unitaire pour chaque ajout ou modification de code structurel. Framework imposé : [Jest / Vitest / Pytest]. ## Tests d'UX VOUS DEVEZ tester l’UX avec Playwright sur l’ensemble des modifications susceptibles d’impacter l’UI. ## Audit par sous-agents Pour tout code structurel produit, déclencher trois passes : 1. Audit fonctionnel : le code fait-il ce qu'il doit ? 2. Audit qualité : lisibilité, duplications, conventions. 3. Revue sécuritaire : vulnérabilités, validation, gestion d'erreurs. ## Git (projets personnels uniquement) Après revue du code, push systématique des modifications sur le dépôt GitHub. ## Problèmes récurrents [A enrichir au fil du projet. Exemples : ne met JAMAIS de tokens d’API en dur dans le code, toujours en env]
Ce modèle ne correspondra pas nécessairement à votre projet : à vous de l'adapter à vos besoins. Comme pour le prompt engineering, le maniement de CLAUDE.md ou AGENTS.md est un processus d'itération continue. Attention également aux changements de version de modèle, que ce soit chez Anthropic ou ailleurs : il est souvent utile de reprendre votre CLAUDE.md à cette occasion. Les modifications de poids entre deux versions font sensiblement varier la façon dont le modèle adhère à vos instructions (ce que l'on appelle la prompt adherence). Ultime conseil enfin : Claude n'est qu'un exécutant, vous devez rester dans la posture du donneur d'ordre. L'IA ne fait qu'appliquer vos consignes ; le context engineering et le prompt engineering sont ce qui différencie un bon développeur avec Claude Code d'un débutant.