225,000 stelle per un Markdown: Karpathy in quattro regole

Un repository che contiene un solo file Markdown ha 225,000 stelle. Questa settimana ne ha guadagnate circa 4,000. Non c'è codice, non c'è build, non c'è release, non c'è tabella di benchmark: solo quattro principi e una serie di istruzioni su come un modello linguistico dovrebbe comportarsi quando gli si chiede di modificare una base di codice.

Il file si chiama CLAUDE.md, sta in un repository chiamato andrej-karpathy-skills, mantenuto da forrestchang. Comprime una serie di critiche che Andrej Karpathy ha rivolto al comportamento dei LLM quando programmano, in una forma che un agente legge davvero all'inizio di ogni sessione. Il dato interessante è il numero di stelle, non il contenuto, perché dice qualcosa su come il comportamento degli agenti venga oggi rattoppato: in modo ufficioso, in prosa, da singoli.

Le critiche, con le parole di Karpathy

Tre citazioni dal testo originale su cui il repository è costruito:

«I modelli prendono decisioni sbagliate al posto tuo e proseguono senza verificare. Non gestiscono la propria confusione, non chiedono chiarimenti, non fanno emergere le incoerenze, non presentano i compromessi, non obiettano quando dovrebbero.»

«Amano complicare codice e API, gonfiare le astrazioni, non ripulire il codice morto... implementano una costruzione gonfia da oltre 1,000 righe dove ne basterebbero 100.»

«A volte cambiano o rimuovono, come effetto collaterale, commenti e codice che non capiscono abbastanza, anche quando è ortogonale al compito.»

Chi ha rilasciato codice scritto da un agente le riconosce tutte e tre. La seconda è la più comune: chiedi una funzione di validazione e ricevi una classe base astratta, uno strategy pattern, un oggetto di configurazione e quaranta righe di gestione degli errori per stati che non possono verificarsi.

Cosa dicono davvero i quattro principi

Pensare prima di scrivere. Dichiarare le assunzioni, presentare più interpretazioni invece di sceglierne una in silenzio, obiettare quando esiste un approccio più semplice, fermarsi quando si è confusi e dire cosa non è chiaro.

Prima la semplicità. Il minimo codice che risolve il problema. Nessuna funzionalità oltre la richiesta, nessuna astrazione per codice usa e getta, nessuna configurabilità che nessuno ha chiesto, nessuna gestione degli errori per scenari impossibili. Il test: un ingegnere senior direbbe che è troppo complicato?

Modifiche chirurgiche. Toccare solo ciò che serve. Non migliorare il codice adiacente, non riformattare ciò che si attraversa soltanto. Allinearsi allo stile esistente anche se lo si farebbe diversamente. Se si nota codice morto non correlato, segnalarlo, non cancellarlo. Se le modifiche creano orfani, ripulire solo quelli. Il test: ogni riga cambiata risale alla richiesta.

Esecuzione guidata dall'obiettivo. Convertire istruzioni imperative in criteri di successo verificabili. Non «aggiungi la validazione» ma «scrivi i test per gli input non validi, poi falli passare». Non «correggi il bug» ma «scrivi un test che lo riproduca, poi fallo passare».

L'ultimo è l'unico principio che non è una limitazione. È leva, e arriva con la frase migliore del materiale originale: i LLM sono straordinariamente bravi a iterare finché non raggiungono un obiettivo preciso. Non dirgli cosa fare; dagli criteri di successo e guardalo andare.

L'installazione, e il fatto che siano due righe

Due strade, entrambe banali.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Oppure, per progetto:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

C'è anche una regola Cursor versionata in .cursor/rules/karpathy-guidelines.mdc, così le stesse indicazioni valgono quando il progetto si apre in Cursor. Licenza MIT.

