Note de la rédaction : En janvier 2026, les critiques d'Andrej Karpathy sur la capacité de Claude à écrire du code ont mis en lumière un fichier apparemment mineur, mais extrêmement crucial dans les flux de travail de programmation par IA : CLAUDE.md. Forrest Chang a ensuite regroupé ces problèmes en quatre règles de comportement visant à limiter les erreurs courantes de Claude en matière de codage : hypothèses silencieuses, sur-ingénierie, endommagement de code non pertinent et absence de critères clairs de succès.

Mais quelques mois plus tard, les scénarios d'utilisation de Claude Code ne se limitent plus à « faire écrire un morceau de code au modèle ». Avec l'adoption courante des agents à plusieurs étapes, des déclencheurs en chaîne par hook, du chargement de compétences et de la collaboration entre plusieurs dépôts de code, de nouveaux modes d'échec apparaissent : le modèle perd le contrôle lors de tâches longues, les tests passent sans vérifier la logique réelle, la migration est terminée mais des erreurs sont silencieusement ignorées, et des styles de code différents sont incorrectement mélangés.

L'auteur de cet article a testé 30 dépôts de code en six semaines et a ajouté huit nouvelles règles aux quatre règles originales de Karpathy, dans le but de couvrir les nouveaux problèmes apparus avec l'évolution de la programmation IA, passant de la complétion unique à la collaboration agentisée.

The following is the original text:

À la fin de janvier 2026, Andrej Karpathy a publié une série de tweets critiquant la manière dont Claude écrit du code. Il a identifié trois types de problèmes typiques : faire des hypothèses erronées sans les préciser, complexifier inutilement, et causer des dommages non liés à du code qui n'aurait pas dû être modifié.

Forrest Chang a vu cette chaîne de tweets, a regroupé les plaintes en 4 règles de comportement, les a écrites dans un fichier séparé appelé CLAUDE.md, et les a publiées sur GitHub. Ce projet a reçu 5 828 étoiles le premier jour, a été sauvegardé 60 000 fois en deux semaines, et compte aujourd'hui 120 000 étoiles, devenant le dépôt de code à un seul fichier à la croissance la plus rapide de 2026.

Ensuite, je l'ai testé sur 30 dépôts de code sur une période de 6 semaines.

Ces 4 règles sont effectivement efficaces. Les erreurs qui survenaient précédemment avec une probabilité d’environ 40 % ont diminué à moins de 3 % dans les tâches où ces règles s’appliquent. Toutefois, le problème est que ce modèle a été initialement conçu pour résoudre les erreurs apparues en janvier lorsque Claude écrivait du code.

En mai 2026, les problèmes auxquels fait face l'écosystème Claude Code sont différents : conflits entre agents, déclenchement en chaîne de hooks, conflits de chargement de compétences et interruption de flux de travail multisteps entre sessions.

J'ai donc ajouté 8 nouvelles règles. Voici la version complète de 12 règles de CLAUDE.md : pourquoi chaque règle mérite d'être incluse, et où la version originale du modèle Karpathy échoue silencieusement sur 4 points.

Si vous souhaitez sauter les explications et copier directement, le fichier complet se trouve en fin de texte.

Pourquoi est-ce important

Le fichier CLAUDE.md de Claude Code est le plus sous-estimé de toute la pile technologique de programmation IA. La plupart des développeurs commettent généralement trois types d'erreurs :

Premièrement, traitez-le comme une poubelle de préférences, y plongez toutes vos habitudes, jusqu'à ce qu'il atteigne plus de 4 000 tokens, ce qui fait chuter le taux de respect des règles à 30 %.

Deuxièmement, il vaut mieux ne pas l'utiliser du tout et redemander à chaque fois. Cela entraîne un gaspillage de 5 fois plus de jetons et un manque de cohérence entre les sessions.

Troisièmement, copier un modèle et ensuite l'ignorer complètement. Il peut fonctionner pendant deux semaines, mais avec les évolutions du codebase, il deviendra obsolète sans que vous vous en rendiez compte.

