Accueil / Une installation structurée

AGENTS.md : quand Claude Code le lit, et comment le constater

Au réglage par défaut, Claude Code lit AGENTS.md seulement quand aucun CLAUDE.md ne le précède dans le dossier de travail ou au-dessus, et ce qui a réellement été chargé se constate au démarrage de la session, pas dans le panneau /config.

Un dépôt préparé pour d'autres agents de code porte souvent à sa racine un fichier AGENTS.md : conventions du projet, commande de test exacte, fichiers à ne pas toucher. Depuis la version 2.1.277 de Claude Code, publiée le 18 septembre 2026, Claude Code lit ce fichier comme instructions de projet, sans import ni réglage, à une condition : aucun fichier CLAUDE.md ne doit prendre sa place.

La condition exacte

Au réglage par défaut, trois fichiers comptent pour cette vérification : CLAUDE.md, .claude/CLAUDE.md et CLAUDE.local.md, dans le dossier de travail ou dans l'un des dossiers au-dessus. Si l'un d'eux existe, Claude lit les fichiers CLAUDE.md et laisse AGENTS.md de côté. Le fichier personnel ~/.claude/CLAUDE.md, le CLAUDE.md géré par l'organisation et les règles de .claude/rules/ ne comptent pas : ils se chargent à côté d'AGENTS.md. La documentation signale un piège : créer un CLAUDE.local.md pour y noter ses préférences personnelles suffit à retirer AGENTS.md de la session.

Quand la condition est remplie, Claude lit au démarrage chaque AGENTS.md et .claude/AGENTS.md du dossier de travail et des dossiers au-dessus. Il lit ensuite l'AGENTS.md d'un sous-dossier quand il y ouvre un fichier et que ce sous-dossier ne porte aucun des trois fichiers CLAUDE.md. Les imports @chemin écrits dans un AGENTS.md sont développés comme dans un CLAUDE.md.

Un réglage n'est pas un témoin

L'entrée Project instructions du panneau /config choisit ce qui se charge. La valeur par défaut, claude-md-or-agents-md, applique la condition ci-dessus ; claude-md-and-agents-md lit les deux familles de fichiers, les CLAUDE.md de chaque dossier d'abord ; claude-md ignore AGENTS.md ; managed-only charge au démarrage le CLAUDE.md géré par votre organisation et la mémoire automatique, en écartant vos CLAUDE.md de projet, local et personnel, vos règles de .claude/rules/ et tout AGENTS.md, mais le CLAUDE.md et les règles d'un sous-dossier se chargent encore quand Claude y lit un fichier. Ce panneau dit ce qui est demandé, pas ce qui a été lu. La preuve se lit ailleurs : en session interactive, la documentation donne l'exemple d'une ligne comme no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md affichée dans la conversation, et depuis la version 2.1.280, la commande /memory liste aussi le chemin du fichier lu.

Deux cas particuliers restent à connaître. Avant la version 2.1.281 du 23 septembre 2026, les sessions sur Amazon Bedrock, Google Vertex AI ou Microsoft Foundry, derrière une passerelle ou avec la télémétrie désactivée, ne lisaient que les fichiers CLAUDE.md ; cette version les a alignées sur les autres. Et dans certains cas, la première session qui suit une mise à jour depuis la version 2.1.276 ou antérieure ne lit pas encore AGENTS.md : la lecture commence à la session suivante.

La démonstration

Créez le dossier hors de tout projet, pour qu'aucun CLAUDE.md d'un dossier parent ne compte dans la vérification.

mkdir test-agents-md && cd test-agents-md
printf "# Règles du projet\nRéponds toujours en une seule phrase.\n" > AGENTS.md
cat AGENTS.md

# Règles du projet
Réponds toujours en une seule phrase.

Lancez ensuite claude dans ce dossier, lisez la ligne affichée au démarrage, puis tapez /memory. Le fichier se charge comme le CLAUDE.md décrit dans la leçon sur la mémoire du projet, et ses consignes vieillissent de la même façon, comme le montre la leçon suivante.