Titre original : Les 4 règles de CLAUDE de Karpathy réduisent les erreurs de Claude de 41% à 11%. Après 30 bases de code, j’en ai ajouté 8 de plus
Auteur original : @Mnilax
Compilation : Peggy, BlockBeats

Préface : En janvier 2026, Andrej Karpathy a critiqué la façon dont Claude écrivait du code, ce qui a mis en lumière un fichier apparemment mineur mais extrêmement crucial dans le flux de travail de programmation AI : CLAUDE.md. Forrest Chang a ensuite organisé ces problèmes en 4 règles de comportement, visant à limiter les erreurs courantes de Claude lors de la programmation : hypothèses silencieuses, sur-ingénierie, dommages involontaires au code non concerné, et absence de critères clairs de réussite.

Mais quelques mois plus tard, le contexte d’utilisation de Claude Code ne se limitait plus à « faire écrire un morceau de code par le modèle ». Avec la normalisation des agents à étapes multiples, des déclenchements en chaîne via hook, le chargement de compétences et la collaboration entre plusieurs bases de code, de nouveaux modes d’échec sont apparus : dérapages du modèle lors de longues tâches, validation de tests sans vérification de la logique réelle, saut silencieux d’erreurs après migration, mélange erroné de styles de code différents.

L’auteur de cet article a testé 30 bases de code en 6 semaines, et a ajouté 8 règles supplémentaires à la base de 4 règles de Karpathy, pour couvrir les nouveaux problèmes liés à la transition de la complétion unique à la collaboration en mode agent.

Voici le texte original :

Fin janvier 2026, Andrej Karpathy a publié une série de tweets critiquant la façon dont Claude écrivait du code. Il a identifié trois types de problèmes typiques : faire des hypothèses erronées sans explication, une complexification excessive, et des dommages non intentionnels au code qui ne devrait pas être modifié.

Forrest Chang a vu cette série de tweets, a organisé ces plaintes en 4 règles de comportement, les a écrites dans un fichier CLAUDE.md séparé, et l’a publié sur GitHub. Ce projet a obtenu 5 828 étoiles dès le premier jour, a été mis en favori 60 000 fois en deux semaines, et compte aujourd’hui 120 000 étoiles, devenant ainsi le dépôt de code monofichier à la croissance la plus rapide en 2026.

Ensuite, j’ai testé cet outil sur 30 bases de code en 6 semaines.

Ces 4 règles sont effectivement efficaces. Les erreurs qui apparaissaient auparavant avec une probabilité d’environ 40 %, ont été réduites à moins de 3 % dans les tâches où ces règles s’appliquent. Mais le problème est que ce modèle a été initialement conçu pour corriger les erreurs survenues lors de la programmation par Claude en janvier.

En mai 2026, le contexte de l’écosystème Claude Code avait changé : conflits entre agents, déclenchements en chaîne via hook, conflits lors du chargement de compétences, interruptions dans les flux de travail multi-étapes entre sessions.

J’ai donc ajouté 8 autres règles. Voici la version complète du fichier CLAUDE.md avec 12 règles : pourquoi chaque règle vaut la peine d’être ajoutée, et où le modèle Karpathy échoue silencieusement dans ses 4 versions initiales.

Si vous souhaitez sauter les explications et copier directement, le fichier complet est en fin d’article.

Pourquoi c’est important

Le fichier CLAUDE.md de Claude Code est le document le plus sous-estimé de toute la stack technique de programmation AI. La plupart des développeurs commettent trois erreurs principales :

Premièrement, le considérer comme une corbeille à préférences, y mettre toutes leurs habitudes, ce qui fait que le fichier dépasse 4000 tokens, et le taux de conformité chute à 30 %.

Deuxièmement, ne pas l’utiliser du tout, en relançant à chaque fois le prompt. Cela entraîne un gaspillage de 5 fois plus de tokens, et un manque de cohérence entre sessions.

Troisièmement, copier un modèle une fois et ne plus y toucher. Il peut fonctionner deux semaines, mais avec l’évolution du code, il finira par devenir obsolète sans que vous ne vous en rendiez compte.