La documentation officielle d'Anthropic est claire : CLAUDE.md est uniquement indicatif. Claude suit environ 80 % du temps ces instructions. Au-delà de 200 lignes, la taux de conformité diminue 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 seuil minimal.

Mais la limite peut encore être augmentée. Après l'ajout de ces 8 règles supplémentaires, il ne couvre plus seulement les problèmes d'écriture de code signalés par Karpathy en janvier 2026, mais aussi les problèmes d'orchestration d'agents apparus en mai 2026 — des problèmes qui n'existaient pas lors de la rédaction du modèle original.

Les 4 règles originales

Si vous n'avez pas encore consulté le dépôt de Forrest Chang, consultez d'abord cette version de base :

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

Ne faites pas d'hypothèses silencieuses. Énoncez vos hypothèses et exposez les compromis. Posez des questions avant de deviner. Suggérez activement des objections lorsqu'une solution plus simple existe.

Règle 2 : Privilégiez la simplicité.
Utilisez le minimum de code nécessaire pour résoudre le problème. N'ajoutez pas de fonctionnalités imaginaires. Ne concevez pas de couches d'abstraction pour du code à usage unique. Si un ingénieur expérimenté le jugerait trop complexe, simplifiez-le.

Règle 3 : Modifications chirurgicales.
Ne modifiez que les parties nécessaires. N'optimisez pas automatiquement le code, les commentaires ou le format adjacents. Ne restructurez pas ce qui ne fonctionne pas mal. Restez cohérent avec le style existant.

Règle 4 : Exécutez avec un objectif en vue.
Définissez d'abord les critères de réussite, puis itérez en boucle jusqu'à la validation complète. Ne dites pas à Claude comment procéder à chaque étape, mais indiquez-lui à quoi devrait ressembler le résultat réussi, et laissez-le itérer par lui-même.

Ces 4 règles permettent de résoudre environ 40 % des modes d'échec que je constate lors de sessions Claude Code non supervisées. Les environ 60 % restants sont cachés dans ces zones blanches ci-dessous.

Mes 8 nouvelles règles, et pourquoi

Chaque règle provient d'un moment réel : les 4 règles originales de Karpathy ne suffisent plus. Je vais d'abord décrire le contexte, puis présenter la règle correspondante.

Les règles de Karpathy ne couvrent pas ce point. Le modèle a donc commencé à décider des problèmes qui devraient être gérés par un code déterministe : réessayer une appel API, router un message, ou quand mettre à niveau le traitement. Le résultat est que les décisions varient chaque semaine. Vous obtenez un if-else instable facturé à 0,003 $ par token.

À ce moment-là, un code appelait Claude pour « déterminer s’il fallait réessayer en cas d’erreur 503 ». Il fonctionnait bien au début, pendant deux semaines, puis est devenu soudainement instable, car le modèle a commencé à inclure le corps de la requête dans le contexte de jugement. La stratégie de réessai est devenue aléatoire, car le prompt lui-même était aléatoire.

Un CLAUDE.md sans contrainte budgétaire équivaut à un chèque en blanc. Chaque boucle risque de déraper et de se transformer en un déversement de 50 000 tokens. Le modèle ne s'arrêtera pas tout seul.

À ce moment-là, une session de débogage a duré 90 minutes. Le modèle répétait en boucle les mêmes messages d'erreur de 8 Ko et progressivement oubliait quelles solutions il avait déjà essayées. À la fin, il a commencé à proposer des solutions que j'avais déjà rejetées 40 messages plus tôt. Avec un budget de tokens, ce processus aurait dû être arrêté après 12 minutes.

Lorsque deux parties du dépôt de code sont contradictoires, Claude tente de plaire aux deux côtés, ce qui aboutit à un code incohérent.

À ce moment-là, il existait deux modèles de gestion des erreurs dans la base de code : l’un utilisait async/await avec des try/catch explicites, et l’autre reposait sur des limites globales d’erreurs. Le nouveau code écrit par Claude utilisait les deux. Résultat : la gestion des erreurs était effectuée deux fois. J’ai mis 30 minutes à comprendre pourquoi les erreurs étaient ignorées deux fois.

