Context engineering per Claude 5: come riscrivere CLAUDE.md, skill e prompt

Il context engineering per i modelli della generazione Claude 5 si fa per sottrazione, e chi ha scritto file di istruzioni lunghi negli ultimi due anni oggi ha del lavoro da disfare. Nell'articolo pubblicato il 24 luglio 2026 sul blog di Anthropic, Thariq Shihipar racconta che dal prompt di sistema di Claude Code è stato rimosso oltre l'80% del testo per modelli come Claude Opus 5 e Claude Fable 5, senza nessuna perdita misurabile nelle valutazioni interne sul coding. Questa guida traduce quel principio in cosa cambiare, file per file.

Il context engineering è il lavoro di decidere cosa il modello ha davanti mentre lavora: il prompt di sistema, il file CLAUDE.md del progetto, le descrizioni degli strumenti, le skill e i documenti di riferimento. Anthropic lo distingue dal prompt engineering con una frase che conviene tenere a mente mentre si taglia: a differenza di un prompt, il contesto viene usato in modo generale su molte richieste diverse, quindi non può essere altrettanto specifico. Se ti serve prima il quadro dello strumento, l'ho scritto in cos'è Claude Code e come funziona.

Cosa tenere e cosa togliere dal CLAUDE.md

Il file CLAUDE.md va tenuto leggero: poche righe per dire a cosa serve il repository, e la maggior parte dei token spesa sulle trappole che stanno dentro il codice. È il consiglio esplicito dell'articolo di Anthropic, e la documentazione di Claude Code aggiunge la soglia pratica: stare sotto le 200 righe, tenendo solo l'essenziale.

La regola per decidere cosa cancellare è semplice: se il modello può scoprirlo aprendo i file, non va scritto. L'elenco delle cartelle, la descrizione di cosa fa una libreria famosa, la spiegazione di come funziona il framework che stai usando sono tutte informazioni che il modello ottiene in un secondo leggendo il progetto, e che nel frattempo paghi a ogni sessione.

Quello che invece non si deduce leggendo il codice va scritto e va scritto meglio di prima. Le trappole sono cose come: quel modulo sembra morto ma lo chiama un cron, quella cartella è generata e non va toccata a mano, quel test fallisce sulla macchina di sviluppo per un motivo noto, il deploy funziona solo se prima gira quel comando. È il tipo di conoscenza che sta nella testa di chi lavora sul progetto da mesi, e che nessun modello può indovinare.

Quando serve una skill invece di una regola nel prompt

Una procedura lunga non va nel file di istruzioni del progetto, va dentro una skill. La differenza è quando viene caricata: il CLAUDE.md entra nel contesto all'avvio di ogni sessione, una skill si carica solo quando serve davvero. Se hai scritto nel CLAUDE.md i sette passaggi della revisione delle pull request, li stai pagando anche nei giorni in cui non tocchi nessuna pull request.

Anthropic descrive le skill come guide leggere che permettono al modello di trovare l'informazione quando gli serve, e consiglia di dividere quelle lunghe su più file invece di tenerle in un blocco unico. È quello che nell'articolo viene chiamato progressive disclosure: non caricare tutto in partenza, lasciare che il dettaglio venga preso al momento giusto. Lo stesso principio vale per gli strumenti, le cui definizioni complete si caricano su richiesta invece che tutte insieme all'avvio.

Il contenuto giusto per una skill è quello che l'articolo definisce come le opinioni, le conoscenze e le buone pratiche particolari di te, del tuo team o del tuo prodotto. Non le regole generali di programmazione, che il modello conosce meglio di noi: il modo specifico in cui le cose si fanno da voi.

Come si riscrive una regola in criterio

L'esempio più chiaro dell'articolo di Anthropic riguarda i commenti nel codice. La vecchia istruzione del prompt di Claude Code diceva di non scrivere commenti per impostazione predefinita, mai docstring su più paragrafi, al massimo una riga corta. La nuova dice una cosa sola: scrivi codice che si legge come il codice attorno, adeguando densità dei commenti, nomi e modi di fare.

La differenza non è di lunghezza, è di natura. La prima è una regola che vale sempre, anche dentro un repository pieno di docstring lunghe dove produce codice fuori posto e formalmente conforme. La seconda è un criterio che il modello applica guardando dove si trova, e che continua a funzionare in progetti diversi senza che nessuno lo riscriva.

