Les 4 règles CLAUDE.md de Karpathy réduisent les erreurs de Claude de 41 % à 11 %. Après 30 bases de code, j'en ai ajouté 8 de plus

Fin janvier 2026, Andrej Karpathy a posté un fil de discussion se plaignant de la façon dont Claude écrit du code. Trois modes d'échec : des hypothèses erronées silencieuses, une complexité excessive, des dommages collatéraux sur du code qu'il n'aurait pas dû toucher.

Forrest Chang a lu le fil, a regroupé les plaintes en 4 règles comportementales dans un seul fichier CLAUDE.md, et l'a déposé sur GitHub. Il a atteint 5 828 étoiles le premier jour. 60 000 favoris en deux semaines. 120 000 étoiles aujourd'hui. Le dépôt mono-fichier à la croissance la plus rapide de 2026.

Ensuite, je l'ai testé sur 30 bases de code pendant 6 semaines.

Les 4 règles fonctionnent. Les erreurs qui se produisaient environ 40 % du temps sont tombées à moins de 3 % sur les tâches qui jouaient sur leurs points forts. Mais le modèle a été conçu pour corriger les erreurs d'écriture de code de janvier.

L'écosystème Claude Code en mai 2026 a des problèmes différents — conflits d'agents, cascades de hooks, conflits de chargement de compétences, workflows multi-étapes qui se brisent entre les sessions.

J'ai donc ajouté 8 règles supplémentaires. Ci-dessous : la liste complète des 12 règles de CLAUDE.md, pourquoi chacune a gagné sa place, et les 4 endroits où le modèle original de Karpathy échoue silencieusement.

Si vous voulez sauter les explications et simplement coller, le fichier complet se trouve à la fin.

Pourquoi c'est important

Le CLAUDE.md de Claude Code est le fichier le plus sous-exploité de toute la pile de codage IA. La plupart des développeurs soit :

• Le traitent comme un dépotoir pour toutes leurs préférences, le gonflant à plus de 4 000 tokens, la conformité tombe à 30 %
• Le sautent complètement et font une invite à chaque fois — 5x de gaspillage de tokens, aucune cohérence entre les sessions
• Copient un modèle une fois et l'oublient. Ça marche pendant deux semaines, puis ça casse silencieusement à mesure que leur base de code évolue

La documentation officielle d'Anthropic est explicite : CLAUDE.md est indicatif. Claude le suit environ 80 % du temps. Au-delà de 200 lignes, la conformité chute fortement car les règles importantes sont noyées dans le bruit.

Le modèle de Karpathy a résolu cela en un fichier, 65 lignes, 4 règles. C'est le plancher.

Le plafond est plus élevé. Avec 8 règles supplémentaires, celles que je vais détailler ci-dessous, vous couvrez non seulement les problèmes d'écriture de code de janvier 2026 dont Karpathy se plaignait, mais aussi les problèmes d'orchestration d'agents de mai 2026 qui n'existaient pas encore lorsque le modèle a été écrit.

Les 4 règles originales

Si vous n'avez pas lu le dépôt de Forrest Chang, le plancher :

**Règle 1 — Réfléchir avant de coder.

**Pas d'hypothèses silencieuses. Énoncez ce que vous supposez. Mettez en évidence les compromis. Demandez avant de deviner. Opposez-vous lorsqu'une approche plus simple existe.

**Règle 2 — Simplicité d'abord.

**Code minimum qui résout le problème. Pas de fonctionnalités spéculatives. Pas d'abstractions pour du code à usage unique. Si un ingénieur senior dirait que c'est trop complexe — simplifiez.

**Règle 3 — Modifications chirurgicales.

**Ne touchez que ce qui est nécessaire. N'"améliorez" pas le code adjacent, les commentaires ou le formatage. Ne refactorisez pas ce qui n'est pas cassé. Respectez le style existant.

**Règle 4 — Exécution axée sur les objectifs.

