Il CLAUDE.md di Karpathy, spiegato: un file dietro una ricerca di competenze

Su Google Trends, a livello mondiale, negli ultimi sette giorni e consultato il 23 ottobre 2026, "karpathy skills" compare come query in crescita sotto il termine seme "claude skills". Chiunque segua quella ricerca finisce nello stesso posto: github.com/multica-ai/andrej-karpathy-skills, un repository che mostrava 222.612 stelle su GitHub, consultato il 23 ottobre 2026. La sua descrizione non contiene affatto la parola skill. Recita: "Un singolo file CLAUDE.md per migliorare il comportamento di Claude Code, derivato dalle osservazioni di Andrej Karpathy sulle insidie della programmazione con LLM."

Il divario tra la query e l'oggetto non è una piccola sottigliezza tecnica. Una skill e un file CLAUDE.md sono meccanismi diversi che svolgono un lavoro diverso, e quasi ogni affermazione che le persone fanno su questo repository o dipende dal sapere quale dei due sia, oppure presume silenziosamente quello sbagliato. La guida all'interno è un singolo file. Il repository attorno a quel file contiene anche un manifest del plugin e una cartella sotto skills, che è probabilmente l'origine della parola nella barra di ricerca. Separare il packaging dal payload è la prima mossa utile qui.

I numeri, tutti da GitHub e letti il 23 ottobre 2026: 222.612 stelle, 22.321 fork, creato il 27 gennaio 2026, ultimo push il 20 aprile 2026, licenza MIT. Quest'ultima coppia è quella interessante. Il repository non ha ricevuto un push da circa sei mesi, eppure il numero di stelle ha continuato a salire.

Il file fa il lavoro; il packaging spiega il termine di ricerca.

Apri il repository e l'elenco dei file rende il disallineamento facile da vedere. C'è CLAUDE.md alla radice, e accanto CURSOR.md, EXAMPLES.md, una cartella .cursor/rules che contiene le stesse linee guida sotto forma di regola di progetto Cursor, una cartella .claude-plugin e una directory skills/karpathy-guidelines. Il percorso di installazione consigliato nel README è il marketplace dei plugin, e descrive il risultato come rendere «la skill disponibile in tutti i tuoi progetti».

Quindi il termine di ricerca non è tanto sbagliato quanto impreciso. C’è una cartella skills. C’è un plugin. Quello che non c’è è un insieme di skill separate, ciascuna delle quali svolge un compito diverso, che è la forma che le persone di solito intendono con skill pack: una cartella che contiene un SKILL.md e tutti i file di supporto necessari a quella capacità, richiamata per un singolo compito. Qui l’intera guida è un unico documento di istruzioni permanenti, e il plugin esiste per portare quel documento all’interno di un progetto.

Che questa distinzione per te conti dipende da ciò che cercavi nella ricerca. Se cercavi una cassetta degli attrezzi, questa non lo è. Se volevi un breve manuale di regole che cambi il modo in cui un agente di programmazione si comporta in un progetto, è esattamente questo, e vale la pena capire perché qualcuno lo scriverebbe come file anziché come skill.

Le lamentele contro cui è stato scritto

La fonte dichiarata nel README è un post di Andrej Karpathy su X, che il README cita per tre critiche sul modo in cui i modelli scrivono codice. Vale la pena leggerle per intero, perché i quattro principi corrispondono a esse quasi uno a uno.

Il primo: i modelli «formulano supposizioni errate al posto tuo e le seguono senza verificare», e «non gestiscono la propria confusione, non cercano chiarimenti, non fanno emergere incoerenze, non presentano compromessi, non oppongono resistenza quando dovrebbero». Nota ciò che viene descritto. Non è una lamentela sulle risposte sbagliate. È una lamentela sulle risposte sbagliate fluenti fornite senza esitazione, in cui l'incertezza che avrebbe dovuto produrre una domanda ha invece prodotto codice sicuro di sé.

Il secondo: “amano davvero complicare eccessivamente il codice e le API, gonfiare le astrazioni, non ripulire il codice morto… implementare una costruzione sovradimensionata di oltre 1000 righe quando ne basterebbero 100”. Quello è familiare a chiunque abbia chiesto una funzionalità e ricevuto un framework.

Il terzo è più sottile e, per chiunque revisioni diff, il più costoso: "a volte modificano/rimuovono ancora commenti e codice che non comprendono sufficientemente come effetti collaterali, anche se ortogonali al compito". Una modifica ortogonale a un commento è piccola di per sé. Moltiplicata in un'intera base di codice, è così che una coda di revisione si riempie di modifiche che nessuno ha richiesto, e che un commento che spiega una soluzione alternativa scompare prima che qualcuno scopra perché quella soluzione esistesse.

Quattro principi, e il test che ciascuno lascia dietro di sé

Il file codifica quattro principi. Ognuno è accompagnato da un breve insieme di regole, e due di essi indicano un test da una riga che puoi applicare a un diff senza installare nulla. È nelle regole che si manifesta il carattere del file.

Pensa prima di scrivere codice

