Contexte projet et CLAUDE.md

Comment Claude Code assemble son contexte au démarrage

Un agentagentIASystème qui enchaîne des appels d'outils de façon autonome pour atteindre un objectif : il planifie, agit, observe, recommence. Sa fiabilité décroît exponentiellement avec le nombre d'étapes.Voir dans le glossaire conversationnel classique — un chat web — reçoit un historique de messages et rien d'autre. Il ne sait rien de votre disque, de votre dépôt Git ou de la structure de vos dossiers, sauf ce que vous lui collez manuellement dans la fenêtre de saisie. Claude CodeClaude CodeIAInterface en ligne de commande agentique qui lit, édite et exécute des actions dans un dépôt de code sous contrôle de permissions, par opposition à un simple chat web.Voir dans le glossaire fonctionne différemment : c'est un agent en ligne de commandeAgent CLIIAProgramme en terminal qui enchaîne raisonnement et outils (lecture, édition, commandes) pour accomplir une tâche dans un environnement local.Voir dans le glossaire, lancé depuis un dossier de projet réel, qui peut lire des fichiers, explorer une arborescence et exécuter des commandes. Cette différence structurelle change tout dans la manière de préparer le contextefenêtre de contexteIAQuantité de texte qu'un modèle peut prendre en compte simultanément : question, documents fournis et historique. Au-delà, les éléments les plus anciens sortent du champ.Voir dans le glossaire.

Au lancement, Claude Code n'a pas accès d'emblée au contenu de tous vos fichiers — ce serait ni possible ni souhaitable sur un dépôt de plusieurs milliers de fichiers. Il dispose plutôt de deux choses : une vue de l'arborescence (les noms de fichiers et de dossiers, pas leur contenu) et le contenu des fichiers CLAUDE.md trouvés sur son chemin. Le reste du code n'est lu qu'à la demande, quand une tâche le justifie, via les outilstool callingIACapacité d'un agent ou d'un LLM à invoquer des outils externes (API, calcul, recherche) pendant le raisonnement.Voir dans le glossaire de lecture et de recherche de l'agent. C'est un point souvent mal compris : donner une instruction dans un promptpromptIAConsigne ou contexte fourni à un modèle de langage pour orienter sa réponse. La qualité du prompt conditionne souvent la qualité du résultat.Voir dans le glossaire ne garantit pas que l'agent a « vu » un fichier particulier, sauf s'il l'a explicitement ouvert.

Contrairement à un chat web où vous copiez-collez du code pour donner du contexte, Claude Code lit les fichiers lui-même via ses outils. Votre rôle n'est pas de tout lui fournir, mais de baliser où chercher et quelles règles respecter.

CLAUDE.md : la mémoire stable du projet

CLAUDE.md est un fichier Markdown ordinaire, versionné comme n'importe quel autre fichier du dépôt. Son seul statut particulier est que Claude Code le charge automatiquement en début de session, sans que vous ayez à le demander. Il joue le rôle d'une mémoire stable : des informations qui ne changent pas d'une tâche à l'autre et qu'il serait absurde de retaper à chaque prompt — les commandes de build, les conventions de nommage, les pièges connus du projet, les zones du code à ne jamais toucher sans revue.

Ce fichier n'est ni un prompt système caché, ni une configuration propriétaire illisible. C'est un document que n'importe quel membre de l'équipe peut ouvrir, modifier et relire dans une pull request, exactement comme un README.md. Cette visibilité a une conséquence directe : ce que vous y écrivez engage toute l'équipe, pas seulement vos sessions personnelles.

CLAUDE.mdCLAUDE.mdIAFichier Markdown de consignes stables placé dans un projet pour orienter Claude Code (stack, conventions, périmètre, interdits) sans les répéter à chaque prompt.Voir dans le glossaire est un fichier versionné et lu automatiquement à chaque session. Tout ce qu'il contient est potentiellement vu par n'importe quel collaborateur utilisant Claude Code sur ce dépôt — traitez-le avec la même rigueur qu'un fichier de configuration partagé.

La hiérarchie des fichiers CLAUDE.md

Claude Code ne se limite pas à un seul fichier. Il peut charger plusieurs CLAUDE.md selon trois niveaux de portée :

Ces fichiers ne s'excluent pas mutuellement : ils se cumulent. Si vous travaillez dans api/ et que ce dossier contient son propre CLAUDE.md, l'agent dispose à la fois du contexte utilisateur, du contexte projet et du contexte spécifique au module. En cas de tension entre deux niveaux — par exemple une convention générale au niveau projet et une exception locale au niveau module — c'est en principe le contexte le plus spécifique et le plus proche du travail en cours qui doit primer, exactement comme une configuration locale l'emporte sur une configuration globale dans la plupart des outils de développement.

