CLAUDE.md dopo Opus 5: perché le istruzioni lunghe ora ostacolano Claude

Informazioni su come lavorare con Ailoot sono disponibili nella documentazione.

Cosa è cambiato in Claude dopo l’uscita di Opus 5?#

Opus 5 è uscito il 24 luglio 2026 ed è diventato subito il modello predefinito in Claude Code. Il modello in sé—il prezzo, i benchmark e le modalità di effort—è trattato in dettaglio in una guida separata, “Dovresti passare a Claude Opus 5?”. Questo articolo parla di altro: l’uscita del modello ha cambiato anche il modo di comunicare con lui in modo efficace.

Anthropic ha pubblicato un’analisi sul blog di Claude. Il punto principale è questo:

L’espressione chiave è “imporre troppi vincoli”. Quando i modelli erano più deboli, avevano bisogno di istruzioni di supporto: fai questo, non fare quello, ecco un esempio, ripetiamolo ancora una volta. Opus 5 non ha più bisogno di quelle istruzioni e, peggio ancora, possono cominciare a ostacolarlo. Anthropic enuncia semplicemente il nuovo principio: lascia che Claude usi il proprio giudizio.

Che cosa significa in pratica per te?

• Il tuo CLAUDE.md è lo stesso tipo di prompt di sistema, ma per il tuo progetto. Se Anthropic ha ridotto il proprio dell’80 percento, probabilmente anche il tuo è troppo lungo.
• Gli elenchi lunghi di regole non garantiscono più che vengano seguite. Al contrario, più righe ci sono, meno attentamente il modello le segue (più avanti trovi i dati della documentazione).
• Sono comparsi nuovi meccanismi—la memoria automatica e le skill—che si occupano di parte del lavoro che prima dovevi specificare a mano in CLAUDE.md.

Il punto principale è che il lavoro più importante avviene prima del prompt: in ciò che inserisci nel contesto del modello prima della prima richiesta. L’aggiornamento a Opus 5 è, in sostanza, la conferma ufficiale di Anthropic della stessa idea. Questa volta, però, include dati concreti e nuovi strumenti. Li esaminerò uno alla volta.

Perché un CLAUDE.md lungo ora è d’intralcio?#

Ecco come funziona. CLAUDE.md è un file di regole che Claude legge all’inizio di ogni sessione. Una guida separata, “Come configurare CLAUDE.md”, spiega come crearne uno da zero; questo articolo tratta il procedimento inverso: cosa rimuovere adesso. Tutto ciò che scrivi lì entra nel contesto prima della tua prima richiesta e vi resta per tutta la conversazione. Il contesto non è infinito e ogni riga di regole in più occupa spazio che potrebbe essere dedicato alla tua attività.

La documentazione di Claude Code lo dice chiaramente:

Il secondo punto conta più del primo: i file lunghi riducono la capacità di seguire le istruzioni. Il modello comincia a prestare meno attenzione. È una trappola in cui cade quasi ogni principiante. La logica sembra inattaccabile: voglio che Claude mi ascolti, quindi scriverò più regole. In pratica accade il contrario. Più lungo è l’elenco, più l’attenzione del modello si disperde e più spesso salta una regola.

Ecco come è cambiato l’approccio:

C’è anche un secondo problema: le contraddizioni. Man mano che il file cresce, finisce quasi inevitabilmente per accumulare regole in conflitto tra loro. In un punto si dice “scrivi sempre test”, in un altro “non toccare la cartella dei test”. La documentazione avverte che, se due regole si contraddicono, Claude può scegliere a caso l’una o l’altra. In altre parole, un file troppo lungo rende il comportamento del modello meno prevedibile.

Una regola semplice: CLAUDE.md è una breve nota su ciò che Claude non può dedurre autonomamente. Tutto il resto occupa soltanto la sua attenzione.

Cosa dovresti tenere in CLAUDE.md e cosa rimuovere?#

La documentazione offre un criterio chiaro per decidere se una regola merita un posto in CLAUDE.md. Aggiungila se:

1. Claude ha commesso lo stesso errore per la seconda volta.
2. Un controllo del codice ha rilevato qualcosa che il modello avrebbe dovuto sapere del progetto.
3. Stai scrivendo la stessa correzione nella chat per la seconda volta.
4. Una nuova persona del team avrebbe bisogno dello stesso contesto per evitare di danneggiare il progetto.

Il principio generale è conservare le insidie specifiche del progetto e rimuovere ciò che è ovvio. Claude Code include anche un controllo integrato, claude doctor, che suggerisce di ripulire un CLAUDE.md troppo lungo. Rimuove i dettagli che il modello può dedurre dal codebase—struttura delle cartelle, elenco delle dipendenze, panoramica dell’architettura—e conserva le insidie, le motivazioni e le convenzioni diverse da quelle predefinite.

La seconda regola importante è la specificità. Le formulazioni vaghe non funzionano. Confronta:

