Une thèse, trois semaines plus tard
Le 28 avril, j'ai publié sur DEV.to un article qui affirmait quatre choses à propos d'un fichier CLAUDE.md — celui qui contraint l'agent de codage à chaque session — et qui finissait par cette phrase : « le CLAUDE.md n'est jamais fini, et c'est précisément pour ça qu'il marche » (4 incidents, 4 règles : comment mon CLAUDE.md s'est écrit tout seul). C'était une thèse, pas une métaphore. Trois semaines ont passé. Le fichier a ajouté quatre règles sans moi.
Je veux dire par là que je ne les ai pas écrites le jour où je me suis assis pour écrire des règles. Je les ai accueillies les jours où un incident les avait produites, et où je n'avais plus qu'à les noter avant qu'elles s'évaporent dans la marche du projet. La différence, sur le papier, paraît mince. Dans la pratique d'un dev solo qui pilote un agent en production, elle est doctrinale.
Une précision avant d'entrer dans la liste : le titre de cet article a failli dire « cinq règles ». live-snapshot-cache.md a été commité le 25 avril, trois jours avant la publication de l'article-pivot. Elle ne compte pas. Je préfère l'honnêteté du chiffre exact au confort de l'arrondi.
Le bilan, mesuré par git
Pas de récit possible sans la matière brute. Voici ce que git log --diff-filter=A --follow sur .claude/rules/ retourne entre le 28 avril 2026 (publication de l'article-pivot) et le 21 mai 2026 (aujourd'hui) — quatre fichiers nouveaux strictement post-publication.
cache-auth-contract.md — committé le 2 mai. Né d'un audit de dette technique, pas d'un crash en prod. C'est un vendredi en fin d'après-midi. Niran est posé à deux bureaux de là, casque sur les oreilles, une boîte de burgers fermée dans l'angle. Je parcours docs/dette/AUDIT-2026-04-30.md section D-20 sur l'écran de droite, le code sur l'écran de gauche. En relisant getCachedFormateurs, je comprends que le cache unstable_cache est mutualisé entre tous les utilisateurs — session non propagable. Si quelqu'un expose cette fonction via une route API sans guard, c'est une fuite RBAC silencieuse. Je lève la tête pour en parler à Niran. Il retire son casque, écoute, dit « Ah oui, ça mord. » Il remet le casque. La règle est rédigée ce soir-là.
// .claude/rules/cache-auth-contract.md — anti-pattern à interdire
// Faille : pas de guard
export async function GET() {
const formateurs = await getCachedFormateurs()
return Response.json(formateurs)
}
// Correct
export async function GET(req: NextRequest) {
const supabase = await createSupabaseServer()
const { data: { user } } = await supabase.auth.getUser()
if (!user) return new Response('Unauthorized', { status: 401 })
const profile = await getUserProfile(user)
if (!canAccess(profile, 'communication')) return new Response('Forbidden', { status: 403 })
const formateurs = await getCachedFormateurs()
return Response.json(formateurs)
}
inscrit-nom-prenom-required.md — committé le 14 mai. « Hum, ça bug. » — Catherine, deux heures avant. « Mais c'est vite corrigé. » La sonde quotidienne sonde_contacts_orphelins_inscrits a remonté un contact statut='inscrit' avec le prénom vide — l'enfant Loubna, importé d'un Airtable où le prénom vivait dans une colonne séparée non mappée. Le grep qui suit relève seize cas similaires. Ce qui aurait pété l'émargement régulier (Cannot read properties of undefined) tombe dans une CHECK constraint Postgres qui ferme la classe à la racine.
-- .claude/rules/inscrit-nom-prenom-required.md
CHECK (
statut <> 'inscrit'
OR (
nom IS NOT NULL AND nom <> ''
AND prenom IS NOT NULL AND prenom <> ''
)
)
Sans cette CHECK, la règle reste textuelle dans CLAUDE.md et l'import suivant ramènera un dix-septième cas avant la prochaine sonde. Avec, l'INSERT échoue, l'import remonte le problème à la source.
contrat-formation.md — committé le 16 mai, dans le sillage d'ADR-0068. C'est la règle la plus longue, parce que le contrat de formation professionnelle est un Snapshot dont chaque colonne porte sa garantie d'immutabilité. motivation_code, text_version, cases_cochees, pdf_storage_path — figés à la génération, jamais recalculés rétroactivement. Une évolution du contrat n'est jamais une réécriture du Snapshot, c'est un nouvel événement avec une nouvelle text_version. La règle existe parce que l'audit Qualiopi trois ans repose entièrement sur l'immutabilité du PDF généré et de la signature stagiaire associée — un recalcul rétroactif suffirait à rendre le dossier indéfendable.
hybrid-snapshot-live-reset.md — committé le 19 mai, deux jours avant cet article. Avant l'envoi des cinquante-trois SMS de Phase 2 réinscription, un audit pré-flight remonte qu'un token sur les cinquante-trois est consommé — créé en mode test le matin, cliqué, used_at non null. Si le SMS Phase 2 part tel quel, le lien /r/<short_code> renvoie un 410 Gone, le contact perd sa conversion, le ticket support tombe en fin de journée. Le helper generateTokenForContact ressuscitait l'objet (Snapshot d'identité figé) mais oubliait de reset le marker Live d'usage. Fix commit 07ed02d. La règle nomme le pattern, l'oppose à R6 Live / Snapshot / Cache du toolkit dont elle est l'extension projet-spécifique.
La règle qui n'aurait pas pu être écrite avant
Reprenons la deuxième règle, celle de Catherine et de Loubna. Certes, j'aurais pu, le 21 mars 2026 jour de création du premier CLAUDE.md, écrire abstraitement « un contact inscrit doit avoir un nom et un prénom ». Mais cette règle-là n'aurait pas tenu, parce qu'elle aurait été lue, hochée de la tête, et n'aurait jamais produit une CHECK constraint Postgres. La règle qui tient n'est pas l'énoncé moral, c'est le mécanisme matériel — le SQL d'audit qui doit toujours retourner zéro, la migration qui ferme la classe d'incident à la racine.
-- audit DB de cohérence — doit toujours retourner 0
SELECT COUNT(*) FROM contacts
WHERE statut = 'inscrit'
AND ((nom IS NULL OR nom = '') OR (prenom IS NULL OR prenom = ''));
Pour produire ce SQL, il fallait l'incident. Pour rédiger le paragraphe Pourquoi de la règle (qui mentionne par leur nom les seize contacts patchés, l'origine Airtable, la sonde qui a remonté le cas-zéro), il fallait avoir traversé l'élargissement. Aucun « j'écris ma doctrine au jour 1 » ne produit ce niveau de spécificité. La règle n'est pas un précepte rédigé, c'est une cicatrice durcie.
Quatre constats sur la sédimentation
Quatre choses se voient quand on aligne les quatre règles et qu'on les regarde de loin.
Premièrement, aucune des quatre n'aurait pu être écrite avant son incident. Pas parce que je manquais d'imagination le 21 mars, mais parce que la précision matérielle d'une règle utile vient de la rencontre avec un cas concret. Une CHECK constraint, un mapping tunnel vers cases papier DREETS, un reset de used_at dans la même transaction que le SELECT — autant de détails opérants que l'abstraction n'aurait jamais produits.
Deuxièmement, toutes citent un commit, une migration, un session log ou un ADR. Aucune règle flottante. Cette traçabilité, je l'ai apprise dans l'article-pivot, mais je ne l'avais pas mesurée comme une mécanique. Aujourd'hui je la mesure : si la règle ne porte pas son ancrage matériel, elle ne fait pas son travail. L'agent peut la lire, le lecteur humain aussi, et l'un comme l'autre peuvent remonter à l'incident en cas de doute.
Troisièmement, trois sur quatre interdisent un anti-pattern, la quatrième fige un Snapshot. La règle négative domine, exactement comme #20 le prédisait. La règle positive abstraite (utilisez Server Components par défaut) se lit et s'oublie. La règle négative ancrée (un helper getOr* qui retourne un Snapshot sans reset des markers Live introduit silencieusement un lien dead à la prochaine réutilisation) se lit et se retient parce qu'elle porte sa conséquence.
Quatrièmement, et c'est le constat qui change le statut du CLAUDE.md, je n'ai pas inventé ces règles, je les ai accueillies. La distinction paraît rhétorique, elle ne l'est pas. Inventer une règle suppose qu'on l'imagine puis qu'on l'écrit. Accueillir une règle suppose qu'un incident l'a produite et qu'on la note avant qu'elle s'évapore. Dans le premier régime, le fichier est un acte d'écriture solitaire qui prétend à l'exhaustivité. Dans le second, le fichier est un dispositif de sédimentation qui exige de tenir un sas — un cahier ouvert, une session de bilan régulière, un grep git log à intervalle court. Le travail n'est plus d'écrire, c'est d'attraper.
Pourquoi ça marche maintenant
Quoi que nous puissions penser des bonnes pratiques de documentation, un CLAUDE.md rédigé d'un trait au démarrage d'un projet ne tient pas. Il vieillit en deux semaines, il accumule des règles que personne ne convoque, et l'agent finit par le lire mécaniquement sans en charger la mémoire opérante. Le CLAUDE.md qui tient, lui, ne vieillit pas — il sédimente. Chaque incident dépose sa couche, le fichier porte la mémoire matérielle du projet plutôt que sa documentation imaginée.
Trois semaines de pratique post-#20 confirment matériellement la thèse de l'article-pivot. Mais elles ajoutent une nuance que #20 n'avait pas formulée : pour que le fichier sédimente, encore faut-il qu'il y ait quelque chose qui le sollicite. Une sonde drift quotidienne, un audit dette mensuel, un pré-flight d'envoi qui demande « est-ce que les cinquante-trois tokens sont bien actifs ? » — ce sont ces dispositifs qui produisent les incidents qui produisent les règles. Sans eux, le fichier reste sur sa version naïve du jour 1, et le projet dérive en silence.
Coda
Un CLAUDE.md qui ne s'écrit plus est un fichier qui ne fonctionne plus — soit parce que le projet est mort, soit parce que les dispositifs qui sollicitent l'incident ont disparu. Trois semaines après avoir publié la thèse, je peux la vérifier sur la matière brute : quatre règles, quatre incidents, quatre paragraphes Pourquoi qui ne pouvaient être rédigés avant. Le fichier a continué de s'écrire pendant que je faisais autre chose. Mais je sais aussi, maintenant, ce qui le maintient vivant — et ce qui suffirait à le tuer si je le perdais de vue.
Si vous tenez un CLAUDE.md sur un projet où vous pilotez un agent en production, posez-vous la question matérielle : qu'a-t-il ajouté sans vous depuis trois semaines ? Si la réponse est rien, ce n'est probablement pas la doctrine qui s'est tarie. C'est le dispositif qui produit les incidents qui s'est éteint.
Suite de 4 incidents, 4 règles : comment mon CLAUDE.md s'est écrit tout seul (28/04/2026). Mesures à 23 jours d'écart, vérifiées sur .claude/rules/ du repo Rembrandt, 18 fichiers de règles projet actuellement, 4 strictement post-pivot. Pas de Counterpart Toolkit dans cette séquelle — ce sujet vit dans une autre série.
Top comments (0)