CLAUDE.md : le contexte client pour Claude Code

Chaque session de Claude Code repart d'une fenêtre de contexte neuve. Pour un travail d'agence, cela veut dire redonner à chaque fois les mêmes informations : quels comptes, quels objectifs, quelles définitions, quel format de rapport. La documentation de Claude Code propose deux mécanismes pour que ce savoir traverse les sessions : les fichiers CLAUDE.md, que vous écrivez, et la mémoire automatique, que Claude écrit lui-même. Ce guide montre comment organiser le premier pour un client e-commerce, et ce qu'il faut savoir de la seconde avant de travailler pour plusieurs clients sur la même machine.

Les faits viennent de la page mémoire de la documentation de Claude Code et de celle des sous-agents, consultées le 14 octobre 2026. L'arborescence et le fichier d'exemple sont notre assemblage : aucune de ces pages n'en publie de semblables.

Ce qu'un CLAUDE.md fait, et ce qu'il ne fait pas

Un CLAUDE.md est un fichier Markdown que Claude lit au début de chaque session. La documentation précise qu'il est transmis comme un message d'utilisateur placé après le prompt système, et ne fait pas partie de ce prompt. La documentation range ce fichier dans le contexte : le respect strict n'est pas assuré, surtout pour des consignes vagues ou contradictoires. Pour bloquer une action quelle que soit la décision de Claude, la page renvoie vers un hook ; nous en avons détaillé le montage dans notre guide des hooks pour comptes publicitaires.

La même page range ce qu'il faut y écrire : les faits que Claude doit connaître à chaque session, comme les commandes, les conventions et l'organisation du projet. Une procédure en plusieurs étapes, ou une consigne qui ne vaut que pour une partie du projet, va ailleurs : dans un skill, comme celui de notre guide du reporting hebdomadaire, ou dans une règle limitée à des chemins.

Où ranger le fichier

Quatre emplacements existent, listés dans l'ordre de chargement, du plus large au plus précis :

Les règles de chargement comptent plus que le tableau. Claude Code charge au lancement les fichiers CLAUDE.md et CLAUDE.local.md du dossier courant et de chaque dossier parent. Ils s'ajoutent les uns aux autres sans se remplacer, de la racine du système de fichiers vers le dossier de lancement : les consignes les plus proches de l'endroit où vous lancez Claude sont lues en dernier. Ceux des sous-dossiers ne se chargent pas au lancement : Claude Code charge chacun une fois que Claude lit, écrit ou modifie un autre fichier de ce sous-dossier.

Un dossier par client

Ces règles suggèrent l'organisation suivante. Elle est notre lecture, la documentation ne la recommande pas :

~/clients/
  CLAUDE.md                     règles communes de l'agence (hors dépôts clients)
  client-a/                     un dépôt Git par client
    CLAUDE.md                   contexte du client
    CLAUDE.local.md             préférences personnelles (dans .gitignore)
    .claude/rules/
      exports-ads.md            règle limitée aux exports Google Ads
    data/ads/
  client-b/
    ...

On lance Claude Code depuis ~/clients/client-a. Le fichier du client et celui de ~/clients/ se chargent, puisque ce dernier est dans un dossier parent. Ceux du client B ne se chargent pas : ils ne sont ni dans un dossier parent, ni dans un sous-dossier. À notre avis, lancer la session depuis ~/clients/ mélangerait les contextes : les fichiers des sous-dossiers se chargent dès que Claude y touche un fichier.

Le fichier du client contient des faits vérifiables et des règles de travail :

# Client A : boutique en ligne

## Contexte
- Comptes : Google Ads <identifiant>, Meta Ads <identifiant>, GA4 <propriété>.
- Marge brute moyenne : <valeur> %. Objectif de ROAS : <valeur>, fixé par <nom> le <date>.
- Conversion principale : événement <nom de l'événement GA4>.

## Règles de travail
- Lecture seule sur les comptes. Aucune modification sans validation écrite de <nom>.
- Chaque constat cite le fichier et la colonne lus. Si l'information manque, écrire NA.
- Comparer deux périodes seulement si elles ont le même nombre de jours.

## Données
- Exports Google Ads : data/ads/, un fichier par semaine nommé AAAA-MM-JJ.csv.
- Flux produits : data/merchant/.

Les valeurs entre chevrons sont à remplir avec les chiffres du client : ne les inventez pas, et laissez la ligne vide plutôt que d'y mettre une estimation. Une règle limitée à des chemins s'écrit dans .claude/rules/ avec un en-tête paths :

---
paths:
  - "data/ads/**/*.csv"
---

# Lecture des exports Google Ads

- Ignorer les lignes de total.
- Citer le nom du fichier et de la colonne pour chaque chiffre repris.

Une règle sans champ paths se charge au lancement avec la même priorité que .claude/CLAUDE.md. Une règle à chemins se charge quand Claude lit, écrit ou modifie un fichier qui correspond. paths est le seul champ que Claude Code lit dans l'en-tête d'une règle : les autres sont ignorés sans erreur.

Écrire des consignes que Claude peut suivre

La documentation donne plusieurs conseils sur la rédaction ; trois valent pour les fichiers de contexte d'un client :

