CLAUDE.md come rete neurale: come allenarlo

Il CLAUDE.md di uno dei nostri progetti interni ha superato le 900 righe. Metà scritte per un incidente capitato una volta sola, mai più ripetuto. Nessuno lo rilegge davvero, ma ogni sessione dell’agente lo carica per intero e lo paga in token, ogni singola volta.

La risposta più utile che abbiamo trovato: trattare il CLAUDE.md come una rete neurale, non come un diario. Ogni sessione è una forward pass che non lo tocca. Il divario tra quello che volevi e quello che è successo è la loss function. Aggiornare il file diventa un backward pass, fatto a batch, mai su un singolo aneddoto, dentro un budget di token fisso.

Le quattro patologie di ogni CLAUDE.md o AGENTS.md

L’osservazione di partenza arriva da Kun Chen, ex ingegnere L8 in Meta, Microsoft e Atlassian, che ha reso pubblico il metodo dopo averlo applicato ai propri repository. Qualsiasi file di memoria più vecchio di qualche mese cade in uno di quattro stati.

• Vuoto: esiste solo perché un tool lo ha creato. L’agente non trova nulla di utile e ridériva le stesse cose a ogni sessione.
• Gonfio: ogni errore ha generato una regola incollata. Dopo un anno sono 900 righe, e ognuna viene pagata a ogni sessione, per sempre.
• Obsoleto: metà delle regole descrive un sistema sostituito mesi fa. L’agente le segue comunque, oppure impara a ignorarle, il che è lo stesso problema.
• Divergente: AGENTS.md dice una cosa, CLAUDE.md un’altra, e l’agente riceve istruzioni diverse a seconda dello strumento usato.

La radice comune è che il file viene editato in modo transazionale, su base aneddotica, ed è molto più facile aggiungere una riga che consolidare e potare quelle esistenti. Nel nostro caso in Martes AI non l’abbiamo ancora applicato ai repository principali, solo a un prodotto interno come Mareply, ma il principio ha già cambiato come guardiamo ai file di configurazione dei nostri agenti e a come impostiamo i team di agenti descritti nel nostro articolo sull’ottimizzazione dei team AI.

Come allenare un CLAUDE.md: le cinque regole

Fatta la diagnosi, la disciplina proposta ha cinque punti, ognuno mappato su un passaggio dell’allenamento di una rete neurale.

L’evidenza viene dalle trascrizioni, non dal ricordo. Ogni sessione dell’agente lascia un log su disco, sia con Claude Code sia con Codex, Cursor o altri harness. Quel log dice cosa è stato chiesto, quale regola è stata seguita, quale ha fatto inciampare l’agente. Trattare ogni riga del CLAUDE.md come un’unità indirizzabile e chiedersi, per ciascuna, in quali sessioni ha contato davvero.

Si aggiorna a batch, mai su un singolo episodio. Una sessione andata male può dipendere da cause casuali. Solo quando lo stesso gap ricompare in almeno due sessioni diverse diventa un pattern degno di una regola. Questo singolo vincolo elimina la maggior parte del rumore, perché la maggioranza delle righe inutili nasce da un episodio che ha infastidito una volta e non si è mai più ripetuto.

Piccoli passi, non riscritture. Un pugno di modifiche per run, non oltre cinque: un’aggiunta, una rimozione, una riscrittura o un’estrazione verso una skill separata. Un passo troppo grande su un file di memoria equivale a ripartire da zero, e si perde tutto ciò che stava già funzionando.

Il budget è non negoziabile, la skill è la valvola di sfogo. Fissare un tetto di token per il file sempre caricato, ad esempio 5.000, e trattarlo come vincolo reale: ogni aggiunta vicino al limite deve nominare cosa viene tolto o estratto per pagarla. Le regole ampie o critiche per la sicurezza restano nel file. Quelle di nicchia con un trigger riconoscibile diventano una skill a parte, caricata solo quando serve.

Nessuna modifica scritta senza revisione umana. Ogni proposta arriva con la diff e l’evidenza a supporto, e la conferma resta sempre a chi possiede il repository. È lo stesso principio del human-in-the-loop che vale per qualunque automazione con un minimo di autonomia: il giusto controllo, non tutto il controllo.

Le alternative per allenare CLAUDE.md nel 2026

Il metodo si può applicare a mano, rileggendo le trascrizioni una a una. È rigoroso, ma richiede tempo: trovarle, leggere megabyte di rumore di tool call, tenere oneste le citazioni, contare i token. Per questo Kun Chen ha costruito backpass, un tool open source sotto licenza MIT che automatizza esattamente questi passaggi.

I limiti dell’analogia con la rete neurale

L’analogia regge fino a un certo punto, e vale la pena dirlo chiaramente invece di venderla come soluzione definitiva. Una rete neurale calcola il gradiente in modo automatico e deterministico. Qui il “gradiente” lo stima un modello linguistico che legge trascrizioni testuali, e resta soggetto a interpretazione, anche quando ogni proposta richiede una citazione verbatim come prova.

C’è poi un problema di dati che gli esaltati del metodo tendono a saltare: funziona bene quando le trascrizioni restano sulla stessa macchina, in una cartella locale. In team con più sviluppatori, agenti cloud o sessioni condivise, le trascrizioni si frammentano su più account e strumenti, e il segnale diventa parziale. Vale anche una domanda etica non banale: quelle trascrizioni contengono spesso frammenti di codice proprietario o dati di clienti. Prima di automatizzare la lettura, va chiarito dove finiscono quei log e chi può accedervi.

Resta comunque una differenza netta rispetto al pattern attuale, quello di scrivere “a vibes” o lasciare che sia l’agente stesso a riscriversi le istruzioni senza criterio. Se nessuno rilegge davvero un file da 900 righe, ha più senso trattarlo come quello che di fatto è già diventato: un modello da allenare con disciplina, non un documento da scrivere una volta e dimenticare.

Vale la pena chiedersi, la prossima volta che si aggiunge una riga al proprio CLAUDE.md o a una skill: è la seconda volta che vedo questo problema, o solo la prima? La differenza tra le due risposte è quasi sempre la differenza tra una regola utile e una riga che nessuno toglierà mai più.