Claude Code lit désormais AGENTS.md : CLAUDE.md, AGENTS.md et le répertoire .claude

Qu’est-ce que claude.md et que devez-vous y mettre ?

CLAUDE.md est un fichier Markdown en texte brut contenant des instructions que Claude Code charge dans le contexte de sa session. Il vous permet de consigner des informations que vous devriez autrement répéter : commandes de compilation et de test, conventions de codage, architecture du projet et règles de travail.

Aucun format de document n’est imposé. Vous pouvez l’organiser avec des titres et des listes Markdown ordinaires, en choisissant la structure qui rend les instructions de votre projet faciles à comprendre. Les éléments de Claude Code /init La commande génère un fichier de base adapté au projet, comme l’explique la documentation officielle des bonnes pratiques.

Un bon point de départ consiste à couvrir quatre domaines :

• Commandes de compilation et de test : les commandes que les contributeurs doivent utiliser pour compiler le projet et vérifier les modifications.
• Conventions de code : les conventions de nommage, de mise en forme et les autres conventions propres au dépôt.
• Architecture du projet : les principaux composants et la façon dont ils s’articulent.
• Règles de travail : les étapes que vous souhaitez que Claude suive pour effectuer et vérifier les modifications.

Considérez ces éléments comme des consignes persistantes. Les instructions entrent dans le contexte de Claude ; elles ne constituent pas une configuration imposée. Si vous devez configurer Claude Code lui-même, utilisez le fichier de paramètres approprié plutôt que de vous attendre à ce que du texte dans CLAUDE.md fasse office de valeur de paramètre.

Cette distinction est importante pour organiser un dépôt : les connaissances sur le projet ont leur place dans les fichiers d’instructions, tandis que la configuration de l’application relève des paramètres. Le portail des guides Claude Code constitue un point de départ pour le processus de travail qui les entoure.

Où placer CLAUDE.md

Claude Code prend en charge les instructions de projet partagées et les instructions personnelles à plusieurs emplacements. La documentation des fichiers d’instructions décrit ces emplacements établis et le fonctionnement de la découverte des instructions.

Les fichiers d’instructions des répertoires parents sont chargés au lancement. Les fichiers des sous-répertoires sont chargés à la demande, ce qui permet aux instructions de devenir pertinentes lorsque Claude travaille dans ces parties du projet.

Pour les instructions partagées, choisissez un emplacement adapté à votre équipe. Un fichier CLAUDE.md à la racine place les consignes aux côtés des autres fichiers de premier niveau du dépôt. .claude/CLAUDE.md les place avec les fichiers du projet propres à Claude.

Les instructions personnelles influent sur bien plus que l’organisation des fichiers

CLAUDE.local.md remplit un rôle différent de celui du fichier de projet partagé : il contient vos instructions personnelles pour ce projet. Dans la version 2.1.277, sa présence détermine également si Claude Code utilise par défaut AGENTS.md.

Cela signifie que l’ajout d’un fichier d’instructions local peut modifier les instructions partagées qui entrent dans le contexte. Avant d’en créer un dans un dépôt qui repose sur AGENTS.md, vérifiez le paramètre Instructions du projet décrit ci-dessous.

Les emplacements ci-dessus proviennent d’une documentation évolutive dont la formulation exacte de septembre 19 n’a pas été vérifiée. Le comportement de repli présenté dans la section suivante est documenté spécifiquement pour la version étiquetée 2.1.277.

Claude Code lit-il automatiquement AGENTS.md ?

Oui, sous certaines conditions. Les notes de version de Claude Code 2.1.277 indiquent : « Ajout de la prise en charge de AGENTS.md : dans un projet sans CLAUDE.md, Claude Code lit AGENTS.md à la place ».

Le comportement par défaut est un mécanisme de repli ; la seule présence d’un fichier AGENTS.md ne signifie donc pas qu’il sera chargé. Dans cette version, la vérification ne se limite pas à un fichier à la racine CLAUDE.md.

Qu’est-ce qui désactive le repli par défaut ?

La présence de l’un de ces fichiers, à n’importe quel endroit du chemin allant de la racine du système de fichiers au répertoire de travail, désactive le repli par défaut vers AGENTS.md :

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

