Ce dépôt GitHub propose un ensemble de guidelines pour Claude Code, inspirées des observations d'Andrej Karpathy sur les limitations des LLMs en développement logiciel. Avec plus de 3 400 stars en quelques jours, il répond manifestement à un besoin de la communauté.
Problèmes identifiés : Karpathy a observé que les modèles tendent à faire des hypothèses erronées sans vérification et à "partir dans une direction" sans valider leurs présupposés. Ils sur-compliquent souvent les solutions, créant des abstractions inutiles quand des approches simples suffiraient. Enfin, ils modifient ou suppriment parfois du code qu'ils ne comprennent pas entièrement, même sans rapport avec la tâche demandée.
Quatre principes fondateurs :
Le premier principe, "Think Before Coding", impose d'expliciter les hypothèses et de poser des questions clarifiantes plutôt que de deviner. En cas d'ambiguïté, présenter plusieurs approches viables. S'arrêter et reconnaître quand on est confus.
Le deuxième principe, "Simplicity First", prescrit d'écrire le code minimal répondant uniquement à ce qui est demandé. Éviter les features spéculatives, les abstractions inutiles, la configurabilité non sollicitée. Supprimer la gestion d'erreurs pour des scénarios impossibles. Le test : un ingénieur expérimenté considèrerait-il ce code comme over-engineered ?
Le troisième principe, "Surgical Changes", limite les modifications au code directement lié à la demande utilisateur. Préserver le style et les commentaires existants. Ne supprimer du code mort préexistant que sur demande explicite.
Le quatrième principe, "Goal-Driven Execution", convertit les tâches en critères de succès spécifiques et vérifiables. Plutôt que "ajouter de la validation", formuler "écrire des tests pour les inputs invalides, puis les faire passer". Utiliser des plans numérotés brefs avec étapes de vérification.
Insight fondamental : Les modèles excellent à "boucler jusqu'à atteindre des objectifs spécifiques". Plutôt que d'émettre des instructions impératives, définir des critères de succès clairs et laisser le système itérer vers ces objectifs.
Installation et usage : Le dépôt peut être installé comme plugin Claude (claude plugins add) ou téléchargé comme fichier CLAUDE.md par projet. Les guidelines sont conçues pour être fusionnées avec des règles spécifiques au projet.
Indicateurs de succès : Les diffs ne contiennent que les changements demandés, le code évite la complexité inutile dès la première tentative, des questions clarifiantes précèdent l'implémentation, les pull requests restent focalisées sans refactoring tangentiel.
Caveat : Ces guidelines privilégient la précision sur la vitesse. Pour les changements triviaux (typos, modifications one-liner évidentes), appliquer du bon sens plutôt que la rigueur complète.