CLAUDE.md : le fichier qui améliore les agents de codage

Un bon CLAUDE.md ne rend pas le modèle plus intelligent. Il rend l'assignation moins ambiguë chaque fois que l'agent entre dans votre dépôt.

Ce mécanisme modeste explique pourquoi un dépôt construit autour de quatre règles de codage en langage clair est devenu l'un des projets d'agent les plus visibles de 2026. Les instructions demandent à l'agent de surfacer les hypothèses, de préférer les implémentations simples, de garder les modifications chirurgicales et de définir un succès vérifiable. Aucun de ces éléments n'est une technique d'ingénierie logicielle nouvelle. C'est le fait de mettre ces quatre éléments en contexte avant chaque tâche qui est utile.

Le titre viral disait qu'un dépôt avait atteint 91 000 étoiles GitHub. Au 2 août 2026, le dépôt avait migré de forrestchang vers multica-ai, évolué en plugins et règles d'éditeur, et atteint 198 529 étoiles selon l'API GitHub.^[1] Le chiffre continuera à changer. La leçon durable est comment les petites instructions persistantes changent le comportement des agents.

TL;DR

• CLAUDE.md est un fichier Markdown contenant des instructions persistantes que Claude Code charge comme contexte.^[2]
• Le dépôt viral a condensé les défaillances courantes des agents en quatre règles : penser avant de coder, priorité à la simplicité, modifications chirurgicales et exécution axée sur les objectifs.^[3]
• Le fichier fonctionne mieux quand il contient des faits et règles nécessaires dans presque chaque session : commandes, architecture, conventions, limites et vérification.
• CLAUDE.md est un contexte, non pas une application forcée. Utilisez des permissions ou des hooks pour les actions qui doivent être techniquement bloquées.^[2]
• Gardez les procédures spécifiques à une tâche dans les skills et les conseils spécifiques à un fichier dans .claude/rules/ ; charger tout globalement gaspille le contexte.
• Un fichier utile est assez court pour être maintenu, assez spécifique pour être testé et révisé quand l'agent répète une erreur.

Qu'est-ce que CLAUDE.md ?

CLAUDE.md est le fichier d'instructions de projet de Claude Code. C'est un Markdown ordinaire, généralement commité à la racine du dépôt, qui donne à l'agent un contexte durable comme :

• comment installer, tester, construire et formater le projet ;
• les parties de l'architecture qui ne sont pas évidentes à partir des noms de fichiers ;
• les conventions de nommage et de style de code ;
• quels fichiers générés ne doivent pas être édités manuellement ;
• les vérifications qui doivent passer avant qu'une tâche soit complète ;
• les limites de sécurité spécifiques au dépôt.

Claude Code lit le fichier au début d'une session. Anthropic le décrit comme l'un des deux mécanismes de mémoire : les gens écrivent les instructions de CLAUDE.md, tandis que la mémoire automatique de Claude stocke les motifs qu'elle apprend des corrections.^[2]

Cela semble être une configuration, mais Anthropic fait une distinction importante. Ces instructions entrent dans le contexte du modèle ; elles ne sont pas des contrôles stricts. Si « ne jamais déployer en production » doit être garanti, un hook PreToolUse ou une limite de permission est le niveau approprié. Une phrase en Markdown peut guider le comportement. Elle ne peut pas fournir une garantie de sécurité.

Pourquoi le fichier de quatre règles est devenu viral

Le dépôt maintenant appelé multica-ai/andrej-karpathy-skills dit que ses directives ont été dérivées des observations publiques d'Andrej Karpathy sur les modes de défaillance des modèles de codage.^[3] Sa popularité est facile à suranalyser. Chaque règle mappe une frustration familière à un comportement que l'agent peut effectuer.

Ces règles n'enseignent pas TypeScript, la conception de bases de données ou le débogage. Elles façonnent la façon dont le modèle aborde l'incertitude et la portée. Cela les rend réutilisables dans les dépôts.

La simplicité est aussi un avantage social. Une équipe peut lire quatre principes en deux minutes, être en désaccord avec un, l'éditer et examiner la modification dans Git. Il n'y a pas de plateforme de prompt cachée à administrer.

Les quatre principes, traduits en comportement de projet