La storia della distribuzione è il punto. Due anni fa, correggere «i modelli fanno overengineering» avrebbe significato un fine-tuning, un system prompt distribuito da un fornitore o un framework. Oggi è un file che un utente lascia cadere in un repository, più una voce di marketplace che lo mette in ogni progetto su quella macchina. Il ciclo di retroazione tra la lamentela e la correzione è molto più corto, ed è per questo che il contatore è quello che è: il file è la più piccola unità possibile di cambiamento di comportamento.

Perché resto comunque scettico su questa cornice

Tre riserve, avanzate nello spirito del file stesso.

I principi non sono test. «Prima la semplicità» è una preferenza, non un criterio. Un agente che lo legge produrrà comunque una soluzione da 300 righe dove ne basterebbero 80, perché il modello non ha modo di misurare la complessità. L'unico principio del file che funziona davvero — l'esecuzione guidata dall'obiettivo — funziona proprio perché sostituisce una preferenza con un controllo: un test che passa o non passa.

«Modifiche chirurgiche» combatte ciò in cui gli agenti sono bravi. Se chiedi una modifica piccola e ottieni una modifica piccola, hai usato uno strumento costoso per risparmiare qualche battuta. Il valore di un agente è poter ristrutturare qualcosa che non volevi toccare. La risposta del file: la ristrutturazione va richiesta, non offerta. Ragionevole, ma significa che le linee guida ottimizzano per un tipo specifico di utente: chi ha già una base di codice e un'opinione netta sui diff.

Nessuno misura se funziona. Il repository elenca segnali: meno modifiche inutili nei diff, meno riscritture, domande di chiarimento prima dell'implementazione invece che dopo. Sono reali e osservabili. Ma non c'è un gruppo di controllo. Installi un file che dice «chiedi prima di assumere», e ora l'agente chiede prima di assumere. È stato il file, o è stato scriverlo che ti ha fatto notare un comportamento che c'era già?

L'autore è onesto sul compromesso, e va riconosciuto: le linee guida pendono verso la cautela più che verso la velocità, e per i compiti banali conviene usare il proprio giudizio. È l'avvertenza corretta ed è anche la tensione. Un agente che si ferma a chiedere per correggere un refuso di una riga è peggiore di uno che lo corregge.

La versione che scriverei io

Se il difetto del file è che tre dei suoi quattro principi sono preferenze, il rimedio è convertirli in controlli. Concretamente, quattro righe che sopravvivono al contatto con un repository vero:

Prima di modificare, elenca i file che intendi toccare e fermati se la lista è più lunga di quanto implichi la richiesta. Questo trasforma «modifiche chirurgiche» in un cancello invece che in un umore.

Prima di finire, esegui i test e incolla l'output. Questo rende «esecuzione guidata dall'obiettivo» non negoziabile, ed è l'istruzione con più leva che puoi mettere davanti a un agente.

Se un compito ammette più di un'interpretazione plausibile, scrivile entrambe e chiedi quale. Questo trasforma «pensare prima di scrivere» da aspirazione in un turno di conversazione.

E un budget di diff: se la modifica aggiunge più o meno 150 righe per la correzione di un bug, fermati e giustifica ogni astrazione. Grezzo, ma intercetta il modo di fallire descritto da Karpathy, quello che costa davvero tempo.

Niente di tutto questo è nel file, e non serve che ci sia. Il compito del file è fissare una postura. I controlli sono il compito di chi possiede il repository.

Cosa dice davvero il numero di stelle

La maggior parte del tooling per agenti uscito quest'anno riguarda la capacità: contesto più lungo, più strumenti, esecuzione parallela. Questo file riguarda la misura, e ha ottenuto più attenzione della maggior parte delle release di capacità.

Quel divario è informativo. Chi paga per questi strumenti ha concluso che il collo di bottiglia non è più cosa il modello sa fare, ma farlo smettere di fare cose che nessuno gli ha chiesto. Un file Markdown con 225,000 stelle è un segnale insolitamente chiaro di dove sia davvero la frustrazione.

È anche un segnale un po' imbarazzante per i laboratori. Il repository con più stelle in questa categoria è una lista di quattro cose che i modelli dovrebbero già fare.