Come si scrive un CLAUDE.md che funziona

La trappola: scriverci dentro tutto

Appena capito a cosa serve, la tentazione è irresistibile: scriverci dentro tutto. Come lavori, cosa ti piace, tutte le eccezioni, i casi particolari, la storia del progetto.

Ed è qui che arriva il fatto controintuitivo, quello che vale l'intera lezione: un file più lungo non viene seguito meglio. Viene seguito peggio.

Due motivi, e li conosci già tutti e due. Il primo: quel file entra nello spazio di lavoro a ogni sessione, quindi più è lungo, più occupa. Il secondo, più importante: in mezzo a duecento righe, le tre che contano davvero pesano meno. Il segnale si diluisce nel rumore — esattamente come in una conversazione troppo lunga.

Il riferimento pratico: sotto le duecento righe. Se stai superando, non hai bisogno di più spazio: hai bisogno di tagliare.

Scrivi cose verificabili, non desideri

La differenza fra un'istruzione che funziona e una che viene ignorata quasi sempre è questa: si può controllare se è stata rispettata?

• "Tieni i file organizzati" → "I contratti nuovi vanno in Documenti/Contratti/anno, con il nome cliente-data"

• "Scrivi in modo professionale" → "Nelle email: niente punti esclamativi, chiusura sempre con nome e ruolo"

• "Fai attenzione ai numeri" → "Ogni totale va ricontrollato sommando di nuovo prima di scriverlo"

Le prime sono desideri: non c'è modo di sapere se sono stati rispettati, quindi non c'è modo di rispettarli. Le seconde sono controlli.

Cosa ci va e cosa no

• Ci va: com'è organizzata la tua roba, le convenzioni di nome, le cose da fare sempre, i comandi che usi, come si chiamano le cose nel tuo mondo.

• Non ci va: le procedure lunghe passo-passo. Occupano spazio in ogni sessione anche quando non servono. Per quelle c'è uno strumento apposta, ed è il capitolo subito dopo questo.

• Non ci va nemmeno quello che si deduce guardando la cartella: se si vede da solo, scriverlo è spazio buttato.

Quando si aggiunge una riga

Non prevedendo. Il file cresce dall'esperienza, e il segnale è preciso:

• hai corretto la stessa cosa per la seconda volta;

• ti sei risentito scrivere in chat una frase che avevi già scritto la sessione prima;

• una persona nuova, per lavorare al posto tuo, avrebbe avuto bisogno di sapere quella cosa lì.

Se una di queste è vera, quella riga vale il suo spazio. Altrimenti aspetta.

La manutenzione vera è togliere

C'è un'abitudine che distingue chi usa bene questi strumenti: ogni tanto toglie. Prova a cancellare una regola e guarda se sbaglia di nuovo. Se non succede niente, quella riga non ti serviva — e la stavi pagando a ogni sessione.

Due segnali che è ora di fare pulizia: istruzioni che si contraddicono (se due righe dicono il contrario, ne seguirà una a caso) e istruzioni scadute, che parlano di come lavoravi sei mesi fa.

E adesso

Ho detto due volte che le cose "occupano spazio", e ho fatto finta che tu sappia di che spazio parlo. Nella prossima lezione lo guardiamo per davvero: il context window, cioè quanto riesce a tenere sul tavolo tutto insieme.

Hai capito?

Due minuti, nessun voto. Provare a rispondere — anche sbagliando — fissa i concetti molto più che rileggere. Se non ti va, salta pure: la lezione si completa lo stesso.

1Un CLAUDE.md lunghissimo che spiega tutto: cosa succede?

Claude segue meglio, perché ha più informazioni Occupa più spazio e le istruzioni vengono seguite peggio, non meglio Non cambia niente, viene letto uguale

2Quale di queste due istruzioni è scritta bene?

Tieni i file organizzati e ordinati I contratti nuovi vanno in Documenti/Contratti/<anno>, con il nome cliente-data

3Quando conviene aggiungere una riga al CLAUDE.md?

Prima di cominciare, prevedendo tutto quello che potrebbe servire Quando ti accorgi di aver corretto la stessa cosa per la seconda volta