• Écrire des consignes assez concrètes pour être vérifiées : « Comparer deux périodes de même durée » plutôt que « Comparer correctement ».
• Viser moins de 200 lignes par fichier. Au-delà, le fichier consomme plus de contexte et l'adhérence baisse. Les imports avec la syntaxe @chemin aident à organiser, sans réduire le coût en contexte, car les fichiers importés se chargent aussi au lancement ; la profondeur d'import est limitée à quatre sauts.
• Éviter les contradictions : si deux consignes se contredisent, Claude peut en choisir une arbitrairement, et la documentation précise que si une règle utilisateur et une règle de projet se contredisent, il peut suivre l'une ou l'autre. La commande /doctor prompt-audit, disponible à partir de Claude Code v2.1.283, cherche les consignes écrites pour d'anciens modèles, les références à des fichiers ou des commandes inexistants et les fichiers qui se contredisent ; elle propose des corrections et ne modifie rien avant votre accord.

Deux détails pratiques. Les commentaires HTML de niveau bloc (<!-- note -->) sont retirés avant l'injection dans le contexte : ils servent de notes pour les humains sans coûter de jetons. Et la commande /init génère un premier fichier : d'après la documentation, elle analyse le code du dépôt pour y trouver commandes de build, instructions de test et conventions. Pour un dossier de client, nous partons plutôt du modèle ci-dessus.

À notre avis, ce fichier ne doit contenir ni identifiants de connexion ni mot de passe : le fichier de projet est partagé par le contrôle de version et son contenu est chargé dans le contexte de chaque session.

La mémoire automatique, côté confidentialité

La mémoire automatique est active par défaut dans les sessions locales. Claude y consigne quatre types de notes : votre rôle et vos préférences (user), les corrections que vous lui donnez (feedback), le travail en cours et les décisions qu'il ne peut pas déduire du code (project), et l'emplacement d'informations extérieures (reference). Les notes sont de simples fichiers Markdown, dans ~/.claude/projects/<projet>/memory/ ; l'index MEMORY.md est chargé à chaque session dans la limite de ses 200 premières lignes ou de 25 Ko, selon la limite atteinte en premier. Elle reste sur la machine et ne passe pas d'un ordinateur à l'autre.

Le point à retenir pour une agence : le dossier de mémoire est dérivé du dépôt Git, de sorte que tous les worktrees et sous-dossiers d'un même dépôt partagent un seul dossier de mémoire. Hors dépôt Git, c'est la racine du projet qui sert. À notre avis, c'est une raison de plus de garder un dépôt par client : avec un seul dépôt contenant tous les clients, leurs sessions partageraient le même dossier de mémoire.

La commande /memory liste les fichiers de mémoire, ouvre le dossier de la mémoire automatique et permet de l'activer ou de la couper. On peut la désactiver pour un projet avec "autoMemoryEnabled": false dans ses réglages, ou avec la variable d'environnement CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. La mémoire automatique de la conversation principale n'est pas chargée dans les sous-agents, sauf dans un fork, qui hérite de la conversation parente ; la mémoire propre à un sous-agent est un dossier à part.

Vérifier ce que Claude a chargé

• /context liste, sous « Memory files », les fichiers CLAUDE.md et CLAUDE.local.md chargés au lancement. Un fichier de sous-dossier n'y figure pas, puisqu'il se charge à la demande ; une ligne « Loaded » avec son chemin s'affiche alors dans le terminal.
• L'événement de hook InstructionsLoaded permet de journaliser quels fichiers sont chargés, quand et pourquoi, ce qui aide à déboguer une règle à chemins.
• Si l'en-tête YAML d'une règle ne s'analyse pas, Claude Code la charge comme une règle sans paths ; claude --debug affiche l'erreur d'analyse.
• Après un /compact, la documentation donne trois origines possibles à une consigne manquante : elle n'a été donnée que dans la conversation, elle vit dans un CLAUDE.md de sous-dossier pas encore rechargé, ou c'est une règle à chemins qui n'a pas encore rencontré de fichier correspondant.

Et les sous-agents ?

Les sous-agents personnalisés chargent les fichiers CLAUDE.md du projet, de l'utilisateur et en local, sauf s'ils déclarent omitClaudeMd: true (Claude Code v2.1.271 ou plus). Le contexte du client parvient donc aux auditeurs en lecture seule décrits dans notre guide des sous-agents pour auditer une boutique. Pour un sous-agent qui démarre sans ces fichiers (omitClaudeMd, Explore, Plan), la documentation conseille de répéter la règle nécessaire dans la consigne de délégation.

Par où commencer

1. Créer un dépôt par client et, au-dessus, un fichier ~/clients/CLAUDE.md court pour les règles de l'agence.
2. Écrire le CLAUDE.md du client avec le modèle ci-dessus, sans estimation à la place des chiffres manquants.
3. Lancer Claude Code depuis le dossier du client et vérifier avec /context que le fichier figure sous « Memory files ».
4. Passer /doctor prompt-audit après quelques semaines, et corriger les contradictions.
5. Ouvrir /memory avant de partager une machine, pour relire ce que Claude a noté.

Questions fréquentes sur CLAUDE.md

Sources consultées le 14 octobre 2026

• Anthropic : mémoire de Claude Code, sous-agents, référence des hooks