La documentation officielle d’Anthropic précise que CLAUDE.md est essentiellement suggestif. Claude suit environ 80 % des recommandations. Au-delà de 200 lignes, le taux de conformité chute nettement, car les règles importantes sont noyées dans le bruit.

Le modèle de Karpathy résout ce problème : un fichier, 65 lignes, 4 règles. C’est le minimum.

Mais le plafond peut être encore plus haut. En ajoutant ces 8 règles, on ne couvre pas seulement les problèmes de programmation évoqués par Karpathy en janvier 2026, mais aussi ceux liés à l’orchestration des agents, apparus en mai 2026 — des problèmes qui n’existaient pas lors de la rédaction du modèle initial.

Les 4 règles originales

Si vous n’avez pas encore vu le dépôt de Forrest Chang, commencez par cette version de base :

Règle 1 : Réfléchir avant de coder.

Ne pas faire d’hypothèses silencieuses. Expliquer ses hypothèses, exposer les compromis. Poser des questions avant de supposer. Lorsqu’une solution plus simple existe, la proposer activement.

Règle 2 : Prioriser la simplicité.
Utiliser le code minimal pour résoudre le problème. Éviter d’ajouter des fonctionnalités imaginaires. Ne pas créer d’abstractions pour du code ponctuel. Si un ingénieur expérimenté trouve cela trop complexe, il faut simplifier.

Règle 3 : Modifier comme un chirurgien.
Ne changer que ce qui est nécessaire. Ne pas « optimiser » le code, les commentaires ou le format sans raison. Ne pas refactoriser ce qui ne pose pas problème. Respecter le style existant.

Règle 4 : Agir en fonction de l’objectif.
Définir d’abord le critère de réussite, puis itérer jusqu’à validation. Ne pas dire à Claude comment faire chaque étape, mais lui indiquer le résultat attendu, pour qu’il itère lui-même.

Ces 4 règles permettent de réduire environ 40 % des modes d’échec observés lors de sessions de programmation Claude non supervisées. Les 60 % restants se nichent dans ces zones d’ombre.

Les 8 règles supplémentaires que j’ai ajoutées, et pourquoi

Chaque règle provient d’un contexte précis : les 4 règles de Karpathy ne suffisaient plus. Je vais d’abord décrire ce contexte, puis donner la règle correspondante.

Règle 5 : Éviter que le modèle fasse du travail non linguistique

Claude peut traiter : classification, rédaction, résumé, extraction d’informations à partir de textes non structurés.
Ne pas lui faire gérer : routage, retries, gestion de codes d’état, transformations déterministes.
Si un code d’état répond déjà à la question, laisser le faire par du code classique.

Les règles de Karpathy ne couvraient pas ce point. Le modèle a commencé à décider de gérer des aspects qui devraient relever de la logique déterministe : relancer une API, router un message, décider quand faire une mise à jour. Résultat : des décisions incohérentes, facturées à 0,003 USD par token, avec une instabilité chronique.

Exemple : un bout de code qui appelle Claude pour « décider s’il faut réessayer en cas de 503 ». Au début, ça fonctionnait bien, pendant deux semaines. Puis, ça s’est mis à devenir instable, car le prompt incluait aussi le corps de la requête. La stratégie de retry devenait aléatoire, car le contexte de la requête était lui aussi aléatoire.

Règle 6 : Fixer un budget strict en tokens, sans exception

Budget par tâche : 4 000 tokens.
Budget par session : 30 000 tokens.
Si une tâche approche la limite, faire un résumé de l’état actuel, puis recommencer.
Ne pas insister au-delà. Exposer clairement le dépassement de budget, plutôt que de le laisser se faire en silence.

Un fichier CLAUDE.md sans limite de tokens, c’est comme un chèque en blanc. Chaque boucle peut déraper, accumuler 50 000 tokens de contexte. Le modèle ne s’arrête pas de lui-même.

Exemple : une session de débogage de 90 minutes, où le modèle tourne en boucle sur un même fragment de 8 Ko d’erreurs, oubliant ce qu’il a déjà essayé. À la fin, il propose 40 solutions que j’avais déjà rejetées. Avec un budget, la session aurait été arrêtée à la 12e minute.

Règle 7 : Exposer les conflits, ne pas faire d’approximation

