CLAUDE.md : le mien, commenté ligne par ligne.

01La réponse courte

Un CLAUDE.md, c'est la mémoire de travail permanente de ton agent. Claude Code charge ~/.claude/CLAUDE.md (tes règles valables partout) puis le CLAUDE.md à la racine du projet (le contexte de ce projet). Tout ce qui y est écrit est relu à chaque session, sans que tu le répètes.

La commande /init en génère un premier jet à partir du code. C'est un bon départ et un mauvais résultat final : il décrit le projet, il ne dit rien de ta façon de travailler ni des erreurs que tu ne veux plus voir.

02Mon CLAUDE.md global, extrait

Il est écrit comme un ordre de mission, en français, avec des titres en capitales. Ce n'est pas une coquetterie : un agent suit mieux une règle courte et tranchée qu'un paragraphe nuancé. Voici les passages qui comptent, noms retirés.

1. LA MISSION SE DIT UNE FOIS
Je donne l'ordre 1 seule fois. Tu l'as compris, tu l'exécutes.
Si tu as VRAIMENT un doute bloquant → 1 question fermée (A ou B).
Si je te corrige une fois sur un pattern → c'est gravé.

4. QUALITÉ AU PREMIER COUP
Avant de dire "c'est fait" :
→ Tu as VÉRIFIÉ (build, test, run, preview, output réel)
→ Tu as relu ton output comme un reviewer hostile
→ Tu as supprimé le code mort que tu viens de créer

5. ERREUR DÉTECTÉE = CORRECTION IMMÉDIATE
→ Cause racine, pas bypass. Pas de --no-verify.
→ Pas de try/catch qui mange l'erreur.

7. FORMAT DE RAPPORT (fin de tâche)
• STATUS : FAIT / PARTIEL / BLOQUÉ
• PREUVE : commit / fichier / URL / output testé
• NEXT : 1 ligne

Règle 1 · La mission se dit une fois

Sans elle, l'agent te repose la question sous trois formes avant d'agir. Avec elle, il agit, et il ne revient vers toi que si un choix est réellement bloquant, en te proposant deux options. La phrase « si je te corrige une fois, c'est gravé » est la plus rentable du fichier : elle le pousse à écrire la correction dans sa mémoire au lieu de l'oublier à la session suivante.

Règle 4 · Vérifier avant de dire « fait »

Un agent dit « c'est fait » quand il a écrit le code, pas quand le code marche. Cette règle déplace la ligne d'arrivée : fait, c'est quand il a montré une sortie réelle. Sur un site, ça veut dire une requête sur le domaine public, pas sur la preview.

Règle 5 · Pas de try/catch qui mange l'erreur

Ça vise une panne précise : un formulaire qui affichait « merci » alors que l'outil email était appelé sans clé, et que cet échec ne remontait nulle part. 174 inscrits n'ont jamais reçu un email en quatre mois. Depuis, une erreur se journalise et remonte. Toujours.

Règle 7 · Le rapport en trois lignes

Statut, preuve, prochaine action. Je pilote plusieurs sites : je lis des dizaines de rapports par semaine. Trois lignes avec une preuve, c'est lisible. Trois écrans de résumé, non.

03Le CLAUDE.md de projet : les pièges, pas la doc

Le fichier de projet ne sert pas à décrire l'architecture, l'agent la lit dans le code. Il sert à écrire ce que le code ne dit pas : la commande de déploiement exacte, la base utilisée, et surtout les pièges déjà rencontrés. Voilà un extrait réel, celui de ce site :

DÉPLOIEMENT (règle gravée, une erreur passée a mis tout le site en 404)
- Le site est en HTML statique dans src/ (source de vérité).
- Seul déploiement autorisé :
  cd src && vercel --prod
- Jamais depuis la racine du dépôt.
- Les previews sont derrière une authentification :
  vérifier toujours sur le site public après déploiement.

Ces quatre lignes existent parce qu'un déploiement lancé depuis la racine a servi les pages sous /src/… au lieu de /…. Résultat : toutes les URL canoniques en 404. L'agent avait « réussi » son déploiement. Le site, lui, était mort.

04Les 5 règles nées de pannes réelles

Si tu ne retiens qu'une partie de cet article, garde celle-ci. Chaque règle a coûté quelque chose avant d'être écrite.

Remarque la forme : une règle courte, et la raison juste à côté. Sans la raison, l'agent applique la règle à la lettre et la contourne au premier cas limite. Avec la raison, il comprend le cas limite.

05La mémoire : un index, pas un roman

Le CLAUDE.md porte les règles. La mémoire porte les faits : décisions prises, chiffres, comptes, pièges. Je la tiens sous forme d'un fichier MEMORY.md qui n'est qu'un index, une ligne par sujet, avec un lien vers une note détaillée.

Pourquoi un index ? Parce que tout ce qui est chargé à chaque session coûte du contexte. Un index de cent lignes se lit d'un coup d'œil ; l'agent n'ouvre la note détaillée que si le sujet le concerne. Ma règle de tri : si une information sert à chaque session, elle va dans le CLAUDE.md. Si elle sert parfois, elle va dans une note. Si elle sert à une tâche précise, elle devient un skill.

06CLAUDE.md ou AGENTS.md ?

Si tu jongles entre plusieurs outils, écris les règles communes dans AGENTS.md et ajoute la ligne @AGENTS.md dans ton CLAUDE.md. Une seule source, pas deux fichiers qui divergent.

07Ce que je n'y mets plus

• Des secrets. Jamais de clé ni de mot de passe dans un fichier que l'agent relit et peut citer. Les clés vivent dans les variables d'environnement.
• La description du code. L'agent la lit dans le code, plus à jour que n'importe quel résumé.
• Des procédures longues. Une procédure de dix étapes utile une fois par mois devient un skill, chargé seulement quand il sert.
• Des souhaits vagues. « Écris du code propre » ne change rien. « Supprime le code mort que tu viens de créer » change quelque chose.