Il modo pratico per rifare questo passaggio sui propri file è prendere ogni riga imperativa e chiedersi cosa stia davvero cercando di ottenere. Quasi sempre sotto una regola rigida c'è un obiettivo che si può dire meglio: dietro "non usare mai commenti" c'è "non aggiungere rumore", dietro "usa sempre questo formato di data" c'è "resta coerente con il resto del progetto". Il criterio sopravvive ai casi che non avevi previsto, la regola no.

Sugli esempi la tesi è più scomoda e vale la pena prenderla sul serio: dare esempi a un modello della generazione Claude 5 lo vincola a un certo spazio di esplorazione. Al posto degli esempi, l'articolo consiglia di progettare interfacce espressive. Un parametro che accetta soltanto pending, in_progress o completed dice come si usa quello strumento meglio di tre esempi scritti a mano, e lo dice senza restringere il campo su tutto il resto.

C'è poi una forma di spreco che quasi tutti hanno in casa: la stessa istruzione scritta due volte, una nel prompt di sistema e una nella descrizione dello strumento. Anthropic consiglia di tenerla solo nella descrizione dello strumento ed eliminare la ripetizione, che non rafforza niente e occupa spazio.

Memoria automatica e specifiche più ricche

La memoria non si salva più a mano. Nell'era precedente si usava il tasto cancelletto per scrivere una nota dentro il CLAUDE.md, mentre oggi Claude salva da solo le memorie rilevanti per il lavoro e per la persona con cui lavora. La conseguenza pratica è che il CLAUDE.md smette di essere il posto dove si accumulano appunti, e torna a essere un documento breve sul progetto.

Cambia anche cosa può fare da specifica. Un piano scritto in markdown non è più l'unico formato: l'articolo di Anthropic cita gli artifact HTML prodotti dalla nuova funzione dedicata, e osserva che una specifica può anche essere una suite di test dettagliata, o una funzione presa da un altro progetto che il modello deve portare nel tuo. Vale la pena provarci, perché una specifica fatta di codice è più precisa di qualsiasi descrizione a parole.

Cosa fare oggi, in ordine

1. Lancia /doctor da dentro Claude Code: è il comando che Anthropic indica per dimensionare correttamente skill e file CLAUDE.md
2. Taglia il CLAUDE.md sotto le 200 righe, cancellando tutto ciò che il modello può scoprire leggendo il progetto
3. Sposta dentro le skill le procedure che servono solo in certi momenti, e dividi su più file quelle lunghe
4. Cerca le istruzioni scritte due volte, nel prompt e nella descrizione di uno strumento, e tienile solo nel secondo posto
5. Riscrivi le regole rigide in criteri, partendo da quelle sullo stile del codice, che sono le prime a essere diventate inutili

Chi non ha ancora messo mano alla configurazione trova il punto di partenza in come configurare Claude Code, tenendo presente che oggi quei file si scrivono molto più corti rispetto a un anno fa.

Le regole che non vanno cancellate

Su questo blog ci sono agenti che pubblicano ogni mattina senza nessuno davanti allo schermo, e i loro prompt sono lunghi. Rileggendoli con il criterio dell'articolo di Anthropic, una parte è chiaramente diventata inutile: le istruzioni su come si scrive un titolo, sul tono, su cosa suona artificiale sono esattamente il tipo di gusto che un modello della generazione Claude 5 applica meglio da solo.

Ma non tutte le righe di un file di istruzioni sono uguali, e questa è la distinzione che l'articolo non fa perché sta rispondendo a un'altra domanda. Ci sono le regole di giudizio, che descrivono una preferenza di stile o di mestiere, e quelle si possono cancellare quasi tutte. E ci sono le regole che descrivono vincoli del mondo, che nessun modello può dedurre guardando il codice: non pubblicare più di due articoli al giorno, fermarsi se la build fallisce, non toccare file fuori da una cartella precisa, non inventare un dato che non sta nella fonte. Quelle restano, e adesso che tutto il resto si accorcia vanno scritte in modo ancora più esplicito.

Il rischio di questa fase è leggere "meno istruzioni" e togliere le seconde insieme alle prime. Un agente che pubblica tre articoli in un giorno perché nessuno gli ha detto quanti ne può fare non ha sbagliato giudizio: gli mancava un'informazione. È lo stesso ragionamento che ho fatto parlando di quali permessi dare all'AI in azienda, e vale ancora di più quando il contesto si accorcia.

Il modo giusto di rileggere i propri file di configurazione è chiedersi riga per riga se quella riga insegna un gusto o comunica un limite. Le prime si cancellano oggi e non le rimpiangi. Le seconde sono le uniche che scriverai ancora fra un anno.