Si deux modes dans la codebase sont en contradiction, ne pas tenter de les fusionner. Choisir l’un ou l’autre, en justifiant le choix, et marquer l’autre pour nettoyage futur.
La « moyenne » des deux modes est la pire des solutions.

Quand deux parties du code sont en conflit, Claude essaie de satisfaire les deux, produisant un code incohérent.

Exemple : un code qui mélange deux stratégies de gestion d’erreurs — une avec async/await et try/catch, l’autre avec une erreur globale. Résultat : erreur gérée deux fois, ce qui complique la compréhension. Il a fallu 30 minutes pour comprendre pourquoi.

Règle 8 : Lire avant d’écrire

Avant d’ajouter du code dans un fichier, lire ses exports, ses appels directs, et tout outil partagé apparent.
Si vous ne comprenez pas pourquoi le code est organisé ainsi, posez des questions, ne rajoutez pas sans réflexion.
« Je ne vois pas le rapport » est la phrase la plus dangereuse dans un code.

L’« intervention chirurgicale » de Karpathy indique à Claude de ne pas modifier le code adjacent, mais ne lui dit pas de le comprendre d’abord. Sans cette étape, Claude peut écrire du code en conflit avec celui existant depuis 6 mois.

Exemple : Claude ajoute une nouvelle fonction identique à une fonction existante, sans lire l’originale. Deux fonctions qui font la même chose, mais la nouvelle écrase l’ancienne à cause de l’ordre d’import, alors que cette dernière était la référence depuis 6 mois.

Règle 9 : Les tests ne sont pas optionnels, mais leur but n’est pas la réussite

Chaque test doit expliquer « pourquoi ce comportement est important », pas seulement « ce qu’il fait ».
Un test comme expect(getUserName()).toBe(‘John’) n’a pas de valeur si la fonction reçoit un ID codé en dur.
Si vous ne pouvez pas écrire un test qui échoue lors d’un changement de logique, la fonction est probablement erronée.

« Agir en fonction de l’objectif » de Karpathy suppose que les tests définissent la réussite. En pratique, Claude considère souvent la validation par test comme la seule métrique, produisant du code qui passe des tests superficiels mais qui détruit d’autres parties.

Exemple : Claude écrit 12 tests pour une fonction d’authentification, tous passés. Mais la logique en production est cassée, car ces tests ne vérifient que si la fonction retourne quelque chose, pas si c’est correct. La fonction passe parce qu’elle retourne une constante.

Règle 10 : Vérifier à chaque étape dans les opérations longues

Dans une tâche à étapes multiples, après chaque étape, faire un résumé, vérifier ce qui a été fait, ce qui reste.
Ne pas continuer à partir d’un état que vous ne pouvez pas reformuler clairement.
Si vous vous perdez, arrêter, reformuler l’état actuel.

Le modèle par défaut de Karpathy suppose une interaction unique. Mais en réalité, la programmation Claude implique souvent plusieurs étapes : refactoriser 20 fichiers, construire une fonctionnalité dans une session, déboguer sur plusieurs commits. Sans checkpoints, une erreur à une étape peut faire perdre tout le progrès.

Exemple : une refactorisation en 6 étapes, où la 4e échoue. Si je ne m’en rends pas compte, Claude continue à faire la 5e et la 6e sur une base erronée. Il faut des checkpoints pour détecter l’erreur à la 4e étape.

Règle 11 : La convention prime sur l’innovation

Si la base de code utilise snake_case, utilisez-le aussi, même si vous préférez camelCase.
Si la base utilise des composants en class, utilisez-les aussi, même si vous préférez hooks.
La cohérence interne prime sur les préférences personnelles. Si une convention est nuisible, la signaler explicitement, ne pas créer une divergence silencieuse.

Dans un code existant avec une norme établie, Claude aime introduire ses propres styles. Même si c’est « meilleur », cela crée une incohérence qui peut casser des tests ou des comportements existants.

Exemple : dans un projet React basé sur des classes, Claude introduit des hooks. Ça fonctionne, mais cela casse des tests qui dépendent de componentDidMount. Il faut tout réécrire.

Règle 12 : La défaillance explicite prime sur la défaillance silencieuse