Cette hiérarchie permet d'éviter un piège classique : un unique CLAUDE.md à la racine qui tente de tout couvrir, y compris des détails qui ne concernent qu'un sous-système. Mieux vaut garder le fichier racine généraliste et déléguer les spécificités à des fichiers de sous-dossier, à condition que le projet soit assez gros pour le justifier — sur un petit dépôt, un fichier unique reste largement suffisant.

<rect x="40" y="140" width="260" height="60" rx="8" fill="none" stroke="currentColor" stroke-width="2"/>
<text x="170" y="175" text-anchor="middle" font-size="15">CLAUDE.md racine (projet)</text>
<path d="M170,200 L170,250" stroke="currentColor" stroke-width="2" marker-end="url(#arr)"/>

<rect x="40" y="250" width="260" height="60" rx="8" fill="none" stroke="currentColor" stroke-width="2"/>
<text x="170" y="285" text-anchor="middle" font-size="15">api/CLAUDE.md (sous-dossier)</text>

<path d="M300,280 L520,200" stroke="currentColor" stroke-width="2" fill="none" marker-end="url(#arr)"/>
<rect x="530" y="150" width="320" height="100" rx="10" fill="none" stroke="currentColor" stroke-width="3"/>
<text x="690" y="195" text-anchor="middle" font-size="16" font-weight="bold">Session sur api/</text>
<text x="690" y="220" text-anchor="middle" font-size="13">contexte cumulé des trois niveaux</text>

Contexte stable versus prompt one-shot

Une confusion fréquente chez les nouveaux utilisateurs consiste à vouloir tout mettre dans CLAUDE.md, y compris des instructions qui ne concernent qu'une tâche du jour. Il faut distinguer deux registres :

• Contexte stable (CLAUDE.md) — vrai indépendamment de la tâche en cours. Exemple : « les tests s'exécutent avec la commande npm run test:unit », « ne jamais modifier directement le dossier generated/ », « le style de commit suit la convention Conventional Commits ».
• Prompt one-shot (le message que vous tapez) — vrai seulement pour cette session ou cette demande précise. Exemple : « corrige le bug d'affichage sur la page de paiement », « refactorise cette fonction pour supprimer la duplication ».

Mélanger les deux registres a un coût réel. Un CLAUDE.md qui accumule des consignes ponctuelles périmées (« pour l'instant, ignore le module de facturation, on le refait la semaine prochaine ») finit par contenir des instructions obsolètes que l'agent continue d'appliquer des mois plus tard, sans que personne ne s'en rende compte. À l'inverse, répéter à chaque prompt des règles qui ne changent jamais (« utilise toujours des fonctions async, pas de callbacks ») est une perte de temps et une source d'incohérence si un collaborateur oublie de le repréciser.

Posez-vous la question : « cette information sera-t-elle encore vraie dans un mois, pour n'importe quelle tâche sur ce dépôt ? » Si oui, elle va dans CLAUDE.md. Si non, elle va dans le prompt de la session en cours.

Ce qu'il faut écrire dans CLAUDE.md — et ce qu'il faut éviter

Un bon CLAUDE.md ressemble davantage à une fiche de poste qu'à une documentation exhaustive. Les catégories qui apportent le plus de valeur :

• Commandes de référence — build, tests, lint, démarrage local. L'agent les utilisera sans avoir à les redécouvrir en explorant package.json ou un Makefile à chaque fois.
• Conventions de code — style privilégié, structure de dossiers, patterns à suivre ou à proscrire.
• Zones sensibles — code généré automatiquement, migrations de base de donnéesdonnéesIAEnsemble d'informations structurées ou non utilisées pour entraîner, évaluer ou alimenter un modèle. La qualité, la quantité et la représentativité des données sont les facteurs décisifs pour les performances en apprentissage automatique.Voir dans le glossaire, fichiers de configuration de production qui ne doivent jamais être modifiés sans validation humaine explicite.
• Contexte d'architecture minimal — comment les grands morceaux du système s'articulent, si ce n'est pas déductible en quelques lectures de fichiers.
• Pièges connus — comportements contre-intuitifs, dépendances fragiles, tests flaky identifiés.

Ce qu'il vaut mieux ne pas y mettre : la documentation fonctionnelle complète du produit (elle a sa place ailleurs et vieillit vite), la liste exhaustive des fichiers du projet (l'agent peut l'obtenir lui-même en explorant l'arborescence), ou des explications que le code rend déjà évidentes. Un CLAUDE.md de plusieurs milliers de lignes n'est pas plus utile qu'un fichier vide : au-delà d'une certaine taille, l'information pertinente se noie et le fichier devient lui-même un poids à maintenir.

Un CLAUDE.md de projet raisonnable ressemble à ceci :

# Conventions du projet
- Tests : `npm run test`, couverture minimale 80 %
- Lint : `npm run lint` avant tout commit
- Ne jamais modifier `src/generated/` (régénéré par `npm run codegen`)
- Les migrations de base vivent dans `db/migrations/`, une par PR, jamais de squash
- Le module `legacy-billing/` est en cours de dépréciation : ne pas y ajouter de fonctionnalité