La « modification chirurgicale » de Karpathy dit à Claude de ne pas modifier le code voisin. Mais elle ne dit pas à Claude : comprenez d'abord le code voisin. Sans cela, Claude écrira un nouveau code en conflit avec le code existant situé à 30 lignes de distance.

À ce moment-là, Claude a ajouté une fonction entièrement identique à côté d'une fonction existante, car il n'avait pas lu la fonction d'origine. Les deux fonctions accomplissent la même tâche. Toutefois, en raison de l'ordre d'importation, la nouvelle fonction a remplacé l'ancienne, qui était devenue le standard de fait pendant six mois.

L'« exécution orientée objectif » de Karpathy suggère que les tests peuvent servir de critère de réussite. Mais en pratique, Claude considère « passer les tests » comme unique objectif, produisant ainsi du code qui réussit les tests superficiels tout en perturbant d'autres éléments.

À ce moment-là, Claude avait écrit 12 tests pour une fonction d'authentification, tous passés. Mais la logique d'authentification en production était défectueuse. Ces tests ne vérifiaient que le fait que la fonction « retournait quelque chose », et non qu'elle retournait la bonne chose. La fonction passait les tests parce qu'elle retournait une constante.

Le modèle de Karpathy a une interaction par défaut unique. Cependant, le travail réel avec Claude Code est souvent multiphasé : refactorisation à travers 20 fichiers, développement de fonctionnalités au sein d'une même session, débogage à travers plusieurs commits. Sans points de contrôle, une seule erreur peut entraîner la perte de l'ensemble des progrès accomplis.

À ce moment-là, une tâche de重构 en 6 étapes a échoué à l'étape 4. Lorsque j'ai découvert l'erreur, Claude avait déjà poursuivi et accompli les étapes 5 et 6 en partant de cet état erroné. Le temps consacré à décomposer et réparer a été plus long que celui nécessaire pour refaire toute la tâche. S'il y avait eu des points de contrôle, le problème aurait été détecté à l'étape 4.

Dans une base de code déjà dotée d’un modèle établi, Claude aime introduire sa propre manière d’écrire. Même si sa méthode est « meilleure », introduire une deuxième approche est pire que n’importe quelle approche unique.

À ce moment-là, Claude a introduit des hooks dans une base de code React basée sur des classes. Cela fonctionnait effectivement, mais il a rompu le modèle de test existant, car ces tests dépendaient de componentDidMount. Il a fallu près d’une demi-journée pour le supprimer et le réécrire.

Les échecs les plus coûteux de Claude sont souvent ceux qui ressemblent à des réussites. Une fonction « fonctionne », mais retourne des données erronées ; une migration « est terminée », mais a ignoré 30 enregistrements ; un test « passe », mais uniquement parce que l'assertion elle-même est fausse.

À ce moment-là, Claude a déclaré que la migration de la base de données avait été « réussie ». En réalité, elle a silencieusement ignoré 14 % des enregistrements présentant des conflits de contrainte de déclenchement. Ce comportement d'ignorance a été enregistré dans les journaux, mais n'a pas été clairement révélé. Ce n'est qu'11 jours plus tard, lorsque les données des rapports ont commencé à présenter des anomalies, que nous avons découvert le problème.

Sur une période de 6 semaines, j'ai suivi un ensemble de 50 tâches représentatives couvrant 30 dépôts de code, en testant trois configurations.

Le taux d'erreur désigne les tâches qui doivent être corrigées ou réécrites pour correspondre à l'intention initiale. Les erreurs prises en compte incluent : hypothèses erronées silencieuses, sur-ingénierie, perturbations inutiles, échecs silencieux, violation des conventions, compromis conflictuels, et points de contrôle omis.

Le taux de conformité désigne la probabilité avec laquelle Claude applique explicitement une règle lorsqu'elle est applicable.