Si vous n’êtes pas sûr qu’une étape a réussi, dites-le clairement.
Si 30 enregistrements sont ignorés silencieusement, on ne peut pas dire « migration terminée ».
Si vous sautez un test, on ne peut pas dire « test réussi ».
Si vous n’avez pas vérifié les cas limites, on ne peut pas dire « fonctionnalité opérationnelle ».
Exposez explicitement l’incertitude, ne la cachez pas.

Les échecs les plus coûteux de Claude sont souvent ceux qui semblent réussir : une fonction qui « tourne » mais retourne des données erronées, une migration « terminée » mais qui a ignoré 14 % des erreurs, un test « passé » mais basé sur une assertion fausse.

Exemple : Claude annonce une migration « réussie », mais a en réalité ignoré silencieusement 14 % des enregistrements qui déclenchaient des erreurs. La problématique n’est détectée que 11 jours plus tard, quand les rapports deviennent anormaux.

Résultats

En 6 semaines, j’ai suivi un groupe de 50 tâches représentatives, couvrant 30 bases de code, avec 3 configurations différentes.

Le taux d’erreur correspond à la proportion de tâches nécessitant correction ou réécriture pour respecter l’intention initiale. Inclut : hypothèses silencieuses, sur-ingénierie, dommages non liés, échecs silencieux, violation de conventions, compromis conflictuels, omission de checkpoints.

Le taux de conformité indique la probabilité qu’une règle soit appliquée de manière explicite lorsque pertinente.

Les résultats les plus intéressants ne sont pas seulement la réduction de l’erreur de 41 % à 3 %. En étendant le cadre de 4 à 12 règles, la charge de conformité n’a pas augmenté : elle est passée de 78 % à 76 %, mais l’erreur a chuté de 8 points de pourcentage. Les nouvelles règles couvrent des modes d’échec non traités par les 4 règles initiales, sans empiéter sur le même budget d’attention.

Où le modèle Karpathy échoue silencieusement

Même sans ajouter de nouvelles règles, le modèle initial de 4 règles est insuffisant dans au moins 4 cas.

Premier : les tâches d’agent à long terme.
Les règles de Karpathy ciblent surtout le moment où Claude écrit du code. Mais que se passe-t-il quand Claude exécute un pipeline à étapes multiples ? Le modèle ne prévoit pas de budget, ni de checkpoints, ni de gestion explicite des échecs. Le pipeline dérive lentement.

Deuxième : cohérence entre plusieurs bases de code.
« Respecter le style existant » suppose une seule norme. Mais dans un monorepo avec 12 services, Claude doit choisir laquelle appliquer. Le modèle ne donne pas de règle pour cela. Il peut choisir au hasard ou mélanger plusieurs styles.

Troisième : qualité des tests.
« Agir en fonction de l’objectif » suppose que les tests définissent la réussite. Mais souvent, Claude écrit des tests qui ne vérifient que si quelque chose est retourné, pas si c’est correct. La validation est superficielle.

Quatrième : différence entre environnement de production et prototype.
Les 4 règles peuvent empêcher la sur-ingénierie en production, mais ralentissent le prototypage. Parfois, il faut 100 lignes pour explorer une idée. La règle « Prioriser la simplicité » peut être trop stricte en phase initiale.

Ces 8 règles supplémentaires ne remplacent pas les 4 originales de Karpathy, mais comblent leurs lacunes : le modèle initial visait la complétion automatique, alors qu’en mai 2026, Claude fonctionne dans un environnement piloté par agents, à plusieurs étapes, avec plusieurs bases de code. Les enjeux ne sont pas les mêmes.

Quelles méthodes ont échoué

Avant de finaliser ces 12 règles, j’ai testé d’autres approches.

Ajouter des règles trouvées sur Reddit / X.
La plupart ne faisaient que reformuler les 4 règles de Karpathy ou concernaient des règles spécifiques non généralisables, comme « Toujours utiliser Tailwind ». J’ai fini par les supprimer.

Plus de 12 règles.
J’en ai testé jusqu’à 18. Au-delà de 14, la conformité chute de 76 % à 52 %. La limite réelle est autour de 200 lignes. Au-delà, le modèle commence à faire du pattern matching plutôt que de lire chaque règle.

