Un documento diffuso nella comunità degli sviluppatori e attribuito, senza conferma ufficiale, ad Andrej Karpathy propone dieci regole per usare gli agenti AI di coding in modo più controllato. Il punto non è ottenere codice più velocemente attraverso prompt più dettagliati, ma progettare un flusso in cui l’agente legge il contesto, definisce un obiettivo verificabile, modifica il repository, esegue i test e controlla autonomamente se il risultato corrisponde davvero alla richiesta.
Le prime quattro regole riprendono principi già associati al metodo di lavoro di Karpathy: riflettere prima di scrivere codice, privilegiare la soluzione più semplice, limitare le modifiche al perimetro richiesto e definire in anticipo cosa significa completare il compito. L’obiettivo è ridurre una tendenza tipica dei coding agent, cioè trasformare una richiesta locale in una serie di modifiche più ampie, spesso non necessarie e difficili da verificare.
Le sei indicazioni aggiuntive spostano però il focus dalla generazione del codice alla verifica del comportamento. La correzione di un bug dovrebbe iniziare dalla creazione di un test che riproduca l’errore. Solo dopo aver modificato il codice, l’agente deve rieseguire quel test e considerare il problema risolto esclusivamente se l’esito cambia nel modo atteso. Non è quindi sufficiente che il modello giudichi plausibile la propria correzione: serve un risultato riproducibile nel progetto.
La definizione dell’obiettivo deve essere altrettanto concreta. Una richiesta come “aggiungi la validazione dell’email” lascia al modello troppe possibilità interpretative. Un criterio più utile indica invece il comportamento atteso: indirizzi vuoti o malformati devono generare un errore, gli indirizzi validi devono essere accettati e i test relativi devono superare l’esecuzione. Quando il lavoro richiede più passaggi, la pianificazione deve precedere l’implementazione, evitando che l’agente inizi a modificare file senza avere una visione chiara delle dipendenze e degli effetti della modifica.
Anche il debugging viene trattato come un processo disciplinato. L’agente deve leggere integralmente errori e stack trace, riprodurre il difetto prima di intervenire e modificare un elemento per volta. Correggere contemporaneamente più componenti può nascondere la causa reale del problema, produrre regressioni e rendere difficile capire quale intervento abbia determinato il risultato finale.
Un’altra regola riguarda le dipendenze. Prima di introdurre una nuova libreria, l’agente deve verificare se il progetto dispone già di strumenti adatti oppure se la funzione può essere implementata con la libreria standard. L’aggiunta di pacchetti esterni aumenta infatti la complessità di manutenzione, espone a problemi di compatibilità e amplia la superficie tecnica da controllare. Quando una dipendenza è davvero necessaria, la scelta deve essere giustificata esplicitamente.
Il documento insiste inoltre sul modo in cui il modello comunica le proprie incertezze. Un agente non dovrebbe dichiarare come certe capacità di una libreria o comportamenti di un sistema che non ha verificato. Deve invece trasformare il dubbio in un’azione: leggere la documentazione disponibile, ispezionare la versione installata, cercare esempi nel repository oppure creare un test mirato. Questo evita che supposizioni ragionevoli ma errate entrino direttamente nel codice di produzione.
La parte più interessante riguarda quattro pattern di errore che l’agente dovrebbe riconoscere mentre lavora. Il primo è il cosiddetto Kitchen Sink: una richiesta circoscritta, come correggere una funzione, viene trasformata in una revisione ampia di moduli e architettura. Il secondo è la Wrong Abstraction, cioè l’introduzione di strutture astratte inutili oppure, al contrario, la duplicazione ripetuta di logiche che meriterebbero una funzione comune. Il terzo è l’Optimistic Path, dove il codice considera solo input validi e condizioni ideali, ignorando errori di rete, dati incompleti, eccezioni applicative e fallimenti dei servizi esterni. Il quarto è il Runaway Refactor, in cui una modifica inizialmente limitata genera una sequenza di cambiamenti strutturali che coinvolge molti file senza una reale necessità.
La regola operativa è significativa: quando l’agente riconosce uno di questi pattern, non deve proseguire automaticamente fino alla fine del task. Deve fermarsi, rivalutare il piano e ridurre il perimetro dell’intervento. È un approccio pensato soprattutto per gli ambienti in cui gli agenti operano per più passaggi consecutivi, con un livello di supervisione umana ridotto.
Questa impostazione viene spesso collegata alla cosiddetta loop engineering. Invece di considerare il prompt come il centro dell’interazione, lo sviluppo assistito dall’AI viene costruito attorno a un ciclo: comprensione della richiesta, pianificazione, esecuzione, verifica, correzione e decisione sul completamento. Il valore dell’agente non dipende soltanto dalla qualità del codice generato al primo tentativo, ma dalla sua capacità di verificare le conseguenze delle proprie azioni e di interrompersi quando sta prendendo una direzione sbagliata.
In questo contesto, file di istruzioni come CLAUDE.md possono fornire all’agente regole persistenti sul repository: convenzioni di sviluppo, comandi di test, limiti sulle dipendenze, componenti da non modificare e criteri di accettazione. Non rappresentano però un vincolo assoluto, perché vengono trattati come contesto e non come istruzioni di sistema. Proprio per questo vanno controllati con attenzione, specialmente nei repository esterni, dato che istruzioni malevole potrebbero spingere l’agente a eseguire comandi rischiosi, leggere file sensibili o utilizzare credenziali presenti nell’ambiente di lavoro.
Le regole attribuite a Karpathy indicano quindi un cambiamento concreto nel modo di usare gli AI coding agent. Il tema non è più soltanto scrivere prompt migliori, ma costruire processi in cui il modello possa operare con obiettivi misurabili, test ripetibili, limiti di intervento chiari e meccanismi capaci di bloccare il lavoro prima che una semplice correzione diventi una modifica incontrollata dell’intero progetto.