Les règles de codage LLM d'Andrej Karpathy : Think, Simplify, & Iterate

Les grands modèles de langage (LLM) comme Claude offrent un énorme avantage en matière de génération de code, mais ils peuvent également produire du code désordonné, surconçu ou même erroné. Andrej Karpathy, pionnier dans le domaine, a distillé ses observations en quatre principes qui aident les développeurs à écrire un code fiable et propre avec Claude. Ce tutoriel passe en revue chaque règle, explique pourquoi elle compte et montre comment intégrer ces recommandations dans votre propre workflow.

1. Think Before Coding

Objectif : Mettre en évidence les hypothèses, clarifier les ambiguïtés, et refuser lorsqu'il existe des décisions plus sûres.

Quand Claude lit une tâche, il infère souvent une interprétation et passe à l'action sans demander. Cela peut entraîner une confusion cachée ou des compromis erronés.

• Exprimez vos hypothèses explicitement : Commencez votre invite par une courte liste de ce que vous supposez.
• Demandez des précisions : Si une exigence est vague, générez d'abord une question pour l'utilisateur.
• Présentez des alternatives : Proposez plusieurs approches viables plutôt que de vous fixer sur une seule.
• Arrêtez-vous si incertain : Indiquez ce qui n'est pas clair et demandez plus de contexte avant de coder.

Astuce pratique : ajoutez un bloc de commentaire au début de chaque fichier que vous générez, avec un bref aperçu des hypothèses et de la stratégie choisie.

2. Simplicity First

Objectif : Prioriser le code le plus simple qui satisfait la spécification.

Claude aime explorer chaque abstraction possible et produit souvent des solutions de 1 000 lignes alors qu'une solution de 50 lignes suffirait. La simplicité réduit la charge cognitive pour les futurs développeurs et diminue la surface d'erreur.

• Supprimez les fonctionnalités inutiles : N'ajoutez pas d'arguments optionnels à moins que la spécification ne les exige explicitement.
• Évitez l'infrastructure générique : Si une petite fonction d'assistance résout le problème, écrivez-la ; ne construisez pas une classe entière au cas où vous pensez la réutiliser.
• Gardez la gestion des erreurs réaliste : Gérez uniquement les chemins d'erreur réalistes. Ne protégez pas contre des états impossibles.
• Appliquez la règle « plus de 200 lignes = 50 lignes » : Lorsqu'un code dépasse 200 lignes, refactorez ou éliminez.

Utilisez le « Test d'ingénieur senior » : « Un ingénieur senior dirait-il que c'est trop compliqué ? » Si oui, simplifiez.

3. Surgical Changes

Objectif : Modifier uniquement ce que l'utilisateur demande explicitement.

Lorsqu'il ajuste du code existant, Claude peut parfois empiéter sur des sections non liées, modifier des commentaires ou refactoriser du code qui fonctionnait correctement.

• Ne touchez pas au code non lié : Limitez les changements aux lignes qui répondent directement à la demande.
• Maintenez le style : Préservez le guide de style du projet ; imitez les modèles existants.
• Ne supprimez pas le code mort préexistant : Si vous remarquez une fonction orpheline, mentionnez-la simplement ; ne la supprimez pas avant qu'on ne vous le demande.
• Nettoyez après vous : Supprimez les imports ou variables inutilisées créés par vos modifications.

Après un changement, exécutez une boucle de revue diff pour confirmer qu'aucune modification non intentionnelle n'a eu lieu.

4. Goal‑Driven Execution

Objectif : Définir des critères de réussite clairs et répéter jusqu'à vérification.

Ce principe tire parti de la force de Claude à itérer jusqu'à ce qu'une condition vérifiable soit satisfaite. Au lieu de donner une commande impérative, vous spécifiez l'état final souhaité.

• Décrivez l'objectif : par ex., « Ajouter la validation d'entrée et exposer les messages d'erreur via une réponse API ».
• Définissez les étapes de vérification : « Écrire un test unitaire pour une entrée vide ; exécuter et confirmer l'échec ; ajouter la validation ; réexécuter et confirmer le succès ».
• Créez un court plan avec des points de contrôle pas à pas.
• Répétez : après chaque changement, demandez à Claude d'exécuter ou d'évaluer les tests.

Exemple de pseudocode :

1. Ajouter un test unitaire pour l'entrée vide → Vérifier l'échec.
2. Insérer la logique de validation → Vérifier l'échec.
3. Ajuster la logique pour faire passer le test → Vérifier le succès.

Comment installer les directives

Le dépôt contient un seul fichier CLAUDE.md que vous pouvez ajouter à n'importe quel projet.

# Option A : En tant que plugin CLI skills
npx skills add forrestchang/andrej-karpathy-skills

# Option B : Copie directe du fichier
# Pour un nouveau projet
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md 

# Pour un projet existant (ajout)
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Une fois le fichier présent, invitez Claude au format Goal‑Driven Execution : « Add data validation; Write tests that catch it; Run until tests pass. » Claude se référera automatiquement aux directives.

Cas d'utilisation pratique

Scénario : une équipe construit une simple API d'enregistrement d'utilisateur. Ils souhaitent : 1. Accepter name, email, et password. 2. Valider le format d'email. 3. Rejeter les e‑mails dupliqués. 4. Stocker le hash du mot‑de‑passe.

En appliquant les règles de Karpathy :

1. Think before coding – demander si l'API doit renvoyer un 409 pour les doublons ou un 400 générique.
2. Simplicity first – utiliser un helper unique pour la validation d'email plutôt qu'un service externe complet.
3. Surgical changes – modifier uniquement le fichier du contrôleur, pas le middleware.
4. Goal‑driven – spécifier les critères de réussite : tests unitaires pour entrées valides et invalides.

Claude générera un code minimal, bien structuré, respectant le style du projet, et le développeur pourra examiner une pull request propre avec uniquement les modifications requises.

Conclusion

Adopter les quatre principes de Karpathy peut réduire drastiquement le bruit et les erreurs rencontrés lors de l'utilisation de LLM pour le codage. En mettant en avant les hypothèses, la simplicité, la précision des modifications et des objectifs explicites, les développeurs peuvent exploiter la puissance de Claude tout en gardant leur base de code maintenable et fiable.

Essayez d'ajouter CLAUDE.md à votre prochain projet et observez comment votre code itère de façon plus intelligente, et vos revues deviennent plus rares et plus ciblées.