**Définissez des critères de succès. Bouclez jusqu'à vérification. Ne dites pas à Claude quelles étapes suivre, dites-lui à quoi ressemble le succès et laissez-le itérer.

Ces quatre règles éliminent environ 40 % des modes d'échec que je vois dans les sessions Claude Code non supervisées. Les 60 % restants se situent dans les lacunes ci-dessous.

Les 8 règles que j'ai ajoutées (et pourquoi)

Chacune provient d'un moment réel où les 4 règles de Karpathy ne suffisaient pas. Je vais montrer le moment, puis la règle.

Règle 5 — Ne faites pas faire au modèle un travail non linguistique

Les règles de Karpathy sont muettes sur ce point. Le modèle décide de choses qui devraient être du code déterministe : s'il faut réessayer un appel API, comment router un message, quand escalader. Des décisions différentes chaque semaine. Un if-else instable à 0,003 $ par token.

1## Règle 5 — Utilisez le modèle uniquement pour les décisions de jugement
2Utilisez Claude pour : la classification, la rédaction, le résumé, l'extraction à partir de texte non structuré.
3N'utilisez PAS Claude pour : le routage, les tentatives, la gestion des codes d'état, les transformations déterministes.
4Si un code d'état répond déjà à la question, du code simple répond à la question.

Le moment : Un code qui appelait Claude pour "décider s'il fallait réessayer sur un 503" a fonctionné magnifiquement pendant deux semaines, puis a commencé à dérailler parce que le modèle a commencé à lire le corps de la requête comme contexte pour la décision. La politique de réessai était aléatoire parce que l'invite était aléatoire.

Règle 6 — Budgets de tokens stricts, sans exception

CLAUDE.md sans budgets est un chèque en blanc. Chaque boucle a une chance de dégénérer en un vidage de contexte de 50 000 tokens. Le modèle ne s'arrêtera pas tout seul.

1## Règle 6 — Les budgets de tokens ne sont pas indicatifs
2Budget par tâche : 4 000 tokens.
3Budget par session : 30 000 tokens.
4Si une tâche approche du budget, résumez et recommencez. Ne forcez pas.
5Signaler le dépassement > dépasser silencieusement.

Le moment : Une session de débogage a duré 90 minutes. Le modèle était parfaitement heureux d'itérer sur le même message d'erreur de 8 Ko, perdant progressivement la trace des correctifs déjà essayés. À la fin, il suggérait des correctifs que j'avais rejetés 40 messages plus tôt. Un budget de tokens l'aurait arrêté à la minute 12.

Règle 7 — Révélez les conflits, ne les moyennez pas

Lorsque deux parties de la base de code sont en désaccord, Claude essaie de satisfaire les deux. Le résultat est incohérent.

1## Règle 7 — Révélez les conflits, ne les moyennez pas
2Si deux modèles existants dans la base de code se contredisent, ne les mélangez pas.
3Choisissez-en un (le plus récent / le plus testé), expliquez pourquoi, et signalez l'autre pour nettoyage.
4Un code "moyen" qui satisfait les deux règles est le pire code.

Le moment : Une base de code avait deux modèles de gestion d'erreurs — l'un avec async/await et try/catch explicite, l'autre avec une barrière d'erreur globale. Claude a écrit un nouveau code qui faisait les deux. Des gestionnaires d'erreurs doublés. Il m'a fallu 30 minutes pour comprendre pourquoi les erreurs étaient avalées deux fois.

Règle 8 — Lisez avant d'écrire

La règle "Modifications chirurgicales" de Karpathy dit à Claude de ne pas toucher au code adjacent. Elle ne dit pas à Claude de comprendre d'abord le code adjacent. Sans cela, Claude écrit un nouveau code qui entre en conflit avec le code existant 30 lignes plus loin.