Le résultat véritablement intéressant n'est pas seulement la baisse du taux d'erreur de 41 % à 3 %. Plus important encore, en passant de 4 règles à 12 règles, la charge de conformité n'a presque pas augmenté : le taux de conformité est passé de 78 % à 76 %, tandis que le taux d'erreur a encore diminué de 8 points de pourcentage. Les nouvelles règles couvrent des modes d'échec non pris en charge par les 4 règles initiales et n'entrent pas en concurrence pour le même budget d'attention.

Où le modèle Karpathy échoue-t-il silencieusement ?

Même sans ajouter de nouvelles règles, les 4 règles d'origine sont insuffisantes dans au moins 4 endroits.

Premièrement, les tâches Agent à exécution prolongée.
Les règles de Karpathy s'appliquent principalement au moment où Claude écrit du code. Mais que se passe-t-il lorsque Claude exécute un pipeline à plusieurs étapes ? Le modèle d'origine ne prévoit pas de règles de budget, pas de règles de points de contrôle, ni de règle « échouer bruyamment ». Le pipeline dérive alors progressivement.

Deuxièmement, la cohérence entre plusieurs dépôts de code.
« Correspondre au style existant » ne prévoit par défaut qu'un seul style. Mais dans un monorepo comportant 12 services, Claude doit choisir lequel de ces styles reproduire. La règle originale ne lui indique pas comment faire ce choix. Il choisit donc soit au hasard, soit mélange de manière équitable plusieurs styles.

Troisièmement, la qualité des tests.
« Exécuter en fonction des objectifs » considère « les tests passés » comme un succès, sans préciser que les tests eux-mêmes doivent avoir du sens. Le résultat est que Claude rédige des tests qui vérifient presque rien, mais qui lui donnent l’impression d’être confiant.

Quatrièmement, les différences entre l'environnement de production et la phase de prototype.
Les mêmes 4 règles peuvent empêcher le sur-ingénierie du code de production, mais peuvent également ralentir le développement de prototypes. En effet, la phase de prototype nécessite parfois 100 lignes de structure exploratoire pour déterminer la direction. Le principe de « simplicité d'abord » de Karpathy est facilement surdéclenché dans le code initial.

Ces 8 nouvelles règles ne remplacent pas les 4 règles originales de Karpathy, mais combleront leurs lacunes : le modèle initial était adapté à un contexte d'écriture de code axé sur la complétion automatique, tel qu'il existait en janvier 2026 ; en mai 2026, Claude Code évolue vers un environnement piloté par des agents, impliquant des étapes multiples et la collaboration entre plusieurs dépôts de code — les problèmes auxquels ils font face sont donc différents.

Quelles méthodes n'ont pas fonctionné ?

Avant de finaliser ces 12 règles, j'ai également essayé d'autres solutions.

Ajoutez les règles que j'ai vues sur Reddit / X.
La plupart d'entre elles se contentaient de répéter les quatre règles originales de Karpathy avec des formulations différentes, ou étaient des règles spécifiques à un domaine non généralisables, comme « utilisez toujours les classes Tailwind ». Elles ont toutes été supprimées.

Plus de 12 règles.
J'ai testé jusqu'à 18 lignes. Au-delà de 14, le taux de conformité est tombé de 76 % à 52 %. La limite de 200 lignes est réelle. Au-delà de cette longueur, Claude commence à faire un matching de modèle en « il y a des règles ici », au lieu de lire réellement chaque règle.

Règles dépendant de l'existence de certains outils.
Par exemple, « utilisez toujours eslint » : si eslint n’est pas installé dans le projet, cette règle devient invalide, et ce de manière silencieuse. Plus tard, je l’ai modifiée pour exprimer une dépendance moins spécifique à un outil, en remplaçant « utilisez eslint » par « respectez le style déjà imposé dans la base de code ».

Dans CLAUDE.md, incluez des exemples, pas des règles.
Les exemples occupent plus de contexte que les règles. Trois exemples consomment à peu près autant de contexte que dix règles, et Claude est facilement sujette à un surajustement sur les exemples. Les règles sont abstraites, les exemples sont concrets. Il faut donc privilégier les règles.