La differenza è semplice. Il modello può interpretare “formattalo correttamente” come preferisce. “Usa un’indentazione di 2 spazi” si può verificare senza ambiguità. Ogni regola in CLAUDE.md dovrebbe essere verificabile e osservabile: si può stabilire se è stata seguita oppure no.

E, terzo, elimina ciò che è ovvio. Se scrivi “scrivi codice pulito” o “segui le best practice” in CLAUDE.md, è rumore. Il modello lo sa già, e quella riga occupa spazio e disperde la sua attenzione. Anthropic sconsiglia esplicitamente di sprecare contesto con cose ovvie.

Dove dovresti spostare le regole che non trovano posto in CLAUDE.md?#

È qui che entra in gioco lo strumento più sottovalutato. Se prima tutte le istruzioni dovevano restare in CLAUDE.md, ora le procedure lunghe hanno una sede propria: le skill. Una guida separata, “Come scegliere le skill di Claude Code”, spiega come scegliere quelle giuste senza aggiungerne troppe.

La differenza è fondamentale. CLAUDE.md viene caricato interamente all’inizio di ogni sessione. Una skill no. La documentazione lo spiega così:

Questo si chiama divulgazione progressiva: caricare le informazioni quando servono. L’idea è fornire il contesto al modello in parti, al momento giusto. Anthropic ha spostato nelle skill le istruzioni dettagliate, per esempio quelle per la revisione del codice, e le ha rimosse dal prompt di sistema.

Il criterio per spostare qualcosa in una skill è semplice: una sezione di CLAUDE.md è passata da fatto a procedura. Una nota di una riga, “Le build si eseguono con npm run build”, è un fatto e appartiene a CLAUDE.md. Dieci passaggi su “come pubblichiamo il progetto” sono una procedura e appartengono a una skill.

Un principio pratico: affida a una skill tutto ciò che fai più di un paio di volte. Spiega una volta come prepari, per esempio, un report settimanale per un cliente, trasforma la spiegazione in una skill e non dovrai rispiegarla. La skill resta lì senza occupare contesto e la puoi richiamare per nome con un comando come /otchet.

Ecco cosa può essere utile spostare nelle skill:

• Procedure in più passaggi (pubblicazione, compilazione di un report, controlli pre-release).
• Istruzioni lunghe che servono raramente, ma che devono essere caricate per intero.
• Qualsiasi cosa tu abbia copiato da una chat all’altra per la seconda o terza volta.

C’è anche un’opzione intermedia: regole specifiche per cartella. Se un’istruzione è pertinente solo a una parte del progetto, puoi inserirla in .claude/rules/ e collegarla ai file pertinenti. Verrà caricata solo quando Claude lavora con quei file, invece di restare sempre nel contesto.

Cos’è la memoria automatica e perché usarla nel 2026?#

Il secondo nuovo meccanismo che alleggerisce CLAUDE.md è la memoria automatica. L’idea è che ora Claude ricordi non solo ciò che hai scritto, ma anche ciò che ha notato autonomamente. Una guida separata, “Memoria di Claude e CLAUDE.md a confronto”, spiega in cosa differiscono i relativi meccanismi.

Le differenze tra i due tipi di memoria:

Ecco come funziona: mentre lavora alla tua attività, Claude nota dettagli utili—quale comando esegue la build, dove il debugging si è arenato, cosa gli hai chiesto di fare diversamente—e li salva nei propri appunti. Li recupera nella sessione successiva. Importante: salva le informazioni in modo selettivo e conserva solo quelle che ritiene utili in futuro.

Gli appunti si trovano in una cartella separata per ogni progetto, con un file indice chiamato MEMORY.md. Puoi consultarli e modificarli con il comando /memory. Sono normali file di testo, quindi puoi leggerli, modificarli o eliminarli in qualsiasi momento.

Cosa cambia in pratica per te: ora Claude registra autonomamente alcune delle cose che prima aggiungevi tu a CLAUDE.md dopo ogni errore. Così il file delle regole diventa ancora più breve, e questo è un bene.

Perché Opus 5 discute le tue istruzioni?#

C’è anche il rovescio della medaglia.

Un modello a cui è consentito usare il proprio giudizio a volte dissentirà per definizione da un comando rigido se nel contesto trova un’opzione migliore.

Ecco cosa significa per te se sei passato a Opus 5 e qualcosa non va:

1. Ricontrolla le vecchie skill e i vecchi plugin. Le configurazioni create per i modelli precedenti possono entrare in conflitto con la nuova logica. Vale la pena verificare di nuovo ciò che prima funzionava a meraviglia.
2. Rimuovi le formulazioni più rigide. I modelli di quinta generazione gestiscono peggio comandi come “non fare mai X, fai sempre e solo Y” rispetto a formulazioni flessibili che spiegano il perché.
3. Fai attenzione ai casi in cui il modello si ferma troppo presto. A volte è un segnale che un’istruzione si contraddice o entra in conflitto con una regola contenuta in un CLAUDE.md troppo lungo.