1## Règle 8 — Lisez avant d'écrire
2Avant d'ajouter du code dans un fichier, lisez les exports du fichier, l'appelant immédiat, et toutes les utilitaires partagés évidents.
3Si vous ne comprenez pas pourquoi le code existant est structuré comme il l'est, demandez avant d'y ajouter quoi que ce soit.
4"Ça a l'air orthogonal" est l'expression la plus dangereuse dans cette base de code.

Le moment : Claude a ajouté une fonction à côté d'une fonction identique existante qu'il n'avait pas lue. Les deux fonctions faisaient la même chose. La nouvelle a pris le dessus à cause de l'ordre des imports. L'ancienne était la source de vérité depuis 6 mois.

Règle 9 — Les tests ne sont pas optionnels, mais ils ne sont pas le but

L'exécution axée sur les objectifs de Karpathy implique des tests comme critères de succès. En pratique, Claude traite "les tests passent" comme le seul objectif, et écrit du code qui réussit des tests superficiels tout en cassant tout le reste.

1## Règle 9 — Les tests vérifient l'intention, pas seulement le comportement
2Chaque test doit encoder POURQUOI le comportement est important, pas seulement CE QU'il fait.
3Un test comme `expect(getUserName()).toBe('John')` ne vaut rien si la fonction prend un ID codé en dur.
4Si vous ne pouvez pas écrire un test qui échouerait lorsque la logique métier change, la fonction est erronée.

Le moment : Claude a écrit 12 tests pour une fonction d'authentification. Tous réussis. L'authentification était cassée en production. Les tests testaient que la fonction renvoyait quelque chose, pas si elle renvoyait la bonne chose. La fonction réussissait parce qu'elle renvoyait une constante.

Règle 10 — Les opérations de longue durée nécessitent des points de contrôle

Le modèle de Karpathy suppose des interactions uniques. Le vrai travail avec Claude Code est multi-étapes — refactorisation sur 20 fichiers, construction de fonctionnalités sur une session, débogage sur plusieurs commits. Sans points de contrôle, un mauvais virage fait perdre toute progression.

1## Règle 10 — Point de contrôle après chaque étape significative
2Après avoir terminé chaque étape d'une tâche multi-étapes : résumez ce qui a été fait, ce qui est vérifié, ce qui reste.
3Ne continuez pas à partir d'un état que vous ne pouvez pas me décrire.
4Si vous perdez le fil, arrêtez-vous et reformulez.

Le moment : Une refactorisation en 6 étapes a mal tourné à l'étape 4. Au moment où je l'ai remarqué, Claude avait également fait les étapes 5 et 6 sur l'état cassé. Démêler le tout a pris plus de temps que de tout refaire. Les points de contrôle l'auraient rattrapé à l'étape 4.

Règle 11 — La convention prime sur la nouveauté

Dans une base de code avec des modèles établis, Claude aime introduire les siens. Même lorsque sa façon est "meilleure", l'introduction de deux modèles est pire que l'un ou l'autre modèle seul.

1## Règle 11 — Respectez les conventions de la base de code, même si vous n'êtes pas d'accord
2Si la base de code utilise snake_case et que vous préférez camelCase : snake_case.
3Si la base de code utilise des composants à base de classes et que vous préférez les hooks : à base de classes.
4Le désaccord est une conversation séparée. Dans la base de code, la conformité > le goût.
5Si vous pensez sincèrement que la convention est nuisible, signalez-la. Ne la bifurquez pas silencieusement.

Le moment : Claude a introduit des hooks React dans une base de code de composants à base de classes. Ils fonctionnaient. Ils ont également cassé les modèles de test de la base de code, qui supposaient componentDidMount. Une demi-journée pour supprimer et réécrire.

Règle 12 — Échouez visiblement, pas silencieusement

Les échecs les plus coûteux de Claude sont ceux qui ressemblent à un succès. Une fonction "marche" mais renvoie des données erronées. Une migration "se termine" mais a sauté 30 enregistrements. Un test "réussit" mais seulement parce que l'assertion était erronée.