1. Penser avant de coder

La directive originale demande à l'agent d'énoncer les hypothèses, de présenter plusieurs interprétations si nécessaire, de contester la complexité inutile et de s'arrêter quand il est vraiment confus.^[3]

L'énoncé spécifique au projet le renforce :

Avant de modifier un contrat d'API, identifiez tous les consommateurs en repo et déclarez
si la modification est rétrocompatible. Si le comportement du produit est ambigu,
arrêtez-vous et posez la question ; ne choisissez pas silencieusement un comportement.

Le principe générique définit la posture. L'ajout concret dit à l'agent où les mauvaises hypothèses sont coûteuses.

2. Priorité à la simplicité

« Ne pas sur-ingéniérer » est directionnellement utile mais difficile à vérifier. Ajoutez la définition locale du dépôt de simple :

Préférez un utilitaire existant à une nouvelle abstraction. N'introduisez pas de service,
fabrique ou flag de configuration pour un seul site d'appel. Implémentez uniquement
le comportement demandé ; listez les suivis optionnels au lieu de les construire.

Cela réduit une tendance du modèle prévisible : résoudre une famille hypothétique de problèmes futurs au lieu du problème courant.

3. Modifications chirurgicales

Les agents voient les opportunités de nettoyage à proximité parce qu'ils lisent largement. Cela ne signifie pas qu'une tâche autorise chaque nettoyage.

Chaque ligne modifiée doit retrace la demande. Préservez le formatage et la dénomination environnants.
Supprimez les imports rendus inutilisés par votre modification, mais signalez plutôt le code mort
non lié au lieu de le supprimer.

Les petits diffs sont plus faciles à examiner, tester, annuler et assigner. Ils réduisent aussi les risques qu'un agent casse quelque chose dont il n'a pas compris le but.

4. Exécution axée sur les objectifs

Une instruction telle que « le rendre fonctionnel » laisse l'état final indéfini. Traduisez la tâche en résultat que l'agent peut vérifier :

Pour les corrections de bogues, reproduisez la défaillance avec un test avant de modifier
le code de production. Pendant l'itération, exécutez les vérifications les plus étroites pertinentes
et toutes les vérifications de projet requises avant la fin. Signalez les commandes et résultats.

C'est là que l'autonomie devient utile. Quand le succès est observable, l'agent peut itérer sur les défaillances au lieu de s'arrêter après la première modification plausible.

Ce qui devrait être dans CLAUDE.md

Anthropic recommande de garder les faits dans CLAUDE.md que Claude devrait avoir dans chaque session, et de déplacer les procédures multi-étapes ou étroites vers des mécanismes plus ciblés.^[2] Un test utile est : « Que dirais-je lors de l'intégration pour presque toutes les tâches ? »

Mettez ceux-ci dans le fichier racine

• une description de paragraphe du projet et de l'architecture ;
• package manager et commandes canoniques d'installation, dev, test, type-check et build ;
• propriété du répertoire et limites des fichiers générés ;
• des règles qui s'appliquent dans les langages ou paquets ;
• définition de « fait » ;
• erreurs haute fréquence et leur correction ;
• où trouver des instructions plus profondes.

Mettez ceux-ci ailleurs

Un modèle CLAUDE.md concis

Copiez ceci comme point de départ, puis remplacez chaque élément entre crochets. Supprimez les sections qui ne limitent pas votre projet.

# Instructions de projet

## Projet

[Un paragraphe : ce que ce dépôt expédie, son runtime principal et la limite architecturale
la plus importante.]

## Commandes

- Installer : `[commande]`
- Développer : `[commande]`
- Test ciblé : `[commande avec fichier ou motif]`
- Test complet : `[commande]`
- Vérification de type : `[commande]`
- Construire : `[commande]`

## Avant de modifier

- Lisez l'implémentation existante la plus proche et les tests avant de proposer une modification.
- Énoncez les hypothèses qui affectent le comportement public, les données, la sécurité ou la compatibilité.
- Si la demande a plusieurs interprétations sensiblement différentes, posez une question.

## Portée