Chaque ligne est vérifiable, stable et directement actionnable — pas de prose générale.

Ignorer les fichiers sensibles et le bruit

L'exploration automatique de l'arborescence par l'agent pose une question de périmètre : que doit-il voir, et que doit-il ignorer ? Comme pour Git, un mécanisme d'exclusion permet de tenir à l'écart les fichiers volumineux, générés ou sensibles — dépendances installées, artefacts de build, fichiers d'environnement contenant des identifiants. L'objectif est double : réduire le bruit pour que l'agent explore efficacement, et éviter qu'un secret ne se retrouve chargé dans le contexte d'une session, où il pourrait être reproduit dans une réponse, un commit ou un log.

Un fichier .env non exclu peut être lu par l'agent comme n'importe quel autre fichier texte s'il ouvre le dossier concerné. La bonne pratique n'est pas de compter sur la prudence de l'agent, mais de retirer les secrets du chemin de lecture : variables d'environnement injectées au runtime, gestionnaire de secrets externe, fichiers d'exemple (*.env.example) versionnés à la place des vrais fichiers.

Cette logique d'exclusion s'articule avec un second mécanisme : les permissions. Claude Code demande une confirmation avant d'exécuter certaines actions — modifier un fichier, lancer une commande shell, accéder à des ressources externes via un connecteur MCPMCPIAModel Context Protocol : protocole permettant de brancher des outils et sources externes (docs, tickets, bases) à un agent LLM via des serveurs dédiés.Voir dans le glossaire. Cette confirmation n'est pas une formalité : c'est le point où une revue humaine s'interpose avant qu'une action ait un effet réel sur le système de fichiers ou l'environnement d'exécution. Combiner de bonnes exclusions (l'agent ne voit pas ce qui est sensible) et des permissions actives (vous validez ce qui a un impact) constitue la base d'un usage sûr, plutôt que de compter sur l'une des deux couches seule.

Faire vivre CLAUDE.md sans qu'il devienne un roman

Un CLAUDE.md se dégrade de deux façons opposées : par abandon (il n'est plus mis à jour et devient trompeur) ou par accumulation (chaque contributeur y ajoute une ligne sans jamais rien retirer, jusqu'à ce que plus personne ne le lise en entier). Quelques pratiques limitent ces deux dérives :

1. Traiter les mises à jour comme du code. Une modification de CLAUDE.md passe par une pull request, avec relecture, exactement comme un changement de configuration.
2. Revoir le fichier périodiquement. À l'occasion d'un changement d'architecture ou d'un nettoyage de dépendances, vérifier que les instructions décrivent toujours l'état réel du projet.
3. Supprimer plutôt qu'accumuler. Une règle devenue obsolète doit être retirée, pas laissée « au cas où ». Une instruction périmée activement suivie par l'agent est pire qu'une absence d'instruction.
4. Préférer la concision à l'exhaustivité. Une liste à puces courte et précise est plus efficace qu'un paragraphe explicatif ; l'agent n'a pas besoin d'être convaincu, seulement informé.
5. Séparer projet et sous-dossiers quand la taille le justifie. Un monorepo avec des stacks technologiques différentes gagne à avoir un CLAUDE.md par module plutôt qu'un fichier racine qui tente de tout couvrir.

Checklist avant de committer un CLAUDE.md

• Chaque ligne est-elle encore vraie aujourd'hui, indépendamment de la tâche en cours ?
• Le fichier contient-il un secret, une clé, un identifiant, même à titre d'exemple ?
• Une information présente ici est-elle déjà déductible du code lui-même en une lecture ?
• Le fichier reste-t-il lisible en moins de deux minutes par un nouveau contributeur ?
• Les zones sensibles (migrations, code généré, configuration de production) sont-elles explicitement signalées ?

Pièges fréquents

Le piège le plus courant consiste à traiter CLAUDE.md comme une documentation produit à destination des humains, en y recopiant le contenu d'un wiki interne. Le fichier perd alors sa fonction : il devient trop long pour être utile comme instruction opérationnelle et redondant avec une documentation qui existe déjà ailleurs.

Le second piège est de croire que remplir CLAUDE.md dispense de donner un contexte de tâche clair dans le prompt. Le fichier fournit un cadre stable, pas une description du travail à faire aujourd'hui — les deux registres restent complémentaires, jamais interchangeables.

Le troisième piège touche à la confiance : parce que CLAUDE.md est chargé automatiquement, certains y placent des règles de sécurité en espérant qu'elles suffisent à encadrer l'agent (« ne jamais exécuter de commande destructive »). Une instruction textuelle reste une instruction, pas une garantie technique. Les permissions et les exclusions de fichiers sensibles restent le mécanisme de contrôle réel ; CLAUDE.md complète ce dispositif, il ne le remplace pas.