Come riscrivere CLAUDE.md per Opus 5: passo dopo passo#

Ecco la procedura per lavorare su un CLAUDE.md ereditato dai modelli precedenti.

1. Esegui il controllo integrato

   Digita claude doctor nel progetto. Ti suggerirà cosa rimuovere dal file troppo lungo e cosa conservare.

2. Rimuovi ciò che è ovvio

   Elimina tutte le righe che Claude può dedurre dal codice stesso: struttura delle cartelle, elenco delle librerie e frasi generiche come “scrivi codice pulito”.

3. Rimuovi le contraddizioni

   Esamina il file dall’inizio alla fine e individua le regole in conflitto. Conservane una ed elimina quella in conflitto.

4. Sposta le procedure nelle skill

   Sposta in una skill separata tutto ciò che è passato da fatto a istruzione passo dopo passo. Lascia in CLAUDE.md un collegamento di una riga.

5. Rendi specifiche le regole rimanenti

   Riformula ogni regola in modo che sia verificabile: “formattalo correttamente” diventa “usa un’indentazione di 2 spazi”.

6. Attiva la memoria automatica e controlla la lunghezza

   Assicurati che la memoria automatica funzioni (/memory) e che il file sia sotto le 200 righe. Se non lo è, c’è qualcos’altro da spostare.

Per evitare di fare a mano la prima revisione, chiedi a Claude di svolgere il lavoro. Ecco un prompt che puoi usare come punto di partenza: copialo e incollalo in una sessione aperta nel tuo progetto:

Leggi il mio CLAUDE.md e il mio codice. Il tuo compito è rendere CLAUDE.md più breve e utile per un modello di quinta generazione.

Esamina il file e suddividi tutte le regole in tre gruppi:

MANTIENI - insidie specifiche del progetto e convenzioni che non puoi dedurre dal codice.

ELIMINA - cose ovvie che già sai e tutto ciò che si può dedurre dal codice.

SPOSTA IN UNA SKILL - procedure in più passaggi che al momento sono contenute come testo in CLAUDE.md.

Per il gruppo 1, riformula le regole vaghe in modo che siano concrete e verificabili.
Individua le regole in conflitto tra loro e mostrale separatamente.
Restituisci una nuova versione di CLAUDE.md di meno di 200 righe, oltre a un elenco di ciò che proponi di spostare nelle skill.
Non modificare alcun file finché non ti do conferma.

Fai caso all’ultima riga: “Non modificare nulla finché non ti do conferma”. Con un modello che ora usa il proprio giudizio, è importante: chiedigli prima di mostrarti un piano e lascia a te la decisione.

Perché il contesto è più importante del prompt?#

Se lasci da parte i dettagli su Opus 5 e guardi al quadro generale, tutta questa analisi ruota attorno a un’idea: il contesto è più importante del prompt. Il lavoro più importante avviene prima della richiesta, quando prepari l’ambiente in cui lavorerà il modello.

CLAUDE.md, le skill e la memoria automatica fanno tutte parte di un’unica cosa: ciò che Claude vede prima del tuo primo messaggio. Puoi perfezionare all’infinito la formulazione della richiesta, ma se il contesto è preparato male—un CLAUDE.md troppo lungo, regole contraddittorie, nessuna struttura—i risultati saranno comunque incoerenti.

Ecco un semplice controllo: senza un primo cervello, un secondo cervello non sarà d’aiuto. Con “secondo cervello”, questo articolo intende la struttura della conoscenza di un progetto che il modello legge a ogni richiesta. Ma funziona solo se è sostenuta da una tua chiara comprensione dell’attività. Uno strumento amplifica il tuo pensiero, e il suo ruolo finisce lì.

L’aggiornamento a Opus 5 ha reso questa logica ancora più chiara. Anthropic ha dimostrato con il proprio lavoro che, quando il modello è abbastanza intelligente, le regole in più fanno solo danno e il vantaggio va a chi ha preparato con cura il contesto. È una competenza che ti accompagnerà con ogni modello futuro, Opus 6 o qualsiasi altro.

Da dove dovresti cominciare adesso?#

Non rimandare a “un giorno”. Il primo passo più semplice è aprire CLAUDE.md adesso e chiederti sinceramente, riga per riga: è un’insidia che Claude non può dedurre oppure è una cosa ovvia che ho aggiunto per sicurezza? Tutto ciò che appartiene al secondo gruppo può essere eliminato.

Poi sottoponi il file al prompt nella sezione precedente, sposta le procedure lunghe nelle skill e controlla che la memoria automatica sia attiva. Una serata di lavoro e il tuo contesto diventerà una base concisa e precisa per il modello.

Puoi applicarlo su un tuo progetto reale: CLAUDE.md, un secondo cervello e skill per le tue attività.

Scopri Ailoot.