- Implémentez uniquement le comportement demandé.
- Préférez les motifs existants et les utilitaires aux nouvelles abstractions.
- Gardez les diffs chirurgicaux ; ne refactorisez pas le code adjacent sauf si c'est requis.
- Supprimez uniquement le code mort créé par votre modification.

## Limites du projet

- `[chemin]` est généré ; modifiez `[chemin source ou commande]` à la place.
- `[paquet]` possède `[responsabilité]` ; ne le dupliquez pas dans `[autre paquet]`.
- N'exposez jamais `[catégorie de donnée secrète ou privée]` dans les journaux ou les fixtures.

## Style

- [Deux à cinq règles qui diffèrent des défauts du formateur ou sont faciles à rater.]
- Correspondez au fichier environnant quand aucune règle explicite ne s'applique.

## Vérification

- Pour une correction de bogue, ajoutez ou mettez à jour un test qui échoue avant la correction.
- Lors de l'itération, exécutez la vérification la plus étroite pertinente.
- Avant la fin, exécutez : `[commandes requises]`.
- Signalez les fichiers modifiés, les commandes exécutées, les résultats et tout risque non vérifié.

## Instructions plus profondes

- Travail API : `.claude/rules/api.md`
- Modifications de base de données : `[chemin skill ou documentation]`
- Publications : `[chemin skill ou documentation]`

Le modèle est volontairement simple. Un CLAUDE.md ne doit pas lire comme un manifeste motivationnel. Il doit réduire les décisions que l'agent aurait d'autre part à deviner.

Comment Claude Code charge plusieurs fichiers d'instructions

Claude Code remonte l'arborescence des répertoires à partir du répertoire de travail actuel et charge les fichiers CLAUDE.md et CLAUDE.local.md qu'il trouve. Les instructions plus proches du répertoire de lancement apparaissent plus tard dans le contexte. Les fichiers imbriqués sous le répertoire de travail se chargent quand Claude lit des fichiers dans ces sous-répertoires.^[2]

Pour un monorepo, cela permet une hiérarchie utile :

repo/
├── CLAUDE.md                 # Faits du projet à l'échelle de l'organisation
├── .claude/
│   └── rules/
│       ├── testing.md        # Règle partagée sans portée
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Architecture spécifique au web et vérifications
│   └── worker/
│       └── CLAUDE.md         # Contraintes runtime du worker
└── CLAUDE.local.md           # Notes locales réservées aux développeurs

Les fichiers sont concaténés comme contexte plutôt que de se comporter comme un remplacement strict de configuration. Les règles contradictoires peuvent donc produire un comportement incohérent. Examinez la hiérarchie périodiquement et supprimez les instructions obsolètes.

Comment améliorer le fichier à partir des défaillances réelles

N'essayez pas de prédire chaque erreur possible dès le premier jour. Commencez petit et utilisez la friction répétée comme backlog.

1. Enregistrez la défaillance. Qu'a fait l'agent et qu'attendiez-vous ?
2. Trouvez le bon niveau. S'agit-il d'une instruction universelle, d'une règle spécifique à un chemin, d'une procédure de tâche ou d'un contrôle de sécurité dur ?
3. Écrivez une règle observable. Remplacez « soyez prudent » par l'action et la condition.
4. Testez-la sur une tâche similaire. Confirmez que le comportement s'améliore sans bloquer les travaux triviaux.
5. Supprimez les règles obsolètes. Le contexte a un coût ; une instruction obsolète peut être pire que pas d'instruction.

Le déclencheur pratique d'Anthropic est mémorable : ajoutez quelque chose quand Claude commet la même erreur une deuxième fois, quand l'examen du code détecte une connaissance que l'agent aurait dû avoir, ou quand vous répétez la même correction entre les sessions.^[2]

Cinq erreurs CLAUDE.md à éviter

Écrire des aspirations au lieu d'instructions

« Écrivez du code excellent et robuste » n'apporte aucune nouvelle information. « Exécutez pnpm test --filter api après les modifications sous packages/api » peut être suivi et vérifié.

Copier un énorme livre de règles générique

Un modèle public peut fournir des idées, mais chaque ligne inconditionnelle consomme du contexte et peut entrer en conflit avec le projet. Gardez les quatre principes comportementaux larges s'ils aident ; remplacez les conseils technologiques génériques par des faits locaux.