1## Règle 12 — Échouez fort
2Si vous ne pouvez pas être sûr que quelque chose a fonctionné, dites-le explicitement.
3"Migration terminée" est faux si 30 enregistrements ont été sauté silencieusement.
4"Tests réussis" est faux si vous en avez sauté un seul.
5"Fonctionnalité fonctionne" est faux si vous n'avez pas vérifié le cas limite que j'ai demandé.
6Par défaut, révélez l'incertitude, ne la cachez pas.

Le moment : Claude a dit qu'une migration de base de données "s'est terminée avec succès". Elle avait silencieusement sauté 14 % des enregistrements qui rencontraient une violation de contrainte. Le saut était enregistré mais pas signalé. Problème découvert 11 jours plus tard lorsque les rapports ont commencé à sembler erronés.

Les chiffres

J'ai suivi le même ensemble de 50 tâches représentatives sur 30 bases de code pendant 6 semaines. Trois configurations :

Taux d'erreur = tâche nécessitant une correction ou une réécriture pour correspondre à l'intention. Compteurs : hypothèse erronée silencieuse, sur-ingénierie, dommage collatéral, échec silencieux, violation de convention, moyenne de conflit, point de contrôle manqué.

Conformité = fréquence à laquelle Claude a appliqué visiblement la règle pertinente lorsqu'elle était applicable.

Le résultat intéressant n'est pas la baisse spectaculaire de 41 % à 3 %. C'est que le passage de 4 à 12 règles n'a presque pas ajouté de surcharge de conformité (78 % -> 76 %) mais a réduit le taux d'erreur de 8 points supplémentaires. Les nouvelles règles couvrent des modes d'échec que les 4 originales n'abordaient pas — elles ne se disputent pas le même budget d'attention.

Où le modèle de Karpathy échoue silencieusement

Quatre endroits où le modèle original à 4 règles ne suffit pas, même avant d'ajouter de nouvelles règles :

**1. Tâches d'agent de longue durée.

*Les règles de Karpathy ciblent le moment où Claude écrit du code. Elles sont muettes sur ce qui se passe lorsque Claude exécute* un pipeline multi-étapes. Pas de règle de budget. Pas de règle de point de contrôle. Pas de règle "échouez fort". Les pipelines dérivent.

**2. Cohérence multi-bases de code.

**"Respectez le style existant" suppose un seul style. Dans un monorepo avec 12 services, Claude doit choisir quel style. Les règles originales ne lui disent pas comment. Il choisit au hasard ou fait la moyenne.

**3. Qualité des tests.

*L'exécution axée sur les objectifs traite "les tests passent" comme un succès. Ne dit pas que les tests doivent être significatifs*. Le résultat est des tests qui ne testent rien d'utile mais rendent Claude confiant.

**4. Production vs prototype.

**Les mêmes 4 règles qui protègent le code de production de la sur-ingénierie ralentissent également les prototypes qui ont légitimement besoin de 100 lignes d'échafaudage spéculatif pour trouver une direction. La "Simplicité d'abord" de Karpathy tire trop sur le code en phase précoce.

Les 8 règles ajoutées ne remplacent pas les 4 de Karpathy. Elles comblent les lacunes là où son modèle, janvier 2026, codage de type autocomplétion, ne correspond pas au travail de mai 2026, piloté par agent, multi-étapes et multi-bases de code.

Ce qui n'a pas fonctionné

Des choses que j'ai essayées avant de me fixer sur les 12 règles :

