Réponse courte : CLAUDE.md est le fichier de contexte persistant que l’outil développeur d’Anthropic, Claude Code, lit au début de chaque session. En 2026 il prend en charge quatre scopes (managed / project / user / local) et une syntaxe d’imports (
@path/to/file) pour intégrer d’autres fichiers. L’auto memory apporté en v2.1.59 permet à Claude d’accumuler des connaissances dans unMEMORY.mdde son propre chef ; ensemble ils dotent le projet d’une mémoire à deux couches. Entre novembre 2025 et janvier 2026, Andrej Karpathy a basculé 80 % de sa routine de coding vers l’agent-driven coding, qualifiant ce passage de « plus grand changement de workflow en environ 20 ans de programmation. » En avril 2026, il a publié le gist idea file et redéfini CLAUDE.md comme le fichier schéma colonne vertébrale d’une architecture de connaissance personnelle composée deraw/(sources),wiki/(base de connaissances maintenue par le LLM) etCLAUDE.md(schéma). Ce guide passe en revue toutes ces innovations et l’allure d’un CLAUDE.md efficace en 2026.
À l’ère de la fusion entre IA et développement, ce que vous dites à l’IA et comment détermine la productivité réelle que vous obtenez en retour. Depuis mars 2026, la documentation officielle d’Anthropic est passée à sa nouvelle adresse (code.claude.com/docs/en/memory) et CLAUDE.md reste le concept le plus critique de Claude Code, autour duquel des couches complémentaires — auto memory, path-scoped rules, imports, subagent memory — se sont formées. Les publications de Karpathy ces six derniers mois ont propulsé ce mécanisme au-delà d’un simple fichier de configuration vers l’architecture centrale de la connaissance des logiciels de l’ère IA.
Andrej Karpathy : de Software 2.0 à l’Idea File
Andrej Karpathy (né le 23 octobre 1986 à Bratislava) est l’un des dix ingénieurs les plus influents de l’IA moderne. Il a terminé son doctorat en informatique à Stanford sous la direction de Fei-Fei Li en 2016. Trois étapes structurent sa carrière : chercheur fondateur d’OpenAI (2015-2017), puis Director of AI chez Tesla (2017-2022) en charge d’Autopilot Vision, retour bref chez OpenAI en 2023, et fondation d’Eureka Labs en 2024. Sa chaîne YouTube, qui héberge la série marathon « Let’s build GPT from scratch », dépasse 2 millions d’abonnés.
Lire Karpathy comme un chercheur strictement technique est incomplet. C’est aussi le designer du vocabulaire créatif de l’IA. Dans Software 2.0 (2017) il soutenait que les programmes sont de plus en plus « écrits » non plus par des développeurs mais par des réseaux neuronaux apprenant des poids. Provocant en 2017, réalité partagée du secteur en 2026. Vibe coding — construire du logiciel en discutant avec l’IA plutôt qu’en tapant directement le code — est le terme qu’il a popularisé début 2025. Agentic coding désigne l’automatisation de tâches longues avec des modèles autonomes comme Claude Code, Codex CLI, Aider et Cline.
La dernière rupture est survenue entre novembre 2025 et janvier 2026. Sur cette période, Karpathy a déplacé 80 % de sa routine du coding manuel vers l’agent-driven coding et a qualifié ce passage de « plus grand changement de workflow en environ 20 ans de programmation. » Claude Code et son fichier mémoire CLAUDE.md étaient au centre. En avril 2026, il a poussé le sujet d’un cran avec l’« idea file » : une nouvelle architecture personnelle de connaissance fondée sur partager des idées, pas du code. Selon ses mots : « You just share the idea, then the other person’s agent customizes & builds it for your specific needs. »
📺 Le point de départ de cet article est la keynote de Karpathy « Software Is Changing (Again) » à la Y Combinator AI Startup School 2024. Vibe coding et agentic coding y sont résumés le plus clairement.
Qu’est-ce que CLAUDE.md et comment s’articule-t-il avec l’auto memory ?
CLAUDE.md est le fichier d’instructions persistant que vous écrivez et maintenez ; Claude Code le lit au début de chaque session. La doc d’Anthropic le dit clairement : « Instructions you write to give Claude persistent context. » En 2026 une seconde couche de mémoire a été ajoutée : auto memory. Le partage : vous écrivez CLAUDE.md (règles, architecture) ; Claude écrit l’auto memory (les enseignements qu’il a dérivés de vos corrections et préférences passées). L’auto memory est arrivée avec Claude Code v2.1.59 et persiste sous ~/.claude/projects/<project>/memory/MEMORY.md. Au début de chaque chat, les 200 premières lignes (ou 25 Ko) de MEMORY.md sont injectées dans le contexte.
| Caractéristique | CLAUDE.md | Auto memory |
|---|---|---|
| Auteur | Vous | Claude |
| Type de contenu | Instructions et règles | Apprentissages dérivés et patterns |
| Scope | Projet, utilisateur ou organisation | Par worktree |
| Chargement | Complet à chaque session | 200 premières lignes / 25 Ko à chaque session |
| Usage principal | Standards de code, architecture, workflow | Commandes de build, observations de debug, préférences |
CLAUDE.md a elle-même gagné une structure plus riche en 2026. Quatre scopes sont supportés : des fichiers managed policy déployés par IT/DevOps à l’échelle de l’organisation (macOS sous /Library/Application Support/ClaudeCode/CLAUDE.md, Linux sous /etc/claude-code/CLAUDE.md, Windows sous C:Program FilesClaudeCodeCLAUDE.md) ; des fichiers projet spécifiques à l’équipe (./CLAUDE.md ou ./.claude/CLAUDE.md) ; des fichiers user couvrant tous vos projets (~/.claude/CLAUDE.md) ; et des fichiers local pour des notes personnelles propres au projet, mis dans .gitignore (./CLAUDE.local.md). Les scopes plus spécifiques l’emportent sur les plus larges.
Le chargement s’est aussi élargi. Partant du répertoire de travail, Claude remonte jusqu’à la racine du système de fichiers en cherchant CLAUDE.md et CLAUDE.local.md dans chaque dossier ; toutes les correspondances entrent dans le contexte. Les CLAUDE.md des sous-dossiers ne sont pas chargés au lancement — ils chargent à la demande quand Claude lit un fichier dans ce dossier. Si vous ajoutez d’autres dossiers via --add-dir, définissez CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 pour charger leurs CLAUDE.md aussi. Après une compaction (/compact), le CLAUDE.md à la racine du projet est rechargé automatiquement ; les fichiers imbriqués reviennent à la prochaine lecture pertinente.
Nouveautés 2026 : Imports, .claude/rules/, interop AGENTS.md
Pour éviter qu’un CLAUDE.md ne grossisse en un fichier unique gigantesque, Anthropic a standardisé la syntaxe @path/to/import. Elle insère d’autres fichiers Markdown dans CLAUDE.md ; chemins relatifs et absolus pris en charge ; récursion autorisée jusqu’à 5 sauts. Usage typique :
See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md
- personal preferences @~/.claude/my-project-instructions.md
Deuxième grande nouveauté : le dossier .claude/rules/ et ses path-scoped rules. Au lieu d’entasser toutes les instructions dans un CLAUDE.md, scindez les règles en fichiers Markdown thématiques, avec un YAML frontmatter qui ne les active que lorsque Claude touche des chemins correspondants :
---
paths:
- "src/api/**/*.ts"
- "lib/**/*.{ts,tsx}"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Les fichiers de règles sans frontmatter paths se chargent toujours ; ceux avec ne s’activent que quand Claude travaille sur un fichier correspondant. Mécanisme critique pour les monorepos où plusieurs équipes maintiennent leurs propres jeux de règles. Le réglage claudeMdExcludes permet aussi de désactiver sélectivement des CLAUDE.md des dossiers ancêtres.
Troisième ajout : l’interopérabilité AGENTS.md. Cursor, Codex, Aider et d’autres agents lisent AGENTS.md ; Claude Code ne lit que CLAUDE.md. La façon standard de résoudre :
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Même jeu d’instructions partagé sur tous vos outils d’agents ; la courte section spécifique à Claude ajoute les extras. Côté commandes slash : /init rédige le fichier, /memory affiche les fichiers chargés et permet de les éditer, le hook InstructionsLoaded sert à déboguer quoi s’est chargé quand. En définissant CLAUDE_CODE_NEW_INIT=1, /init devient un flux multi-phases interactif : un subagent inspecte le repo, vous interroge sur les lacunes et propose un fichier passable en revue avant écriture.
L’approche idea file de Karpathy (avril 2026)
Le 3 avril 2026, Karpathy a proposé sur X puis dans un gist GitHub un nouveau format de partage : l’« idea file ». Là où l’open source classique partage du code, l’idea file partage l’idée, et l’agent de l’autre côté la reconstruit pour son environnement. La raison est simple : en 2026 — avec des modèles d’agents assez puissants — copier l’intention est plus efficace que copier le code au pixel près.
La forme concrète est une structure à trois couches. Couche un : le dossier raw/ ; articles, papiers, images, datasets atterrissent ici. Le LLM lit mais ne modifie jamais ce dossier — les sources sont immuables et vérifiables. Couche deux : le dossier wiki/ ; les pages de synthèse, de concept et d’entités produites par le LLM y vivent, recoupées et croissant cumulativement au lieu d’être redérivées par requête. Couche trois : le fichier CLAUDE.md (alternativement AGENTS.md ou OPENCODE.md) ; il définit le schéma du système global et la façon de le maintenir.
Le système tourne autour de trois opérations. Ingest : quand une nouvelle source arrive dans raw/, le LLM la lit et met à jour simultanément 10-15 pages wiki, garde un index et un journal d’activité. Query : les questions traversent la structure ; les réponses précieuses sont reclassées comme nouvelles pages — la connaissance se compose. Lint : des contrôles de santé périodiques font émerger contradictions, pages orphelines, concepts manquants et revues suggérées. Karpathy relie cela au concept Memex de Vannevar Bush en 1945 ; la question non résolue de Bush « qui maintient ? » trouve enfin sa réponse avec les LLM.
Cette architecture diverge du RAG (Retrieval-Augmented Generation) classique sur un point clé. Le RAG revient aux sources et synthétise à chaque requête ; l’approche idea file compile la connaissance une fois et la garde à jour, plutôt que de la redériver à chaque appel. Selon Karpathy : « The knowledge is compiled once and then kept current, not re-derived on every query. » CLAUDE.md est le fichier schéma qui transforme un chatbot générique en un mainteneur wiki discipliné.
Comment écrire un CLAUDE.md efficace ? (standards 2026)
Quatre principes issus de la doc Anthropic forment le noyau de l’écriture efficace d’un CLAUDE.md. Taille : maintenir le fichier sous 200 lignes ; les fichiers plus longs consomment plus de contexte et baissent le taux d’adhésion. Si les instructions grandissent, scinder via path-scoped rules ou imports. Structure : instructions groupées sous des titres Markdown et des bullets, bien plus scannables que des paragraphes diffus ; Claude lit comme un humain. Spécificité : instructions concrètes et vérifiables. « Format the code properly » → « Use 2-space indentation » ; « Test your changes » → « Run npm test before committing » ; « Keep files organised » → « API handlers live in src/api/handlers/ ». Cohérence : en cas d’instructions contradictoires, Claude en choisit une au hasard ; revoyez périodiquement le CLAUDE.md et les imbrications.
Quand ajouter dans CLAUDE.md ? La recommandation d’Anthropic est nette : « Treat CLAUDE.md as the place you write down what you’d otherwise re-explain. » Si Claude fait la même erreur deux fois, si une convention attrapée en code review devrait aussi être connue de Claude, si vous écrivez aujourd’hui la même correction que la session passée, ou si un nouveau coéquipier aurait besoin d’un contexte pour être productif — tout cela va dans CLAUDE.md. Les procédures multi-étapes ou les règles applicables uniquement à un recoin du code vont dans une skill ou une path-scoped rule, pas dans CLAUDE.md.
Le modèle ci-dessous est le point de départ minimal fonctionnel pour un CLAUDE.md en 2026. Copiez-le directement :
# Project Name
## What this is
One-paragraph summary of what the project does and why it exists.
## Tech stack
- Language: Python 3.12 / TypeScript 5.4
- Framework: FastAPI / Next.js 15
- DB: PostgreSQL 16
- Tests: pytest + httpx / vitest
## Commands
- Install: `uv sync` / `pnpm install`
- Run dev: `uv run uvicorn app.main:app --reload` / `pnpm dev`
- Test: `uv run pytest -x` / `pnpm test`
- Lint: `uv run ruff check .` / `pnpm lint`
- Typecheck: `uv run mypy app/` / `pnpm typecheck`
## Conventions
- Type hints everywhere
- Public functions: docstrings (Google style)
- Tests live in `tests/` matching `app/` structure
- No global state — pass dependencies explicitly
## Don't
- No emoji in code or commits
- No `print()` for debug — use `logger.debug()`
- No new dependencies without justifying in PR description
- Don't write code comments that just restate what code does
## Common pitfalls
- DB migrations: run `alembic upgrade head` after pulling
- The `vendor/` folder is git-tracked but not editable
- `pytest` requires `.env.test` (copy from `.env.test.example`)
## Architecture in 3 lines
- Request → middleware (auth) → router → service → repository → DB
- Async I/O end-to-end with `asyncpg`
- Background jobs in `app/jobs/` use `arq` (not Celery)
## Imports
@README.md
@docs/architecture.md
@AGENTS.md
Deux conseils tirés de la pratique de Karpathy : premièrement l’analogie « AI is a junior dev with infinite enthusiasm » — l’agent IA ressemble à un développeur junior talentueux mais amnésique qui attend son briefing chaque matin ; CLAUDE.md est ce briefing par écrit. Deuxièmement le principe de « living memory » : le fichier n’est pas un README qu’on écrit une fois et qu’on oublie ; il doit grandir avec chaque nouvelle erreur de l’IA.
CLAUDE.md vs Cursor Rules vs ChatGPT Custom Instructions
Les trois principaux outils de coding IA stockent le contexte développeur différemment. En 2026 le système CLAUDE.md de Claude Code est le plus riche et le plus hiérarchique — managed/project/user/local + path-scoped rules + auto memory + imports. Cursor offre une structure similaire via Markdown + YAML frontmatter dans .cursor/rules/, sans scope utilisateur partagé. ChatGPT Custom Instructions est lié à votre compte OpenAI, stocké dans le cloud, deux champs en clair — pas de contexte projet.
| Dimension | CLAUDE.md (Claude Code) | Cursor Rules | ChatGPT Custom Instructions |
|---|---|---|---|
| Emplacement | Repo + user + managed (org) | .cursor/rules/*.md |
Compte OpenAI (cloud) |
| Hiérarchie | 4 scopes + imbriqués + auto memory | Projet seulement | Utilisateur seulement |
| Format | Markdown + YAML frontmatter (rules) | Markdown + YAML frontmatter | Texte brut (2 champs) |
| Imports | @path récursifs 5 sauts |
Limités | Aucun |
| Path-scoped rules | ✅ .claude/rules/ + glob paths |
Partiel | ❌ |
| Auto memory | ✅ v2.1.59+ | ❌ | ❌ |
| Interop AGENTS.md | ✅ Import @AGENTS.md |
❌ | ❌ |
| Versioning | Oui (dans Git) | Oui (dans Git) | Non (cloud-only) |
| Partage équipe | Oui | Oui | Non |
Recommandation pratique : si vous utilisez tous les outils sur le même projet, écrivez CLAUDE.md comme source maître, importez AGENTS.md depuis lui, copiez à l’identique dans .cursor/rules/ pour Cursor. Mettez seulement vos préférences personnelles dans ChatGPT Custom Instructions (par ex. « Réponds en français, commentaires de code en anglais ») — les détails de projet n’y vont pas car ils s’appliquent à tous vos projets.
Conseils pratiques pour les développeurs francophones
L’adoption de CLAUDE.md s’est rapidement répandue dans la communauté développeur francophone à partir de fin 2025. On la croise dans des side projects ouverts sur GitHub depuis Paris, Lyon, Montréal, Bruxelles. La règle commune est la cohérence linguistique : commentaires de code, messages d’erreur, docstrings en anglais ; documentation utilisateur en français ; descriptions de PR bilingues. Une seule ligne dans CLAUDE.md suffit : « Code comments, docstrings, error messages: English. Documentation in docs/: French. PR descriptions: bilingual. »
Deuxième sujet récurrent dans les projets francophones : encoding et locale. UTF-8 (sans BOM), collation utf8mb4_unicode_ci, et fr_FR.UTF-8 explicite dans les tests sensibles au tri sont la pratique standard. Sans cela, les accents et caractères spéciaux produisent des résultats incohérents. Troisième bloc critique : réglementation et règles métier locales : conformité RGPD (pas de données personnelles dans les logs), facture électronique au format Factur-X, formatage des prix en EUR selon f"{amount:,.2f} €" — règles que l’IA ne connaît pas seule.
Dernier conseil : versionnez CLAUDE.md avec l’équipe. Fichier sur main et review dans chaque PR. Une règle ajoutée par un développeur devient instantanément le standard de l’équipe car l’IA lit toujours la version la plus récente. C’est le socle du mouvement par lequel les équipes francophones codifient leurs standards techniques avec l’IA.
Foire aux questions sur CLAUDE.md
CLAUDE.md et auto memory sont-ils la même chose ?
Non. CLAUDE.md est le fichier que vous écrivez avec règles et architecture. L’auto memory est ce que Claude garde tout seul sous ~/.claude/projects/<project>/memory/MEMORY.md — préférences déduites des corrections passées. Les deux chargent ensemble ; aucun ne remplace l’autre. Auto memory disponible à partir de Claude Code v2.1.59.
Que se passe-t-il si ~/.claude/CLAUDE.md et ./CLAUDE.md entrent en conflit ?
Les deux chargent, le contenu est fusionné. En cas de conflit direct, le niveau projet (./CLAUDE.md) l’emporte car plus spécifique. Mettez au niveau utilisateur ce que vous voulez dans tous vos projets, au niveau projet ce qui est propre au projet.
Comment fonctionnent les imports @path ?
@README.md ou @~/.claude/preferences.md font intégrer le fichier dans le contexte. Chemins relatifs et absolus supportés. Récursion maximale de 5 sauts — un fichier importé peut en importer un autre qui en importe un autre, mais le 6e niveau est rejeté. Au premier import externe une boîte de dialogue de validation apparaît ; refuser ferme le dialogue durablement.
Quelle différence entre .claude/rules/ et CLAUDE.md ?
CLAUDE.md charge toujours ; les fichiers de .claude/rules/ avec frontmatter paths ne chargent que lorsque Claude traite un fichier correspondant. Dans de gros projets, le dossier rules découpe les instructions par sujet/chemin et réduit la consommation de contexte. Les rules sans frontmatter paths ont la même priorité que CLAUDE.md.
Comment les skills, plugins et subagents se relient-ils à CLAUDE.md ?
Les skills sont des modules plus lourds invoqués à la demande, non chargés à chaque session. Les plugins empaquetent serveurs MCP, commandes slash et bundles de skills pour distribution. Les subagents peuvent garder leur propre auto memory (enable-persistent-memory). CLAUDE.md sert de couche contextuelle de base sous tout cela ; les flux spécifiques migrent dans les skills.
Le concept d’« idea file » de Karpathy a-t-il redéfini CLAUDE.md ?
Pas directement, mais il a élargi son périmètre. Le CLAUDE.md classique contient règles et commandes. Dans la proposition d’avril 2026 de Karpathy, CLAUDE.md joue en plus le rôle du fichier schéma qui gère raw/ (sources) et wiki/ (savoir compilé par le LLM). Ça fait passer CLAUDE.md d’une liste de commandes au centre d’un système de gestion de connaissances.
Où suivre Karpathy ?
Quatre canaux principaux : YouTube (@AndrejKarpathy) pour les conférences marathon, X / Twitter (@karpathy) pour les observations quotidiennes, GitHub (github.com/karpathy) pour les projets open source comme nanogpt, nanochat, makemore, micrograd, llm.c, et Eureka Labs (eurekalabs.ai) pour les annonces de la plateforme éducative IA. Le gist idea file est directement à gist.github.com/karpathy/442a6bf555914893e9891c11519de94f.
Conclusion : CLAUDE.md, la nouvelle mémoire du logiciel à l’ère de l’IA
CLAUDE.md est une convention d’apparence simple qui refaçonne la nature du développement logiciel. En 2026 elle n’est plus un fichier unique mais un système englobant quatre scopes, imports, path-scoped rules, auto memory et architecture idea file. Comme le souligne Karpathy : la nouvelle monnaie du logiciel n’est pas que du code, c’est le contexte que vous donnez à l’IA. Garder ce contexte persistant, continuellement mis à jour et partagé en équipe est devenu la nouvelle configuration de base des équipes logicielles modernes.
Le plan pratique est simple. Jour un : lancez Claude Code dans n’importe quel projet ouvert et exécutez /init (idéalement avec CLAUDE_CODE_NEW_INIT=1). Jour deux : éditez le brouillon généré selon le modèle de ce guide. Première semaine : à chaque erreur de l’IA, ajoutez une ligne à CLAUDE.md avant de la corriger. Deuxième semaine : partagez avec l’équipe et intégrez dans le processus de review PR. Au bout d’un mois : si le fichier approche 200 lignes, scindez via .claude/rules/ et utilisez les imports @path. Trois mois plus tard : envisagez l’architecture idea file de Karpathy avec les couches raw/ et wiki/.
Recommandation claire : prenez CLAUDE.md au même sérieux que README.md. Chaque ligne ajoutée en un mois est une erreur que l’IA n’a pas faite ce mois-là. Cet investissement compose — le rendement croît semaine après semaine.
Sources
- Anthropic. Claude Code Documentation — How Claude remembers your project. code.claude.com/docs/en/memory (consulté : 2026-05-01)
- Anthropic. Claude Code: Skills, Plugins, Hooks, Subagents documentation. code.claude.com/docs/en
- Karpathy, Andrej. Idea file — gist GitHub, avril 2026. gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- Karpathy, Andrej. Publications X (Twitter), @karpathy — tweet idea file du 3 avril 2026 et discussions de suivi.
- Karpathy, Andrej. Software Is Changing (Again) — keynote, Y Combinator AI Startup School, 2024. YouTube : youtube.com/watch?v=LCEmiRjPEtQ
- Karpathy, Andrej. Software 2.0. Medium, novembre 2017. karpathy.medium.com/software-2-0-a64152b37c35
- Karpathy, Andrej. github.com/karpathy — exemples CLAUDE.md et AGENTS.md dans
nanogpt,nanochat,makemore,micrograd,llm.c. - Antigravity Codes. Karpathy’s LLM Wiki: The Complete Guide to His Idea File. antigravity.codes/blog/karpathy-llm-wiki-idea-file
- MCP Directory. Claude Code Best Practices: A Developer’s Guide (2026). mcp.directory/blog/claude-code-best-practices
