karpathy s'est plaint de claude sur X. forrest chang a transformé cette plainte en quatre règles et un dépôt GitHub. Le dépôt a atteint 120 000 étoiles en quelques semaines. La plupart des développeurs qui lisent ceci n'utilisent encore que ces quatre règles. Le problème, c'est qu'elles ont été écrites en janvier. Nous sommes maintenant à la mi-2026, et l'écosystème de Claude Code a changé.
Cet article vous donne le CLAUDE.md complet en 12 règles, explique pourquoi chaque règle existe, quel échec elle évite, et ce que le modèle original omet silencieusement. Copiez-le à la fin.
Qu'est-ce que CLAUDE.md et pourquoi la plupart des gens se trompent
CLAUDE.md est un fichier que vous placez à la racine de votre dépôt. Claude Code le lit avant chaque session. Ce n'est pas une invite. Ce n'est pas une liste de préférences. C'est un système d'exploitation pour la façon dont Claude se comporte dans votre codebase.
La plupart des développeurs font une de ces trois erreurs. Ils entassent toutes leurs préférences dans le fichier jusqu'à ce qu'il dépasse 4 000 tokens, moment auquel la conformité chute à 30 % car les règles importantes sont enterrées. Ils l'ignorent complètement et doivent tout re-préciser à chaque session, ce qui gaspille cinq fois plus de tokens et ne produit aucune cohérence. Ils collent un modèle une fois, l'oublient, et le regardent silencieusement se briser au fil des semaines à mesure que leur codebase change.
La documentation officielle d'Anthropic est explicite : CLAUDE.md est consultatif. Claude le suit environ 80 % du temps en dessous de 200 lignes. Au-delà de 200 lignes, la conformité chute fortement. Le plafond pour les fichiers CLAUDE.md utiles est court, précis et appliqué par des règles directes, pas des suggestions.
Les 4 règles originales : commencez ici si vous n'avez rien
Andrej Karpathy, ancien directeur de l'IA chez Tesla et co-fondateur d'OpenAI, a publié un fil en janvier 2026 après des semaines de travail intensif avec Claude Code. Pas un framework. Une plainte. Trois modes d'échec qu'il rencontrait sans cesse : Claude suppose silencieusement au lieu de demander, Claude construit trop au lieu de résoudre le minimum, et Claude touche au code qu'on ne lui a jamais demandé de toucher.
Forrest Chang a lu le fil et l'a transcrit sous forme de règles. Un fichier, 65 lignes, sur GitHub le lendemain. Voici les quatre :
Règle 1 – Réfléchir avant de coder
Énoncez vos hypothèses avant d'écrire du code. Mettez en évidence les compromis. Demandez avant de deviner. Opposez-vous quand une approche plus simple existe. Ne construisez jamais sur une hypothèse non vérifiée.
Règle 2 – La simplicité d'abord
Écrivez le code minimum qui résout le problème. Pas de fonctionnalités spéculatives. Pas d'abstractions pour du code utilisé une seule fois. Si un ingénieur senior jugerait cela trop complexe, simplifiez-le.
Règle 3 – Modifications chirurgicales
Ne touchez qu'à ce que la tâche exige. N'améliorez pas le code adjacent, les commentaires ou le formatage. Ne refactorisez pas ce qui n'est pas cassé. Respectez exactement le style existant.
Règle 4 – Exécution axée sur les objectifs
Définissez à quoi ressemble le succès avant de commencer. Bouclez jusqu'à ce que le succès soit vérifié. Ne listez pas les étapes pour que Claude les suive. Dites à Claude à quoi ressemble le résultat final et laissez-le trouver le chemin.
Ces quatre règles couvrent environ 40 % des modes d'échec dans les sessions Claude Code non supervisées. Les 60 % restants se trouvent dans les lacunes que le modèle original ne comble pas, car ces problèmes n'existaient pas pleinement lorsque Karpathy a publié son fil.
Pourquoi le modèle original doit être étendu
Les quatre règles de Karpathy ont été conçues pour corriger une session d'écriture de code mono-agent. L'écosystème Claude Code en 2026 utilise des configurations multi-agents, des hooks, des bibliothèques de compétences et des workflows en plusieurs étapes qui s'étendent sur plusieurs sessions. Le modèle original n'a rien à dire à ce sujet.
Quatre lacunes spécifiques apparaissent dans les règles originales. Premièrement, les conflits d'agents : deux agents modifiant les mêmes fichiers sans règles de propriété, écrasant silencieusement les modifications de l'autre. Deuxièmement, les cascades de hooks : des hooks qui se déclenchent à chaque appel d'outil, transformant une requête de 200 tokens en 8 000 tokens sans budget pour l'arrêter. Troisièmement, les conflits de chargement de compétences : plusieurs compétences avec des descriptions similaires confondent le répartiteur et chargent la mauvaise. Quatrièmement, les interruptions de sessions en plusieurs étapes : une refactorisation en 6 étapes échoue à l'étape 4, mais les étapes 5 et 6 s'exécutent quand même et se basent sur un état défaillant.
Les quatre règles originales ne sont pas fausses. Elles sont incomplètes. Les 8 règles supplémentaires ci-dessous comblent ces lacunes spécifiques.
Les 8 nouvelles règles : ce que chacune corrige
Règle 5 – N'utilisez pas le modèle pour un travail non linguistique
Les décisions déterministes appartiennent au code déterministe. La logique de nouvelle tentative, les seuils de routage, les règles d'escalade, le branchement basé sur l'état : rien de tout cela ne devrait être des appels LLM. Le modèle décide différemment chaque semaine en fonction de ce qui se trouve dans la fenêtre de contexte. Ce qui ressemble à un comportement cohérent est en réalité une variance qui n'a pas encore fait surface.
L'incident spécifique : un appel LLM « décider s'il faut réessayer sur une erreur 503 » a fonctionné pendant deux semaines, puis a commencé à produire un comportement aléatoire parce que le modèle a commencé à lire le corps de la requête comme contexte pour la décision de nouvelle tentative. La politique est devenue aléatoire parce que l'entrée effective était aléatoire.
Ajoutez ceci à votre CLAUDE.md :
Le routage, la logique de nouvelle tentative, le branchement basé sur l'état et les décisions de seuil appartiennent au code, pas aux appels de modèle. Si le résultat d'une décision est binaire ou suit une règle fixe, écrivez la règle dans le code.
Règle 6 – Budgets de tokens stricts, sans exception
Chaque boucle d'agent a une chance de déraper. Claude n'arrêtera pas tout seul une session de débogage de 90 minutes. Il continuera à itérer parce que c'est ce qu'on lui dit de faire. Les budgets de tokens sont le seul mécanisme qui impose un arrêt brutal.
L'incident spécifique : une session de débogage bouclant sur le même message d'erreur de 8 Ko pendant 90 minutes. À la fin, Claude suggérait des correctifs qu'il avait déjà essayés et abandonnés deux heures plus tôt. Le contexte était si plein qu'il avait perdu la trace de son propre raisonnement.
Ajoutez ceci :
Chaque session d'agent a un budget de tokens strict. Si le budget est atteint sans une solution vérifiée, arrêtez-vous, résumez les résultats dans un fichier et quittez. Ne continuez pas au-delà du budget.
Règle 7 – Un agent, un répertoire
Lorsque deux agents touchent le même répertoire simultanément, vous obtenez une corruption d'état silencieuse. Un agent écrit un fichier pendant qu'un autre le lit. Le résultat est une donnée qu'aucun des deux agents n'attendait et qu'aucun ne remarque.
Utilisez les git worktrees. Exécutez git worktree add ../agent-2-branch feature-branch avant de lancer un deuxième agent. Chaque agent obtient son propre répertoire de travail isolé pointant vers sa propre branche. Les agents ne partagent jamais le système de fichiers.
Ajoutez ceci :
Les agents s'exécutant en parallèle travaillent dans des git worktrees séparés. Aucun deux agents ne touchent le même répertoire en même temps. Chaque agent possède sa branche.
Règle 8 – Écrivez des fichiers de point de contrôle pour les travaux en plusieurs étapes
Toute tâche de plus de trois étapes a besoin d'un fichier de point de contrôle. Claude écrit le fichier après chaque étape avec ce qui a été fait, ce qui a été trouvé et ce qui vient ensuite. Si la session meurt ou se brise à l'étape 4, la session suivante lit le point de contrôle et continue à partir de l'étape 4. Sans le point de contrôle, chaque redémarrage revient à l'étape 1.
Créez un fichier appelé PROGRESS.md dans votre répertoire de travail avant de commencer toute tâche en plusieurs étapes. Dites à Claude dans votre CLAUDE.md :
Pour les tâches de plus de trois étapes, écrivez un fichier PROGRESS.md après chaque étape. Incluez : ce qui a été fait, ce qui a été trouvé, ce qui vient ensuite et ce qui est bloqué. Si une session se termine avant la fin, la session suivante lit d'abord PROGRESS.md et continue là où elle s'est arrêtée.
Règle 9 – Échouez bruyamment ou pas du tout
Claude a un fort biais pour paraître réussi. Il réussira un test qui ne teste pas réellement ce qui vous importait. Il terminera une migration tout en ignorant silencieusement les fichiers qui ont généré une erreur. Il signalera « terminé » pour une tâche qui est faite à 80 %.
La règle : si les critères de succès ne peuvent pas être vérifiés, la tâche n'est pas terminée. Si une étape échoue, arrêtez-vous et signalez l'échec avec des détails avant de continuer. Ne masquez pas les erreurs.
Ajoutez ceci :
Ne continuez jamais après une étape qui a échoué. Si un test réussit mais ne couvre pas le comportement réel, dites-le. Si une migration ignore des fichiers, listez les fichiers ignorés et arrêtez-vous. Le succès signifie vérifiable, pas signalé.
Règle 10 – Les descriptions de compétences doivent être uniques
Les compétences sont chargées par correspondance de description. Si deux compétences ont des descriptions qui se chevauchent, le répartiteur en choisit une arbitrairement. La mauvaise compétence se charge, la tâche s'exécute avec de mauvaises instructions, et vous ne voyez jamais d'erreur car aucune erreur n'est levée.
Nommez le travail de chaque compétence avec un langage qui ne peut correspondre à aucune autre compétence. « assistant de requête de base de données » et « assistant de migration de base de données » entreront en conflit. « exécuter des requêtes SQL en lecture seule sur la base de données de production » et « exécuter et vérifier des scripts de migration de schéma avec restauration » ne le feront pas.
Ajoutez ceci :
Chaque description de compétence doit identifier de manière unique son travail. Aucune deux compétences ne doivent avoir des descriptions qui pourraient s'appliquer à la même tâche. Si deux compétences semblent similaires, l'une d'elles doit être renommée avant d'être déployée.
Règle 11 – Séparez le chercheur du rédacteur
La pollution du contexte est réelle. Lorsque Claude fait de la recherche et de l'écriture dans la même session, le bruit de la recherche dégrade l'écriture. Il s'engage dans des tangentes, atténue des conclusions qu'il n'a pas besoin d'atténuer et perd la ligne d'argumentation claire qu'il aurait eue en repartant de zéro.
Lancez un sous-agent de recherche pour toute tâche qui nécessite la lecture de plus de cinq fichiers ou l'interrogation de plus de deux sources. Obtenez un rapport structuré. Démarrez une session propre pour l'écriture ou l'implémentation avec seulement le rapport dans le contexte.
Ajoutez ceci :
La recherche et l'implémentation sont des sessions séparées. Un sous-agent chercheur lit les fichiers, exécute des requêtes et renvoie un résumé structuré. La session d'implémentation démarre à partir de zéro avec ce résumé comme seule entrée. Ne fusionnez jamais la recherche et l'écriture en une seule session.
Règle 12 – Les hooks ont aussi besoin de budgets
Les hooks se déclenchent à chaque appel d'outil. Un hook qui exécute un linter, un formateur, un rédacteur de journal et une analyse de sécurité à chaque écriture de fichier exécute quatre processus par appel d'outil. Sur une session avec 200 appels d'outil, cela représente 800 processus s'exécutant en arrière-plan, la plupart redondants, tous consommant des tokens.
Chaque hook que vous ajoutez a besoin d'une condition de portée : s'exécuter uniquement sur les écritures de fichiers dans des répertoires spécifiques, s'exécuter uniquement lorsqu'une extension de fichier spécifique est touchée, s'exécuter uniquement après la fin de la session plutôt qu'après chaque appel d'outil. Les hooks sans conditions de portée dégraderont les performances de la session de manière invisible.
Ajoutez ceci :
Chaque hook a une condition de portée explicite. Aucun hook ne s'exécute inconditionnellement à chaque appel d'outil. Regroupez la journalisation en fin de session. Exécutez les linters uniquement sur les fichiers modifiés. Exécutez les analyses de sécurité uniquement sur les fichiers en dehors du répertoire de test.
Le CLAUDE.md complet en 12 règles – Copiez ceci
Copiez ce fichier dans la racine de votre dépôt. Remplissez les sections marquées entre crochets. Le fichier entier reste en dessous de 100 lignes, ce qui maintient la conformité au-dessus de 80 %.
CLAUDE.md
Projet
[une phrase : ce que fait ce codebase et la pile technologique utilisée]
Règles de comportement
Réfléchir avant de coder
Énoncez vos hypothèses avant d'écrire du code. Mettez en évidence les compromis. Demandez avant de deviner sur tout ce qui affecte l'architecture ou les données. Opposez-vous quand une approche plus simple existe.
La simplicité d'abord
Écrivez le 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 jugerait cela trop complexe, simplifiez.
Modifications chirurgicales
Ne touchez qu'à ce que la tâche exige. N'améliorez pas le code adjacent, le formatage, les commentaires ou les noms qui ne faisaient pas partie de la demande. Respectez exactement le style de code existant.
Exécution axée sur les objectifs
Définissez à quoi ressemble le succès avant de commencer. Bouclez jusqu'à ce que cette définition soit atteinte et vérifiée. Ne demandez pas d'instructions étape par étape. Trouvez le chemin.
Pas d'appels de modèle pour les décisions déterministes
Le routage, la logique de nouvelle tentative, le branchement basé sur l'état et les décisions de seuil appartiennent au code, pas aux appels LLM. Si une règle peut être écrite, écrivez-la.
Budgets de tokens stricts
Chaque session a une limite de tokens stricte : [définissez votre nombre, par exemple 50 000 tokens]. Si la limite est atteinte sans une solution vérifiée, écrivez les résultats dans un fichier et arrêtez-vous. Ne continuez pas au-delà du budget.
Un agent, un répertoire
Les agents s'exécutant en parallèle travaillent dans des git worktrees séparés. Aucun deux agents ne partagent un répertoire. Si vous avez besoin d'un deuxième agent, exécutez : git worktree add ../agent-2 [nom-de-branche]
Point de contrôle pour les travaux en plusieurs étapes
Pour toute tâche de plus de trois étapes, créez PROGRESS.md dans le répertoire de travail. Écrivez-y après chaque étape : ce qui a été fait, ce qui a été trouvé, ce qui vient ensuite, ce qui est bloqué. Si la session se termine avant la fin, la session suivante lit d'abord PROGRESS.md.
Échouez bruyamment
Si une étape échoue, arrêtez-vous et signalez l'échec avec des détails avant de continuer. Si un test réussit mais ne couvre pas le comportement réel, dites-le. Le succès signifie vérifiable, pas signalé.
Descriptions de compétences uniques
Chaque compétence couvre exactement un travail. Sa description ne peut s'appliquer à aucune autre compétence du projet. Si deux compétences se chevauchent dans leur description, renommez avant de déployer.
La recherche et l'implémentation sont des sessions séparées
Utilisez un sous-agent pour toute tâche qui nécessite la lecture de plus de cinq fichiers ou l'interrogation de plus de deux sources. Obtenez un rapport structuré. Démarrez une session propre pour l'implémentation avec seulement ce rapport comme entrée.
Hooks à portée uniquement
Chaque hook a une condition explicite : extension de fichier, chemin de répertoire ou événement de session. Aucun hook ne s'exécute inconditionnellement à chaque appel d'outil. Regroupez la journalisation en fin de session lorsque c'est possible.
Ce qu'il ne faut pas toucher
[listez les répertoires ou fichiers que Claude ne doit jamais modifier : par exemple, /secrets, /migrations/archive, /prod-config]
Critère de succès par défaut
En cas de doute sur l'achèvement d'une tâche : le test réussit-il, la build réussit-elle, et le résultat est-il vérifiable par autre chose que le propre jugement de Claude ? Si la réponse est non à l'un de ces points, ce n'est pas terminé.
Quatre endroits où le modèle original se brise silencieusement
Même avec seulement les quatre règles originales, il existe quatre conditions spécifiques où le modèle produit un comportement erroné sans vous le dire.
Premièrement : les longues sessions avec un contexte accumulé. La règle d'exécution axée sur les objectifs de Karpathy dit à Claude de boucler jusqu'à vérification. Dans une longue session, la « vérification » devient floue à mesure que le contexte se remplit. Claude commence à vérifier par rapport à un modèle dégradé de ce qu'il était censé faire. La solution est la règle 6 (budget de tokens) qui impose un arrêt brutal.
Deuxièmement : les configurations multi-agents. La règle des modifications chirurgicales dit à chaque agent de ne toucher qu'à ce qui est nécessaire. Mais avec deux agents et aucune règle de propriété de répertoire, le « ce qui est nécessaire » se chevauche. La règle 7 (un agent, un répertoire) est la pièce manquante.
Troisièmement : les compétences parallèles avec des tâches similaires. Le modèle original n'a rien sur les compétences. La règle 10 (descriptions de compétences uniques) comble le fossé d'ambiguïté du répartiteur.
Quatrièmement : les sessions qui se terminent au milieu d'une tâche. L'exécution axée sur les objectifs suppose que la session s'exécute jusqu'à son terme. Elle n'a aucune instruction sur ce qu'il faut faire si la session meurt à l'étape 4 sur 8. La règle 8 (fichiers de point de contrôle) donne à la session suivante un point de départ.
Aucun de ces points n'est un bug dans les règles originales. Ce sont des lacunes que les règles originales n'ont pas été écrites pour couvrir.
Le nombre qui explique les étoiles GitHub
120 000 développeurs ont mis une étoile à un fichier texte de 65 lignes. Pas de code. Pas de bibliothèque. Pas de framework. Un fichier avec quatre règles.
Le nombre qui l'explique : 41 % de taux d'erreur dans les sessions Claude Code non supervisées sans CLAUDE.md. 11 % avec les quatre règles originales. 3 % avec les douze règles complètes.
Une réduction de 38 points du taux d'erreur n'est pas une amélioration marginale. Pour toute équipe utilisant Claude Code sur un travail de production réel, c'est la différence entre un agent en qui vous pouvez avoir confiance pour travailler toute la nuit et un que vous devez surveiller.
Le fichier à la fin de cet article prend cinq minutes à coller et à remplir. La première session après l'avoir fait sera différente. Pas parce que le modèle a changé. Parce que le modèle sait enfin comment votre monde fonctionne.
Ajoutez ceci à vos favoris et collez les 12 règles dans votre CLAUDE.md ce soir.
Repostez si vous avez trouvé cela utile.