Dépendre d’outils spécifiques.
Par exemple, « Toujours utiliser eslint ». Si eslint n’est pas installé, la règle échoue silencieusement. Je l’ai remplacée par une règle plus générale : « Respecter le style imposé par la base de code ».

Mettre des exemples dans CLAUDE.md au lieu des règles.
Les exemples consomment beaucoup de contexte, équivalent à 10 règles, et le modèle peut faire du surapprentissage. Les règles sont abstraites, les exemples concrets. Il faut privilégier les règles.

« Soyez prudent », « Réfléchissez », « Concentrez-vous ».
Ce sont du bruit. Leur taux de conformité est tombé à 30 %, car elles ne peuvent pas être vérifiées. Je les ai remplacées par des règles plus précises, comme « Expliquer clairement ses hypothèses ».

Demander à Claude d’agir comme un « ingénieur senior ».
Ça ne sert à rien. Claude se considère déjà comme tel. La différence réside dans l’exécution, pas dans la perception. Les règles impératives peuvent réduire cet écart, pas les simples indications de rôle.

Version complète des 12 règles de CLAUDE.md

Voici la version prête à copier-coller.

Impossible de l’afficher en dehors de ce document Feishu pour l’instant.

Enregistrer ce fichier à la racine du dépôt sous le nom CLAUDE.md. Ajoutez-y, en dessous, vos règles spécifiques au projet : stack technologique, commandes de test, modes d’erreur, etc. La limite est d’environ 200 lignes, au-delà, la conformité chute.

Comment l’installer

Deux étapes simples :

1. Ajouter les 4 règles de base de Karpathy à votre CLAUDE.md
   curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Coller ci-dessous les règles 5 à 12 du présent article

Enregistrer le fichier à la racine du dépôt. Le symbole « >> » est crucial : il ajoute au fichier existant, sans écraser vos règles spécifiques.

Modèle mental

CLAUDE.md n’est pas une liste de souhaits, mais un contrat de comportement pour bloquer les modes d’échec observés.

Chaque règle doit répondre à cette question : « Quel problème empêche-t-elle ? »

Les 4 règles de Karpathy ciblent les échecs observés en janvier 2026 : hypothèses silencieuses, sur-ingénierie, dommages involontaires, critères faibles de réussite. Ce sont des bases, ne pas les négliger.

Les 8 règles ajoutées visent les nouveaux échecs après mai 2026 : boucles d’agents sans limite, tâches à étapes multiples sans checkpoints, tests superficiels, erreurs silencieuses masquées en succès. Ce sont des correctifs incrémentaux.

Les effets varient selon l’usage. Si vous ne faites pas de pipeline à plusieurs étapes, la règle 10 est moins critique. Si votre code est déjà cohérent et linté, la règle 11 est redondante. Après lecture, gardez celles qui corrigent vos erreurs, supprimez le reste.

Une version de 6 règles, adaptée à vos erreurs réelles, vaut mieux qu’un document de 12 règles dont la moitié ne vous concerne pas.

Conclusion

Le tweet d’Andrej Karpathy en janvier 2026 était une plainte. Forrest Chang l’a transformé en 4 règles. Aujourd’hui, 120 000 développeurs ont mis un star à ce résultat. La majorité utilise encore ces 4 règles.

Les modèles ont évolué, l’écosystème aussi. Agents à étapes multiples, déclenchements en chaîne, chargement de compétences, collaboration multi-bases — tout cela n’existait pas lors du tweet. Les 4 règles initiales ne suffisent plus. Elles ne sont pas fausses, mais incomplètes.

Les 8 règles supplémentaires, testées sur 30 bases de code en 6 semaines, ont réduit l’erreur de 41 % à 3 %.

Sauvegardez cet article ce soir, collez ces 12 règles dans votre CLAUDE.md. Si cela vous évite une semaine d’erreurs, partagez.

[ lien vers l’article original ]

Cliquez pour découvrir les offres d’emploi de律动BlockBeats

Rejoignez la communauté officielle de律动BlockBeats :

Telegram abonnement : https://t.me/theblockbeats

Telegram groupe : https://t.me/BlockBeats_App

Twitter officiel : https://twitter.com/BlockBeatsAsia