Idée principale

Un fichier CLAUDE.md posé à la racine d'un projet dit à l'agent comment travailler : les conventions du dépôt, les formats autorisés, ce qu'il ne doit jamais faire. On le prend volontiers pour la mémoire du projet, puisqu'il est là, qu'il persiste, et que l'agent le lit à chaque fois.

Il n'en est pas une. Ce fichier énonce ce qui doit toujours valoir ; il ne dit pas ce qui a eu lieu. Il ne contient ni le bug rencontré vendredi, ni le correctif essayé puis abandonné, ni la décision prise en cours de session parce que la première approche ne tenait pas. Rien de ce qui s'est produit ne s'y dépose, et rien n'y vieillit.

Deux objets, deux régimes d'écriture. La règle se rédige une fois, à froid, et vaut jusqu'à ce qu'on la change. Le journal s'écrit au fil de l'eau, à chaud, et n'est vrai que du jour où il est daté. Vouloir tenir les deux dans un seul fichier donne soit des règles polluées d'anecdotes, soit un journal qui se prend pour une doctrine.

Pourquoi c'est important

C'est le manque que personne ne voit, parce que quelque chose occupe déjà la place. Un projet qui a son fichier de règles se croit outillé, et se retrouve pourtant à ré-expliquer chaque lundi ce qui a été fait la semaine précédente.

Le diagnostic est utile ailleurs qu'avec un agent : une documentation d'équipe, une charte, un référentiel de conventions souffrent exactement du même angle mort.

Nuances et limites

La frontière bouge. Une décision prise en cours de session et confirmée trois fois devient une règle — le journal est précisément ce qui permet de s'en apercevoir.

Et un fichier de règles mal tenu contient toujours des traces d'histoire : des interdits écrits après un incident, que plus personne ne sait dater.

Questions ouvertes

• À partir de quand une décision consignée dans un journal doit-elle remonter dans les règles ?