Questo repository GitHub offre un insieme di linee guida per Claude Code, ispirate alle osservazioni di Andrej Karpathy sui limiti degli LLM nello sviluppo software. Con oltre 3.400 stelle in pochi giorni, risponde chiaramente a un'esigenza sentita dalla community.
Problemi identificati: Karpathy ha osservato che i modelli tendono a formulare ipotesi errate senza verificarle e a "partire in una direzione" senza validare le proprie premesse. Spesso complicano eccessivamente le soluzioni, creando astrazioni non necessarie laddove approcci semplici sarebbero sufficienti. Infine, talvolta modificano o rimuovono codice che non comprendono pienamente, anche quando estraneo al compito richiesto.
Quattro principi fondanti:
Il primo principio, "Think Before Coding", richiede di rendere esplicite le ipotesi e di porre domande di chiarimento piuttosto che indovinare. In caso di ambiguità, presentare diversi approcci praticabili. Fermarsi e riconoscere la confusione quando si presenta.
Il secondo principio, "Simplicity First", prescrive di scrivere il codice minimo che affronti solo quanto richiesto. Evitare funzionalità speculative, astrazioni non necessarie e configurabilità non richiesta. Rimuovere la gestione degli errori per scenari impossibili. Il test: un ingegnere esperto considererebbe questo codice sovra-ingegnerizzato?
Il terzo principio, "Surgical Changes", limita le modifiche al codice direttamente collegato alla richiesta dell'utente. Preservare lo stile e i commenti esistenti. Rimuovere codice morto preesistente solo su richiesta esplicita.
Il quarto principio, "Goal-Driven Execution", converte i compiti in criteri di successo specifici e verificabili. Anziché "aggiungi la validazione", formulare "scrivi test per input non validi, poi falli passare". Utilizzare piani numerati brevi con passaggi di verifica.
Intuizione centrale: I modelli eccellono nel "ciclare finché non si raggiungono obiettivi specifici". Anziché impartire istruzioni imperative, definire criteri di successo chiari e lasciare che il sistema iteri verso tali obiettivi.
Installazione e utilizzo: Il repository può essere installato come plugin per Claude (claude plugins add) oppure scaricato come file CLAUDE.md per singolo progetto. Le linee guida sono concepite per essere unite alle regole specifiche del progetto.
Indicatori di successo: I diff contengono solo le modifiche richieste, il codice evita complessità non necessaria al primo tentativo, le domande di chiarimento precedono l'implementazione e le pull request restano mirate senza refactoring tangenziali.
Avvertenza: Queste linee guida privilegiano la precisione rispetto alla velocità. Per modifiche banali (refusi, modifiche ovvie di una riga), applicare il buon senso piuttosto che il rigore completo.