• Ajouter des règles que j'avais vues sur Reddit / X. La plupart étaient soit des reformulations des 4 de Karpathy avec des mots différents, soit des règles spécifiques à un domaine ("utilisez toujours les classes Tailwind") qui ne se généralisent pas. Supprimées.
• Plus de 12 règles. J'ai testé jusqu'à 18. La conformité est passée de 76 % à 52 % au-delà de 14 règles. La limite des 200 lignes est réelle. Au-delà, Claude commence à faire du pattern-matching sur "les règles existent" sans vraiment les lire.
• Des règles qui dépendent d'outils qui pourraient ne pas exister. "Utilisez toujours eslint" échoue lorsque eslint n'est pas installé. La règle échoue silencieusement. Remplacé par des formulations agnostiques en termes de capacités : "respectez le style imposé par la base de code" au lieu de "utilisez eslint."
• Des exemples dans CLAUDE.md au lieu de règles. Les exemples sont plus lourds que les règles. Trois exemples coûtent autant de contexte qu'environ 10 règles et Claude se surajuste à eux. Les règles sont abstraites, les exemples sont spécifiques. Utilisez des règles.
• "Soyez prudent" / "réfléchissez bien" / "concentrez-vous vraiment." Pur bruit. La conformité avec ceux-ci est tombée à environ 30 % car ils ne sont pas testables. Remplacé par des impératifs concrets ("énoncez les hypothèses explicitement").
• Dire à Claude d'être "senior." Ne fonctionne pas. Claude pense déjà qu'il est senior. L'écart de conformité est entre penser et faire. Les règles impératives comblent l'écart ; les invites d'identité non.

Le fichier CLAUDE.md complet à 12 règles (prêt à copier-coller)

1# CLAUDE.md — Modèle à 12 règles
2
3Ces règles s'appliquent à chaque tâche de ce projet sauf dérogation explicite.
4Biais : prudence plutôt que rapidité sur les travaux non triviaux. Utilisez votre jugement sur les tâches triviales.
5
6## Règle 1 — Réfléchir avant de coder
7Énoncez les hypothèses explicitement. En cas d'incertitude, demandez plutôt que de deviner.
8Présentez plusieurs interprétations en cas d'ambiguïté.
9Opposez-vous lorsqu'une approche plus simple existe.
10Arrêtez-vous lorsque vous êtes confus. Nommez ce qui n'est pas clair.
11
12## Règle 2 — Simplicité d'abord
13Code minimum qui résout le problème. Rien de spéculatif.
14Pas de fonctionnalités au-delà de ce qui a été demandé. Pas d'abstractions pour du code à usage unique.
15Test : un ingénieur senior dirait-il que c'est trop complexe ? Si oui, simplifiez.
16
17## Règle 3 — Modifications chirurgicales
18Ne touchez que ce qui est nécessaire. Ne nettoyez que votre propre désordre.
19N'"améliorez" pas le code adjacent, les commentaires ou le formatage.
20Ne refactorisez pas ce qui n'est pas cassé. Respectez le style existant.
21
22## Règle 4 — Exécution axée sur les objectifs
23Définissez des critères de succès. Bouclez jusqu'à vérification.
24Ne suivez pas d'étapes. Définissez le succès et itérez.
25Des critères de succès solides vous permettent de boucler indépendamment.
26
27## Règle 5 — Utilisez le modèle uniquement pour les décisions de jugement
28Utilisez-moi pour : la classification, la rédaction, le résumé, l'extraction.
29N'utilisez PAS moi pour : le routage, les tentatives, les transformations déterministes.
30Si du code peut répondre, le code répond.
31
32## Règle 6 — Les budgets de tokens ne sont pas indicatifs
33Par tâche : 4 000 tokens. Par session : 30 000 tokens.
34Si vous approchez du budget, résumez et recommencez.
35Signalez le dépassement. Ne dépassez pas silencieusement.
36
37## Règle 7 — Révélez les conflits, ne les moyennez pas
38Si deux modèles se contredisent, choisissez-en un (le plus récent / le plus testé).
39Expliquez pourquoi. Signalez l'autre pour nettoyage.
40Ne mélangez pas des modèles contradictoires.
41
42## Règle 8 — Lisez avant d'écrire
43Avant d'ajouter du code, lisez les exports, les appelants immédiats, les utilitaires partagés.
44"Ça a l'air orthogonal" est dangereux. Si vous n'êtes pas sûr pourquoi le code est structuré d'une certaine manière, demandez.
45
46## Règle 9 — Les tests vérifient l'intention, pas seulement le comportement
47Les tests doivent encoder POURQUOI le comportement est important, pas seulement CE QU'il fait.
48Un test qui ne peut pas échouer lorsque la logique métier change est erroné.
49
50## Règle 10 — Point de contrôle après chaque étape significative
51Résumez ce qui a été fait, ce qui est vérifié, ce qui reste.
52Ne continuez pas à partir d'un état que vous ne pouvez pas décrire.
53Si vous perdez le fil, arrêtez-vous et reformulez.
54
55## Règle 11 — Respectez les conventions de la base de code, même si vous n'êtes pas d'accord
56La conformité > le goût dans la base de code.
57Si vous pensez sincèrement qu'une convention est nuisible, signalez-la. Ne bifurquez pas silencieusement.
58
59## Règle 12 — Échouez fort
60"Terminé" est faux si quoi que ce soit a été sauté silencieusement.
61"Tests réussis" est faux si l'un d'eux a été sauté.
62Par défaut, révélez l'incertitude, ne la cachez pas.

