Idea principale

Un file CLAUDE.md posto alla radice di un progetto dice all'agente come lavorare: le convenzioni del repo, i formati ammessi, ciò che non deve mai fare. Lo si scambia volentieri per la memoria del progetto, visto che è lì, che persiste e che l'agente lo legge ogni volta.

Non lo è. Questo file enuncia ciò che deve valere sempre; non dice ciò che è accaduto. Non contiene né il bug incontrato venerdì, né la correzione provata e poi abbandonata, né la decisione presa durante la sessione perché il primo approccio non reggeva. Niente di ciò che è successo vi si deposita, e niente vi invecchia.

Due oggetti, due regimi di scrittura. La regola si scrive una volta, a freddo, e vale finché non la si cambia. Il diario si scrive man mano, a caldo, ed è vero solo per il giorno in cui è datato. Voler tenere entrambi in un solo file produce o regole inquinate da aneddoti, o un diario che si crede una dottrina.

Perché è importante

È la mancanza che nessuno vede, perché qualcosa occupa già il posto. Un progetto che ha il suo file di regole crede di avere ciò che serve, e si ritrova comunque a rispiegare ogni lunedì ciò che è stato fatto la settimana precedente.

La diagnosi è utile anche fuori dal caso di un agente: una documentazione di team, una carta di principi, un repertorio di convenzioni soffrono esattamente dello stesso punto cieco.

Sfumature e limiti

Il confine si sposta. Una decisione presa durante una sessione e confermata tre volte diventa una regola — ed è proprio il diario che permette di accorgersene.

E un file di regole tenuto male contiene sempre tracce di storia: divieti scritti dopo un incidente, che nessuno sa più datare.

Domande aperte

• Chi decide di far risalire una decisione fino alle regole, quando il diario è tenuto dall'agente e le regole dall'umano?