CLAUDE.md façon Karpathy : analyse et version FR

TL;DR

Le fameux "CLAUDE.md de Karpathy" n'est pas un repo officiel de Karpathy. C'est forrestchang/andrej-karpathy-skills, un fichier unique qui condense ses observations publiques sur les défauts de codage des LLM.
Quatre principes : Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution.
Karpathy lui-même publie ses propres CLAUDE.md dans ses repos perso (ex. karpathy/llm-council), beaucoup plus orientés architecture projet.
Transposable à toute stack. Le piège : ne pas le copier-coller tel quel sur un projet d'équipe sans le couper, parce qu'il est volontairement prudent.

Qui parle, et pourquoi ça intéresse autant

Andrej Karpathy est l'ancien directeur de l'IA chez Tesla, ancien membre fondateur d'OpenAI, et créateur d'Eureka Labs. Sa bio GitHub publique se résume aujourd'hui à "I like to train Deep Neural Nets on large datasets", avec Stanford comme affiliation visible. Il cumule plus de 183 000 followers et ses repos pédagogiques font référence (nanoGPT, nanochat, llm.c).

Quand il poste une observation sur la manière dont les LLM dérapent quand ils codent, la communauté traduit immédiatement ça en outils. C'est ce qui est arrivé avec le repo forrestchang/andrej-karpathy-skills, qui distille ses remarques en un seul fichier CLAUDE.md. Le repo affiche environ 127 000 étoiles, sous licence MIT.

Important : ce fichier n'est pas écrit par Karpathy. C'est une réécriture par Forrest Chang à partir de ses prises de parole publiques. Le titre "CLAUDE.md de Karpathy" est une étiquette communautaire, pas une signature.

Ce que contient le fichier

Le CLAUDE.md du repo est organisé en sections : The Problems, The Solution, The Four Principles in Detail, Install, Using with Cursor, Key Insight, How to Know It's Working, Customization, Tradeoff Note, License.

Le cœur tient en quatre principes courts.

Principe	Idée centrale
Think Before Coding	Énoncer les hypothèses, ne pas masquer la confusion, demander avant d'inventer
Simplicity First	Le minimum de code qui résout le problème, rien de spéculatif
Surgical Changes	Toucher uniquement ce qui doit l'être, garder le style existant
Goal-Driven Execution	Définir un critère de succès vérifiable, boucler jusqu'à validation

Le repo précise aussi un avertissement honnête : "These guidelines bias toward caution over speed. For trivial tasks, use judgment."

À côté, le CLAUDE.md que Karpathy écrit pour ses propres projets (cf. karpathy/llm-council, environ 18 700 étoiles, projet décrit comme "99% vibe coded") est très différent. Il s'organise en Project Overview, Architecture, Key Design Decisions, Common Gotchas, Data Flow Summary. Autrement dit, Karpathy lui-même utilise CLAUDE.md comme un brief d'architecture, pas comme une charte de comportement.

Les 5 principes vraiment transférables

Indépendamment du stack ou de l'équipe, voici ce qui résiste au copier-coller.

1. Forcer l'agent à expliciter ses hypothèses. Le défaut numéro un des LLM en coding, c'est d'inventer une API qui n'existe pas plutôt que de demander. Une ligne du type "si quelque chose est ambigu, pose la question avant d'écrire du code" change radicalement le comportement.

2. Bannir la spéculation. Pas de "j'ajoute aussi cette fonction au cas où", pas de refacto opportuniste, pas de tests "pour couvrir d'autres scénarios" non demandés. C'est le principe qui fait gagner le plus de temps en revue.

3. Préserver le diff. Demander à l'agent de modifier le strict minimum, en gardant le style et la structure existante. Très utile sur les vieux codebases où chaque PR risque d'embarquer du formatage involontaire.

4. Critère de succès vérifiable. Avant d'écrire du code, l'agent doit dire comment il saura que c'est fini : un test qui passe, une commande qui retourne tel exit code, une sortie attendue. Sans ça, il déclare victoire trop tôt.

5. Mélanger comportement et architecture. Inspirez-vous des deux niveaux. Un premier bloc qui dit comment l'agent doit travailler, un second qui décrit où il travaille (modules, conventions, gotchas).

Une version FR adaptée

Voici un modèle court à coller à la racine d'un projet francophone. Il reprend les principes Karpathy mais en français direct, sans tic de traduction.

# CLAUDE.md

## Comment tu travailles

- Énonce tes hypothèses avant d'écrire du code. Si un nom de fonction, un type ou une route te semble incertain, demande plutôt que d'inventer.
- Écris le minimum de code qui résout le problème. Pas de fonction "au cas où", pas de tests non demandés, pas de refacto opportuniste.
- Touche uniquement ce qui doit l'être. Garde le style et l'indentation existants. Ne renomme rien sans raison.
- Avant de commencer, dis comment tu sauras que c'est fini (test, commande, exit code, sortie attendue). Boucle jusqu'à validation.
- Pour une tâche triviale (typo, renommage local, changement d'une constante), saute ces étapes.

## Le projet

Stack : Next.js 14 (App Router), TypeScript strict, Tailwind, MDX pour le contenu.

Architecture clé :
- src/app : pages et layouts
- src/components : composants React, un par fichier
- src/lib : utilitaires purs, pas d'effets de bord
- content/fr et content/en : contenu MDX bilingue

Pièges connus :
- Pas de SSR ni d'API routes (output: 'export'). Les routes dynamiques doivent toutes implémenter generateStaticParams.
- Toute modification visible déclenche la mise à jour de dateModified dans le frontmatter et de lastModified dans lib/metadata.ts.

## Commandes utiles

- npm run dev : serveur de dev
- npm run lint && npm run type-check : à passer avant chaque commit
- npm run build : build statique de production

Ce qui ne se transpose pas

Trois angles morts à connaître avant de tout copier.

Le contexte de Karpathy est solo, expérimental, vibe coding. Son llm-council est explicitement décrit comme "99% vibe coded" sur un weekend. Sa version est optimisée pour un humain seul qui veut un agent prudent. En équipe, "ne touche que ce qui est strictement nécessaire" peut bloquer des refactos légitimes.

Le biais prudent ralentit. Le fichier lui-même reconnaît qu'il sacrifie la vitesse à la sécurité. Sur un prototype jetable ou un POC d'une journée, ces garde-fous deviennent contre-productifs.

Pas de section qualité ni sécurité. Le CLAUDE.md communautaire ne dit rien sur les tests, l'accessibilité, les secrets, la couverture, le lint. Sur un projet produit, c'est précisément ce qui doit être ajouté en plus.

Verdict

Le mérite du "CLAUDE.md façon Karpathy" est moins le fichier lui-même que la pratique qu'il a rendue visible : un fichier court, en racine, qui code le comportement attendu de l'agent. À reprendre comme socle, à compléter ensuite avec votre architecture, vos commandes et vos règles qualité spécifiques. Pour aller plus loin, voir le guide CLAUDE.md complet et les templates de démarrage.

Ressources

Repo forrestchang/andrej-karpathy-skills : https://github.com/forrestchang/andrej-karpathy-skills (ouvre un nouvel onglet)
CLAUDE.md de Karpathy sur llm-council : https://github.com/karpathy/llm-council/blob/master/CLAUDE.md (ouvre un nouvel onglet)
Profil GitHub de Karpathy : https://github.com/karpathy (ouvre un nouvel onglet)