Enregistrez sous CLAUDE.md à la racine de votre dépôt. Ajoutez des règles spécifiques au projet en dessous des 12 (pile, commandes de test, modèles d'erreur). Ne dépassez pas 200 lignes au total, au-delà, la conformité chute.

Comment installer

Deux étapes :

1# 1. Ajoutez les 4 règles de base de Karpathy à votre CLAUDE.md
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. Collez les règles 5 à 12 de cet article en dessous

Enregistrez à la racine de votre dépôt. Le >> est important, il ajoute à votre CLAUDE.md existant au lieu d'écraser les règles spécifiques au projet que vous avez déjà.

Le modèle mental

CLAUDE.md n'est pas une liste de souhaits. C'est un contrat comportemental qui élimine des modes d'échec spécifiques que vous avez observés.

Chaque règle doit répondre à : quelle erreur cela empêche-t-il ?

Les 4 de Karpathy empêchent les modes d'échec qu'il a vus en janvier 2026 : hypothèses silencieuses, sur-ingénierie, dommages collatéraux, critères de succès faibles. Ils sont fondamentaux. Ne les sautez pas.

Les 8 que j'ai ajoutées empêchent les modes d'échec apparus en mai 2026 : boucles d'agents sans budgets, tâches multi-étapes sans points de contrôle, tests qui ne testent pas, succès silencieux cachant des échecs silencieux. Ils sont additifs.

Votre kilométrage peut varier. Si vous n'exécutez pas de pipelines multi-étapes, la règle 10 n'a pas d'importance. Si votre base de code a un style cohérent imposé par le linting, la règle 11 est redondante. Lisez les 12, gardez celles qui correspondent à des erreurs que vous avez réellement commises, laissez tomber le reste.

Un CLAUDE.md à 6 règles adapté à vos véritables modes d'échec bat un CLAUDE.md à 12 règles avec 6 règles dont vous n'aurez jamais besoin.

F I N

Le fil de janvier 2026 de Karpathy était une plainte. Forrest Chang l'a transformé en 4 règles. 120 000 développeurs ont mis une étoile au résultat. La plupart d'entre eux utilisent encore 4 règles aujourd'hui.

Le modèle s'est amélioré. L'écosystème a changé. Agents multi-étapes, cascades de hooks, chargement de compétences, travail multi-bases de code — rien de tout cela n'existait lorsque Karpathy a écrit son fil. Les 4 règles ne les abordent pas. Elles ne sont pas fausses ; elles sont incomplètes.

8 règles supplémentaires. 6 semaines de tests sur 30 bases de code. Taux d'erreur de 41 % à 3 %.

Mettez ceci en favori et collez les 12 règles dans votre CLAUDE.md ce soir. Republiez si cela vous a évité une semaine de mauvaises directions de Claude.

Telegram pour des astuces quotidiennes d'optimisation Claude :

*https://t.me/+_ZWrQN7GuDA3ZDEy*