Les instructions gérées, les instructions personnelles dans ~/.claude/CLAUDE.md, ainsi que .claude/rules/ ne pas désactivent pas ce repli.

Prenons par exemple un dépôt contenant un fichier partagé AGENTS.md et aucun fichier d’instructions Claude répondant aux critères dans les répertoires parents. Le mode par défaut lit les instructions AGENTS. Si vous ajoutez ensuite CLAUDE.local.md, le repli par défaut est désactivé, même si le nouveau fichier contient des instructions personnelles plutôt que les consignes partagées de l’équipe.

Comment fonctionne la découverte de AGENTS.md

La prise en charge intégrée est assurée par le agents-md plugin, en version 0.1.0. Il découvre à la fois AGENTS.md et .claude/AGENTS.md dans les répertoires parents et joint les instructions imbriquées lorsque Claude lit des fichiers situés sous la racine du projet.

Le contenu déjà chargé par un import ou un lien est dédupliqué. Cela compte si un fichier d’instructions Claude inclut déjà le même contenu AGENTS.

À la date limite de publication de septembre 19, l’annonce de la version indique que cette prise en charge n’est pas encore disponible sur Bedrock, Vertex ou Foundry.

Configurer Claude Code pour lire un seul fichier ou les deux

Ouvrez /config et modifiez Instructions du projet pour choisir le comportement de chargement des instructions. Le README du plugin étiqueté v2.1.277 documente quatre valeurs exactes.

Le README apporte une précision importante concernant managed-only : les pièces jointes imbriquées CLAUDE.md peuvent toujours être ajoutées. N’interprétez pas cette valeur comme une garantie qu’aucun contenu d’instructions Claude imbriquées ne peut entrer dans la conversation.

Configuration exacte pour la version 2.1.277

Pour charger les deux familles d’instructions, utilisez cette configuration :

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

Pour cette version, placez-la dans les paramètres utilisateur à l’emplacement ~/.claude/settings.json, dans un fichier fourni via --settings, ou dans les paramètres gérés. Le fichier de projet .claude/settings.json ne pas fournit pas ces options de plugin.

Les modifications s’appliquent lors de la prochaine reconstruction du contexte, par exemple au tour suivant ou dans une nouvelle conversation. Gardez ce délai à l’esprit lorsque vous vérifiez si un paramètre a modifié les instructions chargées.

L’import des instructions partagées reste une option

Vous pouvez également placer @AGENTS.md dans un fichier voisin CLAUDE.md. Cela importe explicitement les instructions partagées par l’intermédiaire du fichier d’instructions Claude.

Les imports de fichiers d’instructions Claude utilisent @path/to/file.md et ont été introduits dans la version v0.2.107. La version 2.1.277 déduplique le contenu AGENTS déjà importé par CLAUDE.md.

Vous disposez ainsi de deux façons d’organiser les consignes partagées : configurer Claude Code pour charger les deux fichiers, ou utiliser un import pour inclure le contenu AGENTS dans un fichier d’instructions Claude. Choisissez l’organisation qui rend leur relation claire pour les contributeurs du dépôt.

Que placer dans le répertoire .claude ?

Le .claude répertoire contient plusieurs types de fichiers de projet. Ils remplissent des rôles différents ; choisissez donc l’emplacement selon que vous rédigez des consignes persistantes, une configuration, un prompt réutilisable, une définition de sous-agent ou une procédure.

Les paramètres personnels communs à tous les projets se trouvent dans ~/.claude/settings.json. Les définitions personnelles de sous-agents utilisent ~/.claude/agents/, et les compétences personnelles utilisent ~/.claude/skills/<name>/SKILL.md.

Commandes, sous-agents et compétences

Un fichier de commande tel que .claude/commands/deploy.md crée /deploy. La version 2.1.3 a fusionné les commandes slash et les compétences, et les fichiers de commande existants continuent de fonctionner aux côtés des compétences.

Les définitions des sous-agents utilisent Markdown avec des métadonnées YAML en en-tête. Les champs obligatoires sont name et description ; les champs facultatifs pertinents comprennent tools, model, ainsi que permissionMode. Gérez-les avec /agents, et utilisez le guide des sous-agents pour cette partie de la configuration de votre projet.

