CLAUDE.md et sous-agents : ce qui se propage et ce qui ne se propage pas

En bref

Quand Claude Code lance un sous-agent, il ne repart pas de zéro. Les fichiers d’instructions du projet (les CLAUDE.md) lui sont transmis intégralement, tout comme les serveurs MCP configurés. En revanche, les skills — les comportements spécialisés définis dans .claude/agents/ — ne se propagent pas. Comprendre ce mécanisme d’héritage évite des comportements inattendus dans les workflows multi-agents.

Ce que reçoit un sous-agent au démarrage

Le CLAUDE.md est transmis intégralement

Quand une session Claude Code est ouverte, le programme charge les fichiers d’instructions présents dans la hiérarchie du projet. Cet ensemble de fichiers est ensuite transmis tel quel aux sous-agents lancés pendant la session.

Nos tests montrent que les sous-agents voient exactement les mêmes fichiers d’instructions que leur parent — ni plus, ni moins. Un sous-agent interrogé sur son contexte liste les mêmes fichiers, dans le même ordre, que la session parente.

La transmission est intégrale, sans troncature. Nous avons testé un fichier d’instructions de 1 000 lignes (environ 5 800 tokens) avec trois modèles différents (Haiku, Sonnet, Opus). Les trois ont trouvé les marqueurs placés en début et en milieu de fichier. Le fichier n’est pas compressé ni résumé lors du transfert.

Le contenu est figé au moment du chargement. Les sous-agents héritent du contenu tel qu’il existait quand la session parente a démarré. Si vous modifiez un fichier d’instructions en cours de session, les sous-agents lancés après la modification voient l’ancienne version. Pour propager un changement, il faut relancer une nouvelle session.

La hiérarchie de fichiers chargée

Claude Code charge les fichiers d’instructions depuis plusieurs emplacements, dans cet ordre :

1. Le fichier global (~/.claude/CLAUDE.md)
2. Le fichier de la racine du projet (.../CLAUDE.md)
3. Les fichiers des sous-dossiers si le répertoire de travail est un sous-dossier

Les sous-agents reçoivent ces fichiers dans le même ordre. Un fichier placé hors de la hiérarchie git du projet — dans /tmp/ par exemple — n’est pas chargé, ni par la session parente, ni par les sous-agents.

Les serveurs MCP suivent la même logique

Les serveurs MCP configurés dans settings.json sont disponibles pour les sous-agents. Comme les fichiers d’instructions, leur configuration est héritée de la session parente.

Ce qui ne se propage pas : les skills

Les skills sont des agents spécialisés définis dans .claude/agents/. Ils permettent d’associer un nom, un modèle, un jeu d’outils limité et un comportement précis à un agent nommé.

Un sous-agent lancé via l’outil Agent Tool ne reçoit pas les skills du projet. Il reçoit les fichiers d’instructions, mais il n’est pas lui-même un skill — il démarre en mode généraliste. Si vous voulez qu’un sous-agent utilise un skill, il faut l’invoquer explicitement par son nom.

Exclure des fichiers d’instructions avec claudeMdExcludes

Il est possible de dire à Claude Code de ne pas charger certains fichiers d’instructions. La configuration se fait dans settings.json :

{
  "claudeMdExcludes": ["**/rules/exclue.md"]
}

La valeur est un tableau de patterns glob. Chaque pattern est comparé au chemin absolu du fichier. Si le chemin correspond, le fichier n’est pas chargé.

Important : claudeMdExcludes doit être configuré avant le démarrage de la session. Si vous l’ajoutez en cours de session, il est ignoré — les fichiers d’instructions sont déjà chargés dans le contexte.

L’exclusion se propage aux sous-agents. Nos tests montrent que si un fichier est exclu au démarrage de la session parente, il est absent du contexte des sous-agents également. Le mécanisme est simple : le parent filtre au chargement, puis transmet le résultat filtré. Les sous-agents ne rechargent pas les fichiers depuis le disque — ils reçoivent ce que le parent leur passe. Un fichier exclu au niveau parent est donc exclu pour toute la chaîne.

Résumé du mécanisme :

Le cas du conflit : instructions contradictoires

Que se passe-t-il quand un fichier d’instructions dit une chose, et qu’un agent nommé (skill) dit le contraire ?

Nous avons testé ce scénario : les fichiers d’instructions globaux et projet indiquaient de répondre en français, le système d’un agent nommé indiquait de répondre en anglais.

Le résultat est non déterministe. Sur trois runs :

• 1 run : l’agent a suivi l’instruction de son propre système (anglais)
• 2 runs : l’agent a suivi les fichiers d’instructions du projet (français)

Lors du troisième run, l’agent a raisonné explicitement sur le conflit avant de choisir. Il a identifié les deux sources contradictoires et a tranché en faveur des fichiers d’instructions du projet.

Ce comportement illustre un point important : il n’y a pas de hiérarchie stricte et automatique entre ces deux sources. L’issue dépend de si le modèle raisonne ou non sur le conflit, ce qui est stochastique.

La recommandation pratique qui en découle : ne pas mettre les fichiers d’instructions du projet et le système d’un agent nommé en contradiction. Les utiliser de façon complémentaire — le projet définit le contexte global, l’agent nommé définit ses spécificités, sans se contredire.

Ce qu’il faut retenir

• Les fichiers d’instructions du projet sont transmis intégralement aux sous-agents, sans troncature, même pour des fichiers de 1 000 lignes.
• Le contenu transmis est celui qui existait au démarrage de la session — les modifications faites ensuite ne sont pas propagées.
• Les serveurs MCP sont disponibles pour les sous-agents selon la même logique d’héritage.
• Les skills ne se propagent pas automatiquement aux sous-agents génériques.
• claudeMdExcludes filtre au chargement et l’exclusion s’hérite par les sous-agents — mais il doit être configuré avant le démarrage de la session.
• En cas de conflit entre fichiers d’instructions et système d’un agent nommé, le comportement est non déterministe. Ne pas créer de contradiction.

Sources

• Nos observations — tests de propagation CLAUDE.md sur sous-agents Haiku, Sonnet, Opus — 2026-03-19 / 2026-03-20
• Nos observations — tests claudeMdExcludes parent et sous-agent Sonnet — 2026-03-20
• Nos observations — tests conflit instructions projet vs système agent nommé, 3 runs — 2026-03-20
• Documentation Claude Code — claudeMdExcludes — code.claude.com/docs