L'istruzione dell'intestazione è "Non dare nulla per scontato. Non nascondere la confusione. Rendi espliciti i compromessi." Al di sotto: enuncia esplicitamente le ipotesi e chiedi invece di indovinare; presenta più interpretazioni quando la richiesta è ambigua; obietta quando esiste un approccio più semplice; fermati quando sei confuso, indica ciò che non è chiaro e chiedi chiarimenti. Questo mira direttamente alla prima critica. Il meccanismo non è "essere più attento": consiste nel trasformare le scelte silenziose in scelte visibili, così che un revisore possa dissentire prima che il codice esista anziché dopo.

Prima la semplicità

La regola è il codice minimo che risolve il problema, senza nulla di speculativo: nessuna funzionalità oltre a ciò che è stato chiesto, nessuna astrazione per codice a uso singolo, nessuna flessibilità o configurabilità che nessuno ha richiesto, nessuna gestione degli errori per scenari impossibili e «se 200 righe potessero essere 50, riscrivilo». Il test è una singola domanda — un ingegnere senior direbbe che è troppo complicato? — che è una questione di giudizio, e dichiaratamente tale.

Modifiche chirurgiche

Qui il file divide l'istruzione in due, che è la cosa più utile che contiene. Quando modifichi codice esistente: non migliorare codice, commenti o formattazione adiacenti; non rifattorizzare ciò che non è rotto; allineati allo stile esistente anche se tu lo faresti diversamente; menziona il codice morto non correlato invece di eliminarlo. Quando le tue modifiche creano orfani: rimuovi le importazioni, le variabili e le funzioni che le tue modifiche hanno reso inutilizzate, ma lascia stare il codice morto preesistente a meno che non ti venga chiesto. Il criterio è che ogni riga modificata risalga direttamente alla richiesta.

Esecuzione guidata dagli obiettivi

Definisci criteri di successo e itera finché non sono verificati. Il README mostra la trasformazione come coppie. Invece di "aggiungere validazione", scrivi test per input non validi e poi falli passare. Invece di "correggere il bug", scrivi un test che lo riproduca e poi fallo passare. Invece di "rifattorizzare X", assicurati che i test passino prima e dopo. Per il lavoro in più passaggi chiede un breve piano in cui ogni passaggio nomina la propria verifica. Il README cita di nuovo Karpathy qui: "Gli LLM sono eccezionalmente bravi a iterare finché non raggiungono obiettivi specifici… Non dirgli cosa fare, dagli criteri di successo e guardalo procedere."

Un file, una skill e un plugin sono tre cose diverse.

Vale la pena essere precisi sul meccanismo, perché il comportamento pratico è diverso. CLAUDE.md è un file di istruzioni di progetto: testo che Claude Code legge come contesto permanente per un repository, presente indipendentemente dal fatto che qualcuno lo abbia richiesto in questo turno. Una skill è una cartella con un SKILL.md che descrive quando la capacità dovrebbe essere usata, caricata quando un compito lo richiede e non prima. Un plugin è un pacchetto di distribuzione, installato tramite un marketplace, che può contenere skill, comandi e altri componenti. Le distinzioni riguardano quando le istruzioni entrano nel contesto e chi decide, non la qualità.

Un CLAUDE.md è, in questo senso, il più diretto dei tre. È sempre attivo in quel progetto, si applica a ogni attività al suo interno e occupa contesto a ogni turno, che il lavoro sia la correzione di un refuso di una riga o una migrazione. Il README del file stesso riconosce il costo in una sezione chiamata Tradeoff Note: le linee guida propendono per la cautela rispetto alla velocità e, per le attività banali — semplici correzioni di refusi, one-liner ovvi — dovresti usare il tuo giudizio. Dice che l'obiettivo è ridurre gli errori costosi nelle attività non banali, non rallentare quelle semplici.

È un resoconto equilibrato di ciò che un file di istruzioni permanenti può fare. Non può aggiungere una capacità che il modello non possiede. Può solo rendere più o meno probabile il comportamento esistente del modello. Ecco perché il file è scritto come vincoli — non fare questo, chiedi prima di quello — anziché come incoraggiamento a fare meglio.

Che cosa misurano 222.612 stelle

Misurano l'attenzione. Non è una cosa da liquidare e non è poco: un repository creato a gennaio 2026 e con l'ultimo push ad aprile ha raggiunto 222.612 stelle e 22.321 fork entro il 23 ottobre 2026, su GitHub, consultato quel giorno, il che significa che è stato condiviso ampiamente e forkato da persone che ne volevano una copia propria. Il conteggio delle stelle è un proxy ragionevole di quante persone hanno trovato qualcosa che valeva la pena mettere tra i preferiti.

Non è un indicatore surrogato dell'effetto, e il repository non finge il contrario. Ciò che non è pubblicato da nessuna parte al suo interno: qualsiasi benchmark che confronti i risultati con e senza il file, qualsiasi metodologia per misurare se funziona e qualsiasi confronto con un gruppo di controllo. Non c'è alcun prima-e-dopo su una codebase reale, nessuno studio con revisori, nessun tasso di incidenti. Un file come questo è un'ipotesi sul comportamento del modello, enunciata in modo elegante, e nessuno ha eseguito la sperimentazione.