Coder les faits que l'agent peut découvrir peu coûteusement

Vous avez rarement besoin de lister tous les répertoires. Expliquez les limites que les noms de fichiers ne révèlent pas, comme quel paquet possède l'autorisation ou quelle source génère un client archivé.

Traiter les instructions comme des contrôles de sécurité

Ne dépendez jamais de « ne lisez pas les secrets » ou « ne déployez pas » comme seule protection. Utilisez les identifiants limités, les permissions, le sandboxing et les hooks pour les limites strictes.

Ne jamais examiner le fichier

Les commandes changent, les paquets se déplacent et les anciennes exceptions deviennent le comportement par défaut. Assignez la propriété et examinez CLAUDE.md comme du code.

Comment savoir si cela fonctionne

Évitez de juger le fichier sur la base que une démo semble impressionnante. Mesurez le travail que l'équipe examine déjà :

• lignes modifiées médiane par tâche terminée ;
• fichiers non liés touchés ;
• commentaires d'examen de code causés par les violations de convention du dépôt ;
• succès au premier passage du test ;
• tâches réouvertes après une completion revendiquée ;
• clarifications répétées qui devraient devenir du contexte persistant.

Le dépôt viral suggère les mêmes tests au niveau des résultats : moins de modifications de diff inutiles, moins de réécritures causées par une surcomplexité, et des clarifications avant l'implémentation plutôt qu'après les erreurs.^[3]

FAQ

Où CLAUDE.md doit-il aller ?

Pour les instructions de projet partagées par l'équipe, placez-le dans ./CLAUDE.md ou ./.claude/CLAUDE.md et committez-le. Utilisez ~/.claude/CLAUDE.md pour les instructions personnelles entre les projets et CLAUDE.local.md pour les notes personnelles dans un projet.^[2]

CLAUDE.md fonctionne-t-il avec Cursor ou d'autres agents de codage ?

CLAUDE.md est une convention Claude Code. Le dépôt viral expédie également les règles Cursor et un plugin, tandis que d'autres agents peuvent utiliser des fichiers comme AGENTS.md ou des répertoires de règles spécifiques aux produits. Gardez une source canonique et adaptez-la délibérément plutôt que de supposer que chaque outil charge le même fichier.

Quel devrait être la longueur de CLAUDE.md ?

Il n'y a pas de compte de lignes universel. Il devrait contenir uniquement les informations précieuses dans presque chaque session. Si une section s'applique à un répertoire ou un workflow, déplacez-la vers une règle limitée en chemin ou skill.

CLAUDE.md peut-il arrêter les commandes destructrices ?

Il peut instruire Claude de ne pas les exécuter, mais Anthropic décrit explicitement le fichier comme contexte plutôt que configuration appliquée. Utilisez les permissions ou hooks pour une prévention fiable.^[2]

Comment créer le premier fichier ?

Exécutez /init dans Claude Code pour générer un CLAUDE.md de démarrage, ou créez le fichier Markdown manuellement. Puis exécutez /context pour confirmer qu'il s'est chargé et /memory pour inspecter ou modifier les fichiers mémoire.^[4]

Le fichier est simple parce que le problème est répétitif

Les agents de codage n'ont pas besoin d'une constitution de 500 lignes avant de pouvoir corriger un bogue. Ils ont besoin de quelques faits du projet qu'ils ne peuvent pas déduire, une limite claire autour du changement demandé et une vérification qui distingue la fin réelle de la confiance.

C'est pourquoi quatre règles ordinaires ont parcouru si loin. Elles abordent les erreurs que les développeurs voient quotidiennement, vivent dans un format que toute l'équipe peut modifier et se chargent avant que l'agent ne commence à prendre des décisions. Commencez là. Ajoutez la connaissance du projet uniquement quand elle prévient une défaillance réelle et appliquez les limites critiques en dehors du prompt.

Si vous êtes nouveau dans l'outil lui-même, commencez par le guide plus large sur l'utilisation de Claude Code. Utilisez cet article quand l'installation est terminée et que la prochaine question est ce que votre agent devrait savoir chaque fois qu'il entre dans le repo.

Références

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Lectures complémentaires

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models