CLAUDE.md : le contexte qu'on arrête enfin de réexpliquer à chaque session

Les premières semaines, je retapais les mêmes précisions au début de chaque session : le format de mes commits, le port de dev du projet, l'interdiction du gradient indigo/violet par défaut. Rien de compliqué à expliquer, mais tout à réexpliquer, session après session, comme si l'agent n'avait jamais travaillé sur ce repo la veille. CLAUDE.md règle exactement ce problème : un fichier markdown, chargé automatiquement au démarrage de Claude Code, qui tient lieu de mémoire persistante du projet.

Ce que ça remplace, concrètement#

Sur une équipe humaine, ce rôle est tenu par l'onboarding et la documentation interne : les conventions ne sont pas réexpliquées à chaque nouvelle tâche, elles sont écrites une fois et consultées au besoin. CLAUDE.md fait la même chose pour un agent, à un détail près : il n'est pas consulté « au besoin », il est chargé systématiquement, à chaque session, avant la première réponse. C'est ce qui le distingue d'un skill, chargé seulement si le modèle juge que le contexte le justifie : CLAUDE.md n'a pas ce filtre, il est toujours là.

Un fichier, ou un fichier qui en importe d'autres#

Le CLAUDE.md de ce blog tient en une ligne :

@AGENTS.md

Tout le contenu réel vit dans AGENTS.md, importé via cette syntaxe. Ce repo tourne sur une version de Next.js volontairement en avance sur mes connaissances d'entraînement, et l'AGENTS.md le dit sans détour :

# This is NOT the Next.js you know
 
This version has breaking changes, APIs, conventions and file structure
may all differ from your training data. Read the relevant guide in
`node_modules/next/dist/docs/` before writing any code. Heed deprecation
notices.

Cette instruction m'a évité plus d'un bug bête : un agent qui code depuis ses connaissances d'entraînement sur une API qui a changé produit du code qui compile souvent, mais qui ne fait pas ce qu'on croit. Le forcer à vérifier la doc locale avant d'écrire, plutôt que de lui faire confiance sur sa mémoire, change directement la fiabilité du résultat.

Ce qui mérite d'y être, ce qui n'y a pas sa place#

Ce qui mérite d'y être : les conventions non dérivables du code lui-même (le format des commits, le port de dev, l'interdiction d'un pattern visuel précis), les contraintes du projet (une version de framework en avance sur l'entraînement du modèle, une règle métier qui n'apparaît nulle part dans le code), et les préférences de collaboration qui ne changent pas d'une tâche à l'autre.

Ce qui n'y a pas sa place : l'architecture du projet (elle se lit en explorant les fichiers), l'historique des décisions (le message de commit suffit), et tout ce qui est déjà correctement documenté ailleurs et qu'un CLAUDE.md ne ferait que dupliquer, avec le risque de désynchronisation que ça implique.

AGENTS.md, un standard qui dépasse Claude Code#

Passer par @AGENTS.md plutôt que d'écrire directement dans CLAUDE.md n'est pas qu'une question d'organisation. AGENTS.md est un format adopté par plusieurs outils agentiques, pas seulement Claude Code : écrire les conventions du projet dans ce fichier les rend lisibles par n'importe quel agent qui respecte la convention, sans dupliquer le contenu pour chaque outil. CLAUDE.md reste la porte d'entrée spécifique à Claude Code, mais le contenu qui compte vraiment vit dans un fichier qui ne dépend d'aucun outil en particulier.

Le tester comme n'importe quelle doc#

Un CLAUDE.md, comme un skill mal écrit, peut exister sans être vraiment suivi. La différence avec un skill, c'est qu'il est chargé à coup sûr : le risque n'est donc pas qu'il ne se déclenche pas, mais qu'il soit ignoré en pratique parce qu'une règle est mal formulée, contradictoire avec une autre, ou noyée dans trop de texte pour rester prioritaire. La méthode que j'applique est la même que pour un skill : écrire une règle, vérifier sur la session suivante qu'elle est vraiment appliquée, et la reformuler si ce n'est pas le cas plutôt que de supposer qu'elle l'est.

Ce que ça change au quotidien#

Le gain n'est pas seulement le temps gagné à ne plus retaper les mêmes consignes. C'est la cohérence : sans CLAUDE.md, la qualité d'une session dépend de ce que je pense à préciser au bon moment. Avec, elle dépend d'un fichier versionné, relu et corrigé au fil du temps, qui ne dépend plus de ma mémoire du jour. La règle tient en une phrase : tout ce que je répéterais identiquement sur n'importe quelle tâche de ce projet appartient à CLAUDE.md, pas à mon prompt du moment.