Claude Code AGENTS.md : activer la lecture native

En bref : configurer Claude Code pour lire AGENTS.md

Procédez dans cet ordre :

1. Exécutez claude --version. Il faut la v2.1.277 ou une version ultérieure.
2. Effectuez la mise à jour si nécessaire. Une installation native accepte claude update ; Homebrew et WinGet utilisent les commandes de mise à niveau de leur propre gestionnaire de paquets.
3. Vérifiez que la session peut récupérer les feature flags d’Anthropic. Le chargement natif de AGENTS.md n’est pas disponible dans les sessions qui passent par un fournisseur tiers, comme Amazon Bedrock, Google Cloud's Agent Platform et Microsoft Foundry, ni lorsque les réglages de télémétrie ou de trafic non essentiel bloquent cette récupération.
4. Placez AGENTS.md ou .claude/AGENTS.md dans le chemin du projet. Avec le mode par défaut, vérifiez qu’aucun CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md de projet ne se trouve dans le répertoire de travail ou dans l’un de ses parents.
5. Si les deux familles de fichiers doivent coexister, ouvrez /config et réglez Project instructions sur claude-md-and-agents-md.
6. Faites le test dans une nouvelle session. La première session qui suit l’installation ou la mise à niveau constitue une exception : ouvrez donc la suivante avant de conclure.

Voilà pour le fonctionnement natif. Si Project instructions n’apparaît pas dans /config, conservez l’import documenté @AGENTS.md dans CLAUDE.md.

Claude Code AGENTS.md : quel fichier est réellement chargé ?

Ce nouveau comportement fonctionne comme un aiguillage, pas comme une recherche systématique de tous les fichiers d’instructions. Dans le mode par défaut claude-md-or-agents-md, Claude Code cherche d’abord les instructions Claude au niveau du projet. Il ne se replie sur AGENTS.md que si aucun fichier Claude admissible n’existe dans le répertoire de travail ou dans ses parents.

Le périmètre fait toute la différence. Un CLAUDE.local.md situé dans un répertoire parent désactive le repli. En revanche, un fichier personnel ~/.claude/CLAUDE.md, un CLAUDE.md administré par l’organisation et .claude/rules/ ne le désactivent pas. Cette nuance explique pourquoi deux développeurs qui ouvrent le même dépôt peuvent observer des comportements différents.

Lorsque le repli s’applique, Claude Code lit au démarrage de la session les fichiers AGENTS.md et .claude/AGENTS.md présents dans le répertoire de travail et ses parents. Le fichier AGENTS.md d’un sous-répertoire peut être chargé plus tard, lorsque Claude y lit un fichier, à condition que ce sous-répertoire ne contienne pas son propre fichier Claude admissible. En revanche, Claude Code ne lit pas directement AGENTS.local.md, AGENTS.override.md ni les fichiers placés sous .agents/.

Le mécanisme ressemble davantage au sélecteur électrique d’un bâtiment qu’à une recherche dans les dossiers. Le sélecteur commence par choisir le circuit d’instructions actif. Les fichiers de l’autre circuit peuvent être parfaitement valides tout en restant déconnectés.

Choisir volontairement le mode Project instructions

Ouvrez /config, repérez Project instructions, puis choisissez le mode adapté à la source de vérité du dépôt :

• Fallback, claude-md-or-agents-md : idéal pour un dépôt qui utilise déjà AGENTS.md et ne contient aucun fichier Claude de projet. C’est le réglage par défaut.
• Both, claude-md-and-agents-md : idéal si AGENTS.md rassemble les règles communes et CLAUDE.md les consignes propres à Claude.
• Claude only, claude-md : idéal lorsqu’une équipe ne souhaite pas encore exposer à Claude Code ses instructions communes aux agents.
• Managed only, managed-only : idéal dans un contexte de lancement contrôlé où la politique de l’organisation et la mémoire automatique doivent être chargées, mais pas les instructions du dépôt au démarrage.

En mode Both, Claude Code lit dans chaque répertoire le contenu Claude avant le contenu AGENTS. Il évite aussi de charger deux fois le même AGENTS.md lorsque CLAUDE.md l’importe déjà ou pointe vers lui par un lien symbolique.

Le choix s’applique dès le message suivant et persiste dans les nouvelles sessions. Il peut également être défini pour le plugin intégré agents-md@builtin dans les réglages utilisateur, dans un fichier --settings ou dans les réglages administrés. Claude Code ignore cette option dans les fichiers de réglages locaux et de projet : un dépôt ne peut donc pas imposer discrètement la même sélection à tous les développeurs. Un administrateur peut toutefois définir ce choix de manière centralisée au moyen des réglages administrés.