Les compétences regroupent des procédures réutilisables dans un dossier contenant SKILL.md, avec des scripts et des documents de référence facultatifs. Claude peut sélectionner les compétences pertinentes, ou vous pouvez en invoquer une avec /skill-name ; le contenu de la compétence est chargé lors de son utilisation. Le guide des compétences décrit ce processus.

Ces structures sont antérieures à la version introduisant le mécanisme de repli vers AGENTS. Le journal des modifications associé au tag confirme que les paramètres de projet, les commandes, les agents et les compétences existaient dès la version v2.1.277. Les descriptions détaillées des répertoires s'appuient sur une documentation évolutive dont la formulation exacte à la date limite n'a pas été vérifiée.

CLAUDE.md et mémoire automatique

CLAUDE.md et la mémoire automatique se distinguent par l'auteur du contenu. Vous rédigez les fichiers d'instructions pour définir les consignes du projet ; Claude enregistre le contexte utile dans la mémoire automatique.

Le journal des modifications associé au tag fait état de l'enregistrement automatique et de la gestion via /memory dans la version 2.1.59. La mémoire automatique joue donc un rôle distinct de celui des instructions que vous maintenez délibérément dans CLAUDE.md ou AGENTS.md.

Pour déterminer où placer une information, appuyez-vous sur cette distinction entre les auteurs. Placez les commandes de compilation explicites, les conventions, les notes d'architecture et les règles de travail dans vos fichiers d'instructions. Utilisez /memory pour gérer le contexte utile que Claude enregistre automatiquement.

Points clés

• CLAUDE.md contient des instructions Markdown persistantes que Claude Code charge dans son contexte ; il n'impose pas de configuration.
• Claude Code 2.1.277 ajoute un mécanisme conditionnel de AGENTS.md repli, dont Bedrock, Vertex et Foundry sont exclus au lancement.
• Un fichier situé dans un répertoire parent, CLAUDE.md, .claude/CLAUDE.md, ou CLAUDE.local.md désactive le mécanisme de repli par défaut.
• Définissez les instructions du projet sur claude-md-and-agents-md pour charger les deux familles d'instructions.
• Dans la version v2.1.277, les options du plugin doivent être placées dans les paramètres utilisateur, un --settings fichier ou les paramètres gérés, et non dans ceux du projet .claude/settings.json.
• Le .claude le répertoire contient également les paramètres, les commandes, les sous-agents et les compétences ; la mémoire automatique contient le contexte enregistré par Claude.

FAQ

Qu'est-ce que CLAUDE.md ?

CLAUDE.md est un fichier Markdown en texte brut contenant des instructions persistantes pour Claude Code, telles que des commandes de compilation, des conventions de codage, des notes d'architecture et des règles de travail. Claude le charge dans le contexte de la session, et /init peut générer un fichier de départ à partir du projet.

Quel fichier est chargé lorsque CLAUDE.md et AGENTS.md sont tous deux présents ?

Dans Claude Code 2.1.277, avec le mode par défaut claude-md-or-agents-md , un fichier d'instructions Claude répondant aux critères désactive le repli vers AGENTS. Sélectionnez claude-md-and-agents-md pour charger les deux, ou importez les instructions AGENTS voisines avec @AGENTS.md dans CLAUDE.md.

Pourquoi l'ajout de CLAUDE.local.md désactive-t-il le repli vers AGENTS ?

La version 2.1.277 inclut CLAUDE.local.md parmi les fichiers qui désactivent le repli par défaut lorsqu'ils sont trouvés entre la racine du système de fichiers et le répertoire de travail. Sa présence peut donc modifier le chargement des instructions AGENTS partagées, même si son rôle est de fournir des consignes personnelles pour le projet.

Puis-je activer les deux fichiers dans le fichier .claude/settings.json du projet ?

Dans la version v2.1.277, le fichier du projet .claude/settings.json ne fournit pas les agents-md options du plugin. Utilisez /config, ou placez la configuration documentée pluginConfigs dans les paramètres utilisateur, un --settings fichier ou les paramètres gérés.