Ciò che il README offre invece è una sezione intitolata Come sapere se sta funzionando, che elenca quattro cose che potresti osservare: meno modifiche non necessarie nei diff, meno riscritture dovute a complicazioni eccessive, domande di chiarimento che arrivano prima dell'implementazione anziché dopo gli errori, e pull request minime e pulite. Questi sono segnali sensati. Sono anche esattamente ciò che scriveresti se non avessi misurato nulla, e sono autodichiarati da chiunque applichi il file. Leggili come una lista di controllo con cui valutare il file nel tuo repository, non come prova che sia già stato superato.

Quello che digiti effettivamente per installarlo

Il README indica due percorsi. Quello consigliato viene eseguito all'interno di Claude Code: aggiungi il marketplace, poi installa il plugin, dopodiché le linee guida sono presenti in tutti i progetti anziché per singolo repository. Il secondo è per progetto: recupera il CLAUDE.md grezzo in un nuovo repository, oppure aggiungilo a uno esistente. È inoltre presente una regola di progetto Cursor committata, quindi le stesse linee guida si applicano quando la cartella viene aperta in Cursor — un dettaglio che indica che il file è stato scritto per essere portabile tra strumenti che leggono un file di istruzioni a livello di progetto, non legato al loader di un singolo fornitore.

Un dettaglio fastidioso, che vale la pena segnalare perché lo incontrerai se segui il README alla lettera. I nomi dei comandi del marketplace indicano forrestchang/andrej-karpathy-skills, mentre l'URL del repository in cima alla pagina è multica-ai/andrej-karpathy-skills. Entrambe le stringhe compaiono nello stesso README, letto il 23 ottobre 2026. Vedo la discrepanza e non posso dirti perché esista, quindi il consiglio onesto è provare l'altro percorso se uno fallisce, e considerare obsoleta una delle due stringhe.

L'altra cosa da notare nella pagina iniziale: il repository è mantenuto da multica-ai, e il blockquote di apertura del README pubblicizza Multica, "una piattaforma open-source per eseguire e gestire agenti di coding con competenze riutilizzabili". È una dichiarazione legittima, ed è anche un indizio del perché il packaging abbia questo aspetto. Un progetto interessato alle competenze riutilizzabili è probabile che distribuisca le proprie linee guida come qualcosa di installabile, e il plugin è proprio questo.

Usarlo senza ereditarne i presupposti

La sezione Personalizzazione è la parte che la maggior parte dei lettori salta. Il file è pensato per essere integrato con istruzioni specifiche del progetto anziché sostituirle, e gli esempi che fornisce sono concreti: usa la modalità strict di TypeScript, tutti gli endpoint API devono avere test, segui i pattern di gestione degli errori esistenti in un file specifico. Non si tratta di decorazione. È la differenza tra un manuale di regole generico e un insieme di istruzioni che sa dove vive il tuo codice.

C'è una ragione pratica per unire anziché impilare. Se incolli il file così com'è e il tuo progetto ha le proprie convenzioni, i due insiemi di istruzioni possono entrare in conflitto, e un modello che riconcilia un conflitto è proprio la confusione che il primo principio cerca di eliminare. Scrivere le tue convenzioni nello stesso file, con la stessa voce, mantiene la superficie delle istruzioni abbastanza piccola da poter essere verificata.

E dovresti assolutamente verificarlo. Questo è un breve documento di istruzioni comportamentali che si applicherà a ogni richiesta nel repository. La domanda giusta non è se 222.612 persone possano sbagliarsi — questa impostazione non risolve nulla — ma se ciascuna regola corrisponde a un errore che hai effettivamente visto. Se i tuoi diff non hanno mai contenuto riscritture di commenti estemporanee, la sezione Surgical Changes ti costa contesto senza motivo. Eliminala. Il file è con licenza MIT ed è pensato per essere modificato.

Un livello più in basso, nulla di tutto ciò cambia quale modello risponde. Un file CLAUDE.md influenza il modo in cui una richiesta viene gestita una volta che raggiunge un modello; non dice nulla sul modello che la riceve. Quella seconda decisione spetta a qualunque cosa si trovi davanti al modello. Un modo per organizzarla è un unico endpoint compatibile con OpenAI che offre più di 200 modelli sotto un'unica chiave, con failover automatico tra provider e prezzi di listino dei provider passati con un ricarico dello 0%. Noi ospitiamo modelli; non realizziamo Claude Code, e nulla nel tuo repository è visibile a noi.

La ricerca continuerà a dire skills, perché è la parola che le persone usano per una cosa che installi per far comportare un agente in modo diverso, e anche il packaging attorno a questo repository la usa. L'artefatto è un file: un documento di istruzioni permanenti, scritto in risposta a tre reclami specifici, con quattro principi e una serie di test che puoi applicare a mano. Giudicalo in base a se quei reclami suonano come il tuo repository. È una domanda migliore del numero di stelle, che ha sempre e solo misurato quante persone hanno avuto la stessa reazione che hai appena avuto.