Vérifier le fichier chargé par une nouvelle session

Utilisez une information sans danger, jamais une instruction destructive. Ajoutez cette ligne au fichier à tester :

Project probe: BASALT-HERON.

Fermez ensuite la session, ouvrez-en une nouvelle dans le dépôt et demandez : What is the project probe? Si la réponse est bien BASALT-HERON, le contenu a atteint le contexte de la session. Supprimez la ligne après le contrôle.

Ne prenez pas /context comme unique verdict. Un AGENTS.md chargé directement n’apparaît pas dans sa liste Memory files. Avec le repli par défaut, une session interactive peut afficher au démarrage la ligne AGENTS.md loaded. La question fondée sur cette information inoffensive fonctionne aussi avec les autres modes de sélection.

Si le test échoue, contrôlez les points suivants dans cet ordre :

1. Version : v2.1.277 ou ultérieure.
2. Nombre de sessions : il ne doit pas s’agir de la première session après l’installation ou la mise à niveau.
3. Fournisseur : la session ne doit pas passer par un fournisseur qui empêche la récupération des feature flags d’Anthropic.
4. Environnement : aucune variable de télémétrie ou de trafic non essentiel ne doit désactiver cette récupération.
5. Plugin et politique : le plugin intégré agents-md doit être actif, et ni disableAllHooks ni allowManagedHooksOnly ne doit le bloquer.
6. Hiérarchie des fichiers : avec le mode par défaut, aucun CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md admissible ne doit se trouver au niveau courant ou dans un répertoire parent.
7. Mode : /config doit correspondre au comportement recherché.

Si Project instructions n’apparaît pas dans /config, c’est déjà un indice de diagnostic. Soit la version de la session n’est pas compatible, soit celle-ci ne peut pas utiliser la fonctionnalité.

Conserver l’import lorsque le mode natif ne fonctionne pas

L’import existant reste la couche de compatibilité la plus sûre pour Bedrock, Vertex, Foundry, les autres sessions via un fournisseur tiers, les environnements où la télémétrie est restreinte et les équipes qui mélangent plusieurs versions. Placez ceci dans le fichier CLAUDE.md situé à côté de AGENTS.md :

@AGENTS.md

Vous pouvez ajouter les instructions propres à Claude en dessous. Claude lit d’abord le fichier commun importé, puis les ajouts spécifiques à Claude. Conserver cette passerelle ne provoque pas de double chargement lorsqu’un utilisateur compatible choisit le mode Both.

Un lien symbolique de CLAUDE.md vers AGENTS.md fonctionne aussi, mais l’import reste le choix le plus sûr entre plateformes. Sous Windows, créer un lien symbolique peut nécessiter des droits élevés ou le mode développeur, tandis que Git doit disposer du bon réglage pour les liens symboliques. Une fois le chargement direct opérationnel, supprimez tout hook SessionStart qui affiche AGENTS.md, car il pourrait en injecter une seconde copie.

Cette version change l’équation de maintenance. Auparavant, une équipe dotée d’une politique commune à plusieurs agents devait souvent entretenir deux fichiers, un import de raccord ou un hook. Dans les sessions compatibles, le chemin par défaut peut désormais se limiter à un seul fichier d’instructions versionné. Le tarif de Claude, lui, ne baisse pas : Anthropic inclut Claude Code dans son offre Pro à $20 par mois. Le gain vient de la réduction des points de synchronisation et du nombre de sessions qui appliquent des règles obsolètes.

Pour aller plus loin, le guide complet de Claude Code détaille l’installation, le contexte du projet et les commandes du quotidien. Si votre dépôt définit aussi des agents spécialisés, le guide des sous-agents explique leur contexte de démarrage distinct.

Sept cas où cette nouveauté fait vraiment gagner du temps

Ce classement suit l’ampleur du problème de coordination que le nouveau sélecteur permet d’éliminer.

Les trois premiers cas offrent le meilleur retour, car les conséquences d’un échec se multiplient avec le nombre de personnes et de dépôts. Dans un dépôt individuel qui ne fait appel qu’à un agent, le confort est réel, mais limité.

Ce que vous pourriez construire autour de cette nouveauté

1. Un outil de diagnostic des instructions multi-agents

Créez un CLI local et un contrôle CI qui expliquent précisément quels fichiers d’instructions chaque agent de code va charger. Les équipes plateforme et les cabinets de conseil paieraient pour obtenir une réponse fiable avant de généraliser le dispositif à leurs dépôts.