Faites attention. Réfléchissez sérieusement. Concentrez-vous.
Ce sont tous du bruit. Le taux de conformité à ce type d'instructions est tombé à environ 30 %, car ils ne peuvent pas être vérifiés. Plus tard, je les ai remplacés par des règles impératives plus spécifiques, comme « explicitez les hypothèses ».

Dites à Claude de se comporter comme un « ingénieur expérimenté ».
Cela ne fonctionne pas. Claude se considère déjà comme un ingénieur expérimenté. La question réelle n'est pas de savoir s'il le pense, mais s'il le fait. Les règles impératives peuvent réduire cet écart, les indicateurs d'identité non.

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

Voici la version complète prête à être copiée et collée.

Ce contenu ne peut pas être affiché en dehors du document Feishu pour le moment

Enregistrez-le sous le nom CLAUDE.md à la racine du dépôt. Ajoutez sous ces 12 règles des règles spécifiques au projet, comme la pile technique, les commandes de test, les modèles d'erreurs, etc. Ne dépassez pas 200 lignes au total, car au-delà, la conformité aux règles diminue nettement.

Comment installer

Deux étapes seulement :

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

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

Enregistrez le fichier à la racine du dépôt. Les >> sont importants : ils permettent d'ajouter au fichier CLAUDE.md existant, sans remplacer les règles spécifiques au projet que vous avez déjà écrites.

CLAUDE.md n'est pas une liste de souhaits, mais un contrat de comportement conçu pour corriger les modèles d'échec spécifiques que vous avez observés.

Chaque règle devrait répondre à une question : quel type d'erreur elle empêche ?

Les 4 règles de Karpathy visent à prévenir les modèles d'échec qu'il a observés en janvier 2026 : hypothèses silencieuses, sur-ingénierie, destruction non pertinente, critères de succès faibles. Ce sont des fondamentaux ; ne les sautez pas.

Mes 8 nouvelles règles visent à prévenir de nouveaux modes d'échec apparus après mai 2026 : les boucles d'agents sans contrainte budgétaire, les tâches multi-étapes sans points de contrôle, les tests qui semblent effectués mais qui n'ont pas vérifié les logiques critiques, ainsi que le fait de présenter des échecs silencieux comme des succès silencieux. Ce sont des correctifs incrémentaux.

Bien sûr, les effets varient selon les individus. Si vous n'utilisez pas de pipeline à plusieurs étapes, la règle 10 n'est pas aussi importante pour vous. Si votre base de code suit un seul style uniforme déjà imposé par un outil de linting, la règle 11 est redondante. Après avoir lu ces 12 règles, conservez uniquement celles qui correspondent réellement à des erreurs que vous avez déjà commises, et supprimez les autres.

Une version de 6 règles de CLAUDE.md adaptée aux modes d'échec réels, supérieure à une version de 12 règles dont 6 n'auront jamais d'utilité.

Conclusion

Le tweet de Karpathy en janvier 2026 était essentiellement une plainte. Forrest Chang l'a transformé en 4 règles. Finalement, 120 000 développeurs ont mis un Star à ce résultat. Et la majorité d'entre eux, aujourd'hui, n'utilisent toujours que ces 4 règles.

Les modèles ont progressé, et l'écosystème a changé. Les agents à plusieurs étapes, les déclencheurs en chaîne via hook, le chargement de compétences, la collaboration entre plusieurs dépôts de code — tout cela n'existait pas lorsque Karpathy a publié ce tweet. Les quatre règles d'origine ne résolvent pas ces problèmes. Elles ne sont pas fausses, mais incomplètes.

Ajout de 8 nouvelles règles. 6 semaines, couverture des tests sur 30 dépôts de code. Taux d'erreurs réduit de 41 % à 3 %.

Épinglez cet article pour ce soir et collez ces 12 règles dans votre fichier CLAUDE.md. Si cela vous fait gagner une semaine d’essais et d’erreurs avec Claude, partagez-le.