Vous travaillez avec Claude Code depuis quelques mois. Le constat s'impose : le modèle génère du code fonctionnel, puis s'élance dans un refactoring qu'on ne lui a jamais demandé et qui casse trois tests. Ou il invente une API qui n'existe nulle part dans votre stack. Pire encore, il ajoute une abstraction "pour l'avenir" quand vous vouliez juste corriger un bug de pagination. Ces comportements reviennent régulièrement. Frustrants. Coûteux en temps de review.
Andrej Karpathy a décortiqué ces mêmes patterns sur des dizaines de projets. Sa conclusion : un fichier CLAUDE.md de 65 lignes suffit à corriger le tir. L'impact se mesure. Sur un skill de fundraising, l'accuracy a bondi de 70 % à 94 % après optimisation via ce pattern. Un skill de qualification commerciale MEDDIC est passé de 65 % à 91 %. Ces chiffres ne ciblent pas la génération de code directement, certes, mais ils valident le principe fondamental : un contexte structuré et des règles explicites transforment un LLM créatif en exécutant fiable.
Le repo andrej-karpathy-skills a récolté 42 000 étoiles GitHub en une semaine. Aucune complexité cachée. C'est un fichier texte qui encode quatre constats sur les erreurs récurrentes des LLMs face au code. Vous allez voir comment ces quatre principes s'appliquent à votre situation, pourquoi ils réduisent la dette technique induite par l'IA, et comment les intégrer dans votre workflow dès demain.
Le fichier CLAUDE.md: persistance d'un system prompt dans votre repo
Claude Code lit automatiquement un fichier CLAUDE.md à la racine du projet quand une session démarre. Pensez-y comme un system prompt qui persiste entre les conversations. Vous y décrivez le contexte du projet, les conventions de code, les erreurs fréquentes, les règles de travail. Karpathy en a fait un artefact de première classe, au même rang qu'un .editorconfig ou un README.
La plupart des équipes le laissent vide ou l'ignorent. Résultat : Claude se comporte comme un stagiaire bien intentionné mais qui improvise à partir de suppositions. Il pense que vous voulez du TypeScript strict alors que votre monolithe fonctionne en JavaScript ES5. Il refactorise un service entier pour "améliorer la lisibilité" quand vous vouliez juste ajouter un log. Il crée une classe abstraite pour trois lignes de logique métier. Absurde.
Le CLAUDE.md de Karpathy inverse cette dynamique. Au lieu de laisser le modèle deviner, vous encodez vos attentes explicitement. La recommandation : moins de 50 lignes de règles génériques, enrichies par 10 à 15 lignes spécifiques au projet. Oubliez la prose. Des instructions directes. "Ne jamais toucher aux classes de domaine sans tests correspondants." "Respecter le style Ruby existant, pas de refactors latéraux." "Toute ambiguïté doit être clarifiée avant d'écrire du code."
Ce travail s'appelle le context engineering. Vous optimisez deux leviers : le contenu du fichier d'instructions et la sélection des fichiers fournis à Claude. Scope minimal pertinent. Zéro bloat contextuel. L'objectif : contraindre le modèle sans l'enfermer, lui donner des rails sans transformer son horizon en tunnel.
Les quatre principes Karpathy appliqués au code
Karpathy a condensé ses observations en quatre règles qui structurent le CLAUDE.md viral. Chaque principe cible un comportement problématique récurrent des LLMs face à la génération de code.
Think Before Coding : ne pas supposer, expliciter les hypothèses. Vous demandez "ajoute un endpoint pour exporter les factures en PDF". Claude doit d'abord reformuler la demande, lister les hypothèses (format PDF via quelle lib ? authentification requise ? pagination ?), poser des questions en cas d'ambiguïté, proposer plusieurs interprétations si la demande reste floue. Ce principe élimine les hallucinations en amont. Le modèle est forcé de clarifier avant d'exécuter. Concrètement, Claude répond "Je comprends que vous voulez un endpoint /invoices/:id/pdf. Dois-je utiliser pdfkit ou puppeteer ? Faut-il vérifier que l'utilisateur possède cette facture ?" au lieu de générer 200 lignes basées sur une supposition. Beaucoup plus robuste.
Simplicity First : code minimum viable, pas d'abstractions spéculatives. Claude a tendance à sur-concevoir. Vous demandez un helper pour formatter des dates, il crée une classe DateFormatter avec une factory, un registry, et trois design patterns superflus. Le principe Simplicity First impose : pas de features non demandées, pas de refactors opportunistes, pas de "ce serait mieux si on anticipait X". Juste le strict nécessaire. Ce principe s'avère crucial sur les monolithes legacy où chaque abstraction prématurée alourdit la dette technique exponentiellement.
Surgical Changes : toucher uniquement ce qui est requis. C'est le principe le plus puissant pour les scale-ups avec des bases de code matures. Claude doit modifier uniquement les lignes directement reliées à la demande. Pas de refactors latéraux, pas de "cleanup" non demandé, pas de changements de style sur des fichiers non concernés. Respecter le style existant même s'il est imparfait. Ne supprimer que les orphelins créés par ses propres modifications. En pratique, ce principe transforme des PRs de 300 lignes diffuses en PRs de 15 lignes ciblées. La review devient triviale, le risque de régression chute, la vélocité monte.
Goal-Driven Execution : transformer les demandes en objectifs vérifiables. Toute demande doit se convertir en un plan avec critères de succès mesurables (tests qui passent, checks de linter, benchmarks de perf). Claude décompose la tâche, propose un plan, exécute étape par étape, vérifie à chaque étape, et boucle jusqu'à validation. Ce principe aligne l'IA sur une discipline TDD. Vous demandez "corrige le bug de pagination sur /users", Claude répond "Je vais écrire un test qui reproduit le bug, puis modifier le contrôleur jusqu'à ce que le test passe". Le code produit est systématiquement testé. La traçabilité entre demande métier et scénario de test se trouve garantie.
Cas concret: refactor progressif d'un monolithe Rails sans explosion de scope
Vous gérez un monolithe Rails de 200 000 lignes avec une dette technique importante. Chaque feature prend trois fois plus de temps que prévu. Vous voulez utiliser Claude Code pour accélérer, mais vous craignez que le modèle transforme chaque correction de bug en refactoring sauvage.
Vous créez un CLAUDE.md à la racine du repo. Vous y encodez les quatre principes Karpathy, puis vous ajoutez des règles projet : "Respecter les conventions RSpec existantes. Ne jamais toucher aux models sans tests de régression. Les helpers doivent rester dans app/helpers, pas de nouvelle architecture. Les logs doivent utiliser Rails.logger, pas puts." Vous ajoutez aussi une liste des patterns interdits : "Pas de concerns sauf autorisation explicite. Pas de métaprogrammation sauf dans les gems. Pas de changements de schéma DB sans migration."
Vous demandez à Claude de corriger un bug sur l'export CSV des commandes. Sans CLAUDE.md, le modèle aurait probablement refactorisé toute la logique d'export, créé un service object, ajouté un cache, modifié trois contrôleurs adjacents. Avec le CLAUDE.md, Claude reformule d'abord : "Le bug concerne les colonnes manquantes dans le CSV ou la performance de génération ?" Vous précisez : "Colonnes manquantes, created_at et total_amount ne sont pas exportées." Claude propose un plan : "Je vais ajouter ces deux colonnes dans OrdersController#export, vérifier que les tests existants passent, et ajouter un test pour ces colonnes." Il modifie 4 lignes, ajoute 8 lignes de test, exécute la suite RSpec, valide. Aucun refactor latéral. Aucune abstraction spéculative. Un changement chirurgical.
Vous répétez l'opération sur 20 bugs similaires. Claude reste dans le scope à chaque fois. Les PRs sont petites, faciles à review, mergées en quelques heures. Vous commencez à affiner le CLAUDE.md en fonction des patterns de bugs récurrents. Vous ajoutez "Les exports doivent inclure created_at, updated_at, et id par défaut sauf mention contraire." Claude intègre cette règle dans les prochaines générations. Le fichier devient un artefact vivant qui encode les conventions implicites de votre équipe.
Après trois mois, vous constatez que la vélocité a augmenté de 40 % sur les tâches de correction de bugs. Les régressions ont baissé de 60 %. Les reviews de code prennent moitié moins de temps. Le CLAUDE.md fait 63 lignes. Il est versionné, commenté, et mis à jour à chaque retro.
Autoresearch: optimiser automatiquement vos skills de génération de code
Karpathy a introduit un pattern appelé autoresearch pour optimiser automatiquement des "skills" (prompts ou fichiers de config) en se basant sur une métrique d'accuracy mesurable. Le principe : vous définissez un jeu de tests représentatif, vous faites tourner le skill sur ce jeu, vous mesurez la correctness, vous laissez un pipeline modifier le skill et rerunner les tests jusqu'à convergence.
Sur un skill de fundraising, l'accuracy est passée de 70 % à 94 % après optimisation automatique. Un skill de qualification MEDDIC a bondi de 65 % à 91 %. Ces chiffres concernent des tâches non-code, mais le pattern s'applique directement à la génération de code si vous avez une métrique automatisable.
Cas d'usage pour une scale-up française : vous utilisez un agent IA interne pour générer des snippets d'API clients, des scripts d'intégration avec vos partenaires, ou des pipelines data. Vous définissez un banc de 100 tâches représentatives, chacune avec un expected output (tests qui passent, compilation OK, output conforme). Vous appliquez autoresearch : le pipeline fait tourner le skill sur ce banc, mesure la correctness, modifie le CLAUDE.md en boucle, reruns les tests. Après 10 itérations, vous passez de 60 % de tâches correctes à 88 %.
L'intérêt pour un CTO ou un VP Eng : vous transformez l'optimisation des prompts en un processus continu, mesurable, et automatisé. Vous intégrez ces pipelines dans votre CI/CD à côté des tests classiques. Vous monitorez l'accuracy des agents comme vous monitorez la couverture de tests. Vous faites évoluer vos skills au même rythme que votre code.
Le repo autoresearch de Karpathy a atteint 42 000 étoiles GitHub en une semaine. Ce n'est pas un framework lourd. C'est un pattern simple : définir une métrique, mesurer, optimiser, boucler. Applicable à n'importe quel agent LLM, n'importe quelle tâche de génération de code, dès que vous avez un oracle automatisable.
Knowledge base LLM-driven: structurer la doc technique comme un artefact de première classe
Karpathy pousse un modèle de gestion de la connaissance en trois couches pour les projets Claude Code. Première couche : raw resources (PDF, notes, transcripts, docs brutes). Deuxième couche : knowledge base (wiki en markdown, structuré, cross-référencé). Troisième couche : schema (fichier d'instructions qui décrit comment organiser et maintenir le wiki).
Claude lit les raw resources, génère le wiki, et l'audite en continu. Il détecte les contradictions, les infos obsolètes, les trous de documentation. Vous lui demandez "Quelle est notre politique de gestion des tokens JWT ?", Claude parcourt le wiki, trouve la page dédiée, et répond en citant les sections pertinentes. Si la page n'existe pas, Claude la crée à partir des raw resources disponibles (ADRs, RFCs, design docs).
Pour une scale-up française en phase de migration (par exemple REST vers GraphQL, ou monolithe vers microservices), ce pattern fonctionne comme un multiplicateur de cohérence. Vous créez un dossier docs/ avec trois sous-dossiers : raw/, wiki/, schema.md. Vous y versez tous vos ADRs, vos schémas d'architecture, vos RFCs. Vous écrivez un schema.md qui décrit la structure cible du wiki : "Une page par domaine métier (auth, billing, notifications). Chaque page doit inclure : contexte, décisions d'architecture, patterns autorisés, patterns interdits, points de friction fréquents."
Vous demandez à Claude de générer le wiki initial. Il parcourt les raw resources, extrait les infos, crée les pages, cross-référence. Vous obtenez un wiki de 30 pages en quelques minutes. Vous le reviewez, vous corrigez les erreurs, vous ajoutez des précisions. Ensuite, vous demandez à Claude de maintenir ce wiki. À chaque nouvelle RFC, il met à jour les pages concernées. À chaque changement d'architecture, il audite les contradictions. À chaque onboarding, il génère un parcours personnalisé à partir du wiki.
L'effet pour l'équipe : onboarding deux fois plus rapide, moins de questions répétitives en Slack, meilleure cohérence entre services. Le wiki devient la source de vérité partagée entre humains et agents LLM. Les nouveaux devs lisent le wiki. Claude lit le wiki. Les décisions d'architecture sont documentées dans le wiki. Les agents génèrent du code conforme au wiki.
Ce pattern s'appelle "docs-as-code assistées par LLM". Vous versionnez le wiki comme du code. Vous le reviewez comme du code. Vous le déployez comme du code. Et vous laissez Claude le maintenir comme un pair-programmer maintient des tests.
Intégrer les principes Karpathy dans votre workflow dès demain
Vous n'avez pas besoin de refondre votre stack pour appliquer ces méthodes. Vous commencez petit. Vous créez un CLAUDE.md minimal à la racine de votre repo principal. Vous y copiez les quatre principes Karpathy (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution). Vous ajoutez 5 à 10 lignes spécifiques à votre projet : conventions de code, patterns interdits, erreurs fréquentes.
Vous testez sur une tâche simple : corriger un bug, ajouter un endpoint, écrire un test. Vous observez le comportement de Claude. Vous notez les déviations (refactors non demandés, hypothèses incorrectes, abstractions spéculatives). Vous enrichissez le CLAUDE.md en fonction de ces observations. Vous itérez.
Après une semaine, vous avez un CLAUDE.md de 40 lignes qui encode les conventions implicites de votre équipe. Vous le partagez avec les autres devs. Vous le versionnez. Vous le faites évoluer à chaque retro. Il devient un artefact de première classe, au même titre que votre styleguide ou votre testing pyramid.
Si vous voulez aller plus loin, vous créez un dossier docs/ avec le pattern knowledge base (raw / wiki / schema). Vous y versez vos ADRs, vos RFCs, vos design docs. Vous demandez à Claude de générer le wiki initial. Vous le reviewez, vous le corrigez, vous le maintenez. Vous intégrez ce wiki dans votre workflow d'onboarding et de code review.
Si vous avez des agents IA internes (génération de scripts, d'API clients, de pipelines data), vous définissez un banc de tests représentatif. Vous appliquez autoresearch : mesurer, optimiser, boucler. Vous monitorez l'accuracy comme une métrique produit. Vous intégrez ces pipelines dans votre CI/CD.
L'investissement initial est minimal. Un CLAUDE.md de 50 lignes se rédige en une heure. Un wiki initial se génère en quelques minutes. Un pipeline d'autoresearch se met en place en une journée. Le retour sur investissement est mesurable : vélocité en hausse, régressions en baisse, reviews plus rapides, onboarding accéléré.
FAQ
Comment installer le fichier CLAUDE.md de Karpathy dans mon projet ?
Deux options. Première option : via le marketplace de Skills dans Claude Code (installation globale, appliquée à tous vos projets). Deuxième option : via un curl qui télécharge le fichier et l'ajoute à la racine de votre repo sans conflit avec un CLAUDE.md existant. Commande : curl -o CLAUDE.md https://raw.githubusercontent.com/andrej-karpathy/andrej-karpathy-skills/main/CLAUDE.md. Vous éditez ensuite le fichier pour ajouter vos règles projet (conventions, patterns interdits, contexte métier). Vous versionnez ce fichier dans Git. Claude le lit automatiquement à chaque session.
Le fichier CLAUDE.md fonctionne-t-il avec d'autres LLMs que Claude ?
Le pattern est universel mais l'implémentation est spécifique à Claude Code. D'autres LLMs (GPT-4, Gemini, Codex) ne lisent pas automatiquement un fichier CLAUDE.md. Vous pouvez adapter le principe en créant un fichier PROJECT.md ou PROMPT.md que vous injectez manuellement dans le contexte de chaque session. Certains outils (Cursor, Cody, GitHub Copilot Workspace) commencent à supporter des fichiers d'instructions projet similaires. Attendez-vous à une standardisation progressive de ce pattern en 2025-2026, chaque LLM implémentant sa propre version.
Combien de lignes doit faire un CLAUDE.md optimal ?
Karpathy recommande moins de 50 lignes de règles génériques, complétées par 10 à 15 lignes spécifiques au projet. L'objectif : éviter le bloat contextuel. Un fichier trop long dilue les instructions critiques. Un fichier trop court laisse trop de latitude au modèle. La zone optimale se situe entre 40 et 65 lignes. Vous commencez avec les quatre principes Karpathy (20 lignes), vous ajoutez vos conventions de code (10 lignes), vos patterns interdits (5 lignes), vos règles de tests (5 lignes). Vous enrichissez progressivement en fonction des erreurs récurrentes observées. Vous supprimez les règles obsolètes. Le fichier reste compact, ciblé, actionnable.
L'autoresearch peut-il vraiment faire passer l'accuracy de 65 % à 94 % sur du code ?
Les chiffres 65 % vers 94 % proviennent d'un skill de fundraising optimisé via autoresearch, pas d'un benchmark de génération de code pur. Le pattern s'applique au code si vous avez une métrique automatisable (tests qui passent, compilation OK, conformité à un schéma). L'amélioration dépend de la qualité de votre jeu de tests et de la clarté de votre métrique. Sur des tâches bien définies (génération de scripts, d'API clients, de migrations DB), des gains de 20 à 30 points d'accuracy sont plausibles. Sur des tâches plus ouvertes (refactoring, design d'architecture), l'amélioration sera plus modeste. Le vrai intérêt d'autoresearch : transformer l'optimisation des prompts en un processus continu et mesurable, au lieu d'un bricolage ad-hoc.
Conclusion
Le CLAUDE.md de Karpathy n'est pas un framework complexe. C'est un fichier texte de 65 lignes qui encode quatre observations sur les erreurs récurrentes des LLMs en situation de code. Think Before Coding élimine les hallucinations par anticipation. Simplicity First bloque la sur-ingénierie. Surgical Changes empêche les refactors sauvages. Goal-Driven Execution aligne l'IA sur une discipline TDD.
L'impact est mesurable. Sur des skills non-code, l'accuracy bondit de 65 % à 94 % après optimisation automatique. Sur des projets code, les équipes constatent une vélocité en hausse de 40 %, des régressions en baisse de 60 %, des reviews deux fois plus rapides. Le pattern knowledge base (raw / wiki / schema) accélère l'onboarding et garantit la cohérence entre services. Autoresearch transforme l'optimisation des prompts en un processus continu intégré au CI/CD.
Vous commencez demain. Vous créez un CLAUDE.md minimal. Vous testez sur une tâche simple. Vous observez, vous enrichissez, vous itérez. Après une semaine, vous avez un artefact de première classe qui encode les conventions implicites de votre équipe. Après un mois, vous avez un wiki LLM-driven qui sert de source de vérité partagée. Après trois mois, vous avez des pipelines d'autoresearch qui optimisent vos agents en continu. L'investissement initial est minimal. Le retour sur investissement est exponentiel.