La demande est déjà visible : claude code setup génère environ 1,900 recherches mensuelles aux États-Unis, tandis que claude md vs agents md en génère 480 et progresse de 1,500% sur un an. La plus petite version commercialisable analyse l’arborescence, lit la version de Claude Code et la configuration du fournisseur, signale les fichiers qui en masquent d’autres, puis affiche le plan d’ordre de chargement. Une offre payante destinée aux équipes pourrait appliquer la même politique dans tous leurs dépôts.

C’est l’opportunité la plus solide, car elle résout un problème de diagnostic plutôt qu’un simple besoin de modèle. Le risque vient de la plateforme : Anthropic pourrait intégrer ces contrôles à claude doctor. Pour rester pertinent, le produit devrait donc couvrir plusieurs agents de code et conserver un historique des dérives de politique, au lieu de dépendre d’une seule commande Claude.

2. Un générateur et linter de politiques AGENTS.md

Créez un éditeur guidé qui transforme les commandes de build, les règles de test, les limites entre répertoires et les exigences de revue en un AGENTS.md concis, puis repère les contradictions et les formulations vagues. La cible : les petites équipes d’ingénierie qui adoptent plusieurs agents.

La requête agents md génère environ 2,900 recherches mensuelles aux États-Unis. Plus précise, la requête agents md best practices en génère 210 et progresse de 750% sur un an. Un MVP doit inclure un scanner de dépôt, un bref questionnaire, un premier jet généré et des règles de lint pour détecter les consignes dupliquées ou contradictoires. Il doit respecter les recommandations du fournisseur sur la concision des fichiers de projet, sans produire un manuel de politique interminable.

Son point faible reste la défendabilité. N’importe quel agent de code sait rédiger du Markdown. Le produit ne justifie son existence que si sa validation reflète l’ordre de chargement réel et prouve que chaque outil de code compatible a bien consommé le résultat.

3. Un audit de migration pour les parcs d’agents mixtes

Proposez un rapport qui cartographie CLAUDE.md, AGENTS.md, les imports, les liens symboliques, les hooks, les règles imbriquées et les exceptions liées aux fournisseurs, puis établit un plan de migration sûr vers une source unique. Les clients les plus probables sont les agences et les grandes équipes qui utilisent plusieurs outils d’agents.

Les 480 recherches mensuelles pour claude md vs agents md, en hausse de 1,500% sur un an, témoignent de façon particulièrement directe de cette confusion. Le MVP peut prendre la forme d’un analyseur de dépôt en lecture seule accompagné d’un plan de pull request. Il ne doit jamais supprimer une passerelle automatiquement, car certaines sessions non compatibles peuvent encore en dépendre.

Le revers est une fenêtre de pertinence assez courte. Quand les équipes auront convergé vers une convention stable de fichier commun, les migrations ponctuelles diminueront. Les audits récurrents de politique et les contrôles de compatibilité des fournisseurs devront alors devenir le cœur du service.

Les limites, sans détour

Le repli natif supprime une passerelle. Il ne transforme pas les instructions de projet en mécanisme d’application, ne rend pas tous les fournisseurs compatibles et ne résout pas les conflits entre règles. Anthropic présente les fichiers d’instructions comme du contexte. Si une commande doit toujours être bloquée, utilisez une règle d’autorisation ou un hook PreToolUse.

Il ne rend pas non plus AGENTS.md visible dans les mêmes diagnostics que CLAUDE.md. Un chargement direct n’apparaît ni dans /memory ni dans la liste Memory files de /context. Cette incohérence justifie de conserver l’information de contrôle inoffensive dans votre checklist de migration.

Ne supprimez pas un import fonctionnel dans un parc de fournisseurs mixtes simplement parce que le test natif réussit sur un ordinateur portable. Ne choisissez pas non plus le mode Both avant d’avoir recherché les contradictions. Le contenu Claude est lu avant le contenu AGENTS dans un répertoire, mais l’ordre du contexte ne constitue pas un système strict de priorité des politiques.

Cette version reste une amélioration opérationnelle significative. Un dépôt qui considère déjà AGENTS.md comme sa source commune peut désormais fonctionner avec Claude Code sans faire passer le second nom de fichier pour la véritable source. La fonctionnalité paraît modeste, mais son effet sur la coordination est considérable.

Si vous souhaitez déployer un système fiable d’instructions multi-agents dans vos dépôts, je peux vous accompagner sur l’architecture et son déploiement.