Qu'est-ce qu'un fichier CLAUDE.md ? Et comment en écrire un que votre agent respecte vraiment

Si vous utilisez Claude Code depuis plus d'un jour, vous connaissez ce fardeau : à chaque nouvelle session, vous devez réexpliquer votre stack, vos conventions et tout ce qu'il ne cesse de rater. Le fichier CLAUDE.md est là pour en finir avec ça. Il est petit, il est ennuyeux, et c'est pourtant le fichier qui a le plus d'impact dans votre dépôt.

Qu'est-ce qu'un fichier CLAUDE.md ?

Un fichier CLAUDE.md est un fichier Markdown que Claude Code lit automatiquement au début de chaque session. C'est la mémoire persistante d'un projet : les règles, le contexte et les commandes que l'agent doit appliquer à chaque tâche sans qu'on lui demande. Vous l'écrivez une fois, vous le commitez, et il se charge à chaque fois. C'est le seul fichier qui, par défaut, fait partie de chaque conversation.

CLAUDE.mdécrit une fois

Session 1chargé

Session 2chargé

Chaque sessionchargé

Un seul fichier, lu au début de chaque session. C'est pour cela qu'il est crucial de bien le concevoir.

Pourquoi un fichier CLAUDE.md est devenu viral

Plus tôt cette année, un fichier CLAUDE.md unique a fait le tour du web parce qu'il faisait ce que la plupart ne font pas. Il est parti de quelques observations sur les échecs des agents IA (manque de planification, suppositions hâtives, sur-ingénierie de tâches simples, modification de fichiers non demandés) pour les transformer en règles claires que l'agent devait suivre. Ce n'était pas une simple liste des versions de vos frameworks. C'était une description de la façon de se comporter.

C'est là toute l'idée. Par défaut, l'agent a des instincts forts mais aucune retenue. Un fichier CLAUDE.md rempli de détails techniques sur le projet n'y change rien. Un fichier CLAUDE.md axé sur le comportement, oui.

Le robot kitstarter travaillant sur un ordinateur portable avec une feuille unique épinglée à côté de lui, toujours visible — Une seule feuille, épinglée là où l'agent ne peut pas la rater. C'est tout le secret.

Ce que contient réellement un fichier CLAUDE.md

Pensez-y en trois couches, dans cet ordre précis. L'ordre est important, car le modèle accorde le plus d'attention à ce qui se trouve en haut du fichier.

Règles de comportementdemander avant de coder, faire la modification la plus simple possible, prouver que ça tourne, ne pas avoir l'air généré par une IA

Contexte du projetla stack, et uniquement les conventions qui diffèrent des standards

Commandesles commandes de dev, de test et de build qu'il doit réellement exécuter

Le comportement d'abord, le contexte ensuite, les commandes en dernier. La plupart des gens font l'inverse et se demandent pourquoi rien ne change.

Remarquez ce qui ne figure pas ici : un pavé de documentation, toute votre architecture, ou une copie du README. Tout cela ne fait qu'alourdir le fichier, détourne l'attention du modèle des règles importantes, et finit par être ignoré. Un fichier CLAUDE.md n'est pas un espace de stockage de connaissances. C'est là que réside le comportement.

Comment l'écrire pour que votre agent le respecte

Quelques règles simples pour que votre fichier soit efficace plutôt qu'inutile :

Faites court, moins de 200 lignes environ. Les modèles ne suivent fidèlement qu'un nombre limité d'instructions, et le prompt système de Claude Code consomme déjà une partie de ce budget. Un fichier CLAUDE.md de 600 lignes est un fichier de 600 lignes que l'agent va simplement survoler.
Placez les règles prioritaires en premier. Le fichier est lu de haut en bas, et le début bénéficie de l'attention la plus constante.
Ne documentez que ce qui diffère des standards. L'agent sait déjà coder en React. Dites-lui plutôt ce qu'il risque de rater sur votre projet.
Considérez-le comme un document vivant. Chaque fois que vous corrigez l'agent, ajoutez la règle correspondante pour qu'il ne refasse plus la même erreur. Cette seule habitude produit un effet cumulé plus rapide que tout le reste.

Demander avant d'agirUne seule question à la fois, présentée sous forme de choix multiples avec une recommandation, jusqu'à ce que l'objectif soit parfaitement clair.

Aller droit au butAllez directement à l'essentiel. Recommandez une seule option avec sa justification plutôt que d'en lister cinq. Dites clairement quand une idée ne fonctionnera pas.

Éviter les tics d'écriture de l'IAPas de tirets cadratins dans les textes qu'il rédige pour vous, pas d'émojis en guise de titres, pas de dégradés plats en décoration, et des polices correctement chargées.

Signaux d'alerte, s'arrêter et corrigerUn tableau à deux colonnes associant ce que l'agent s'apprête à faire à ce qu'il doit faire à la place. Cela rend les règles faciles à vérifier.

Conventions (à respecter)Uniquement les règles internes qui diffèrent des standards : les couleurs de la marque, les polices, la méthode de validation des captures d'écran.

Où trouver quoiUne carte des fichiers, et quel fichier sert de source unique de vérité. Des pointeurs vers le code, jamais une copie de celui-ci.

Utiliser les commandesLa commande à exécuter pour chaque tâche répétitive, afin d'éviter que l'agent n'improvise son propre workflow.

Sept sections réelles issues des deux fichiers AGENTS.md de ce dépôt, le kit que nous fournissons et le guide de ce site. Même fichier, nom compatible multi-outils. Le comportement occupe les quatre premières.

Placez les règles du projet dans ./CLAUDE.md à la racine du dépôt pour que votre équipe les partage via git. Placez vos préférences personnelles dans ~/.claude/CLAUDE.md pour qu'elles vous suivent sur tous vos projets.

Le raccourci : le comportement, clé en main

Rédiger de bonnes règles de comportement est un art en soi, et trouver la formulation exacte pour qu'un agent obéisse vraiment demande de nombreux essais. C'est tout le pari de kitstarter : un fichier CLAUDE.md et un ensemble de commandes pour que Claude Code, Codex et Antigravity demandent avant de coder, restent concis et évitent le style typique de l'IA, rédigées là où l'agent les lira. Vous pouvez tout à fait écrire le vôtre. Commencez par les quatre règles de comportement ci-dessus, restez sous la barre des 200 lignes, et ajoutez une règle à chaque fois qu'il dévie. Si vous préférez utiliser des formulations éprouvées, nous les avons déjà préparées pour vous.

Questions fréquentes

Où va le fichier CLAUDE.md ? Les règles du projet vont dans ./CLAUDE.md à la racine du dépôt, partagées avec votre équipe via git. Vos préférences personnelles vont dans ~/.claude/CLAUDE.md. Les deux se chargent automatiquement.

Quelle longueur doit-il faire ? Moins de 200 lignes environ. Au-delà, le modèle commence à survoler le texte et vos règles importantes n'attirent plus son attention.

Quelle est la différence entre CLAUDE.md et AGENTS.md ? Même idée, nom de fichier différent. AGENTS.md est la convention multi-outils lue par plusieurs agents ; CLAUDE.md est celle de Claude Code. De nombreuses équipes n'en gardent qu'un seul et configurent l'autre pour qu'il pointe dessus. Consultez notre guide des bonnes pratiques.

Évitez les essais et erreurs

kitstarter fournit le fichier CLAUDE.md et les commandes nécessaires pour que votre agent demande d'abord, reste concis et n'ait pas l'air d'une IA.

Get the kit · $20 $29 Lire la documentation