Prise en charge de AGENTS.md dans Claude Code : comment l'utiliser avec CLAUDE.md

Claude Code prend en charge AGENTS.md depuis la v2.1.277 : dans un projet sans CLAUDE.md, Claude Code lit désormais votre AGENTS.md comme instructions de projet. Pas besoin d'import, de lien symbolique ni de réglage. Si votre dépôt contient les deux fichiers, Claude lit uniquement CLAUDE.md, sauf si vous modifiez le réglage Project instructions dans /config pour charger les deux.

Si votre équipe mélange plusieurs agents de codage, le même AGENTS.md que Codex et Cursor lisent déjà guide désormais Claude Code aussi. Ce guide couvre les règles de priorité, la migration, et un AGENTS.md qui apprend à n'importe quel agent à tester vos APIs avec l'Apidog CLI.

Qu'est-ce qu'AGENTS.md dans Claude Code ?

AGENTS.md est un simple fichier Markdown d'instructions destiné aux agents de codage : commandes de build, commandes de test, style de code et règles du projet. Depuis la v2.1.277, Claude Code le lit via un plugin intégré, si bien qu'un dépôt configuré pour d'autres agents fonctionne avec Claude Code sans fichiers supplémentaires. Aucun champ obligatoire ni syntaxe particulière n'est requis.

Le format lui-même est ouvert. Le site AGENTS.md le décrit comme « un format simple et ouvert pour guider les agents de codage », utilisé par plus de 60 000 projets open source et désormais placé sous la tutelle de l'Agentic AI Foundation au sein de la Linux Foundation. OpenAI Codex et Cursor documentent tous deux la prise en charge d'AGENTS.md, et Claude Code était le grand absent jusqu'à cette version.

Nouveau venu sur ce format ? Commencez par comment rédiger des fichiers AGENTS.md pour les équipes de développement d'API.

Voici l'historique de cette fonctionnalité extrait du changelog officiel de Claude Code :

Exécutez claude --version avant de compter sur tout cela. Sur toute version antérieure à 2.1.277, Claude Code ne lit que les fichiers CLAUDE.md.

CLAUDE.md vs AGENTS.md : lequel a la priorité ?

Par défaut, CLAUDE.md l'emporte. Claude Code ne lit AGENTS.md que s'il n'existe aucun CLAUDE.md dans votre répertoire de travail ni dans un répertoire parent. La documentation mémoire de Claude Code distingue trois cas :

Tous les fichiers ne comptent pas pour cette vérification. Ces trois-là bloquent AGENTS.md :

• CLAUDE.md dans le répertoire de travail ou au-dessus
• .claude/CLAUDE.md dans le répertoire de travail ou au-dessus
• CLAUDE.local.md dans le répertoire de travail ou au-dessus

Ceux-ci ne le bloquent pas et continuent d'être chargés en plus d'AGENTS.md : votre fichier utilisateur ~/.claude/CLAUDE.md, le CLAUDE.md géré par votre organisation, et les fichiers sous .claude/rules/.

Méfiez-vous du piège de CLAUDE.local.md : ajoutez-en un pour vos notes personnelles non committées, et Claude cesse de lire l'AGENTS.md de l'équipe pour vous.

Ce que Claude Code charge, et quand

Quand rien ne le bloque, Claude Code lit :

1. Au démarrage de la session : chaque AGENTS.md et .claude/AGENTS.md dans le répertoire de travail et les répertoires parents. Les sessions interactives affichent une ligne du type no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. Dans les sous-répertoires : l'AGENTS.md d'un sous-répertoire, dès que Claude ouvre un fichier à cet endroit avec l'outil Read et que ce dossier n'a pas son propre CLAUDE.md.
3. Les imports : les imports @path à l'intérieur d'AGENTS.md sont développés, et les motifs claudeMdExcludes s'appliquent.

Claude Code ne lit pas AGENTS.local.md, AGENTS.override.md, ni rien sous .agents/. Si vous partagez un dépôt avec Codex, qui documente AGENTS.override.md, gardez-le à l'esprit.

Comment modifier les fichiers d'instructions que Claude Code charge

Tapez /config dans une session et réglez Project instructions sur l'une des quatre valeurs suivantes :

Pour la plupart des équipes mixtes, claude-md-and-agents-md est le réglage qu'il vous faut. Il conserve votre CLAUDE.local.md personnel tout en chargeant l'AGENTS.md partagé.

Vous pouvez aussi le définir dans un fichier de paramètres. Claude Code lit cette entrée depuis ~/.claude/settings.json, un fichier --settings ou les paramètres gérés, et l'ignore dans les fichiers de paramètres de projet et locaux :

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

Avant la v2.1.285, l'ID du plugin était agents-md@builtin. Les versions à partir de 2.1.285 acceptent les deux ID, donc utilisez l'ancien si des installations plus anciennes partagent le fichier. Le changement prend effet dès votre prochain message.

Si Project instructions n'apparaît pas dans /config, votre session ne peut pas charger AGENTS.md : vous êtes sur une version antérieure à 2.1.277, vous avez désactivé le plugin intégré via /plugin, ou c'est votre première session après la mise à jour (cela fonctionne à partir de la suivante).

Comment migrer une ancienne solution de contournement AGENTS.md

Beaucoup d'équipes intégraient AGENTS.md dans Claude Code manuellement avant cette version. La documentation recommande :

Conservez l'import @AGENTS.md si quelqu'un dans votre équipe utilise encore une version antérieure à 2.1.277. C'est la seule configuration qui fonctionne sur toutes les versions.

Import ou lien symbolique ?

Si vous avez besoin de règles propres à Claude en plus du fichier partagé, utilisez un import. Claude lit d'abord le fichier importé, puis le reste :

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Si vous n'avez besoin de rien de spécifique à Claude, un lien symbolique suffit :

ln -s AGENTS.md CLAUDE.md

Deux pièges : les outils Edit et Write de Claude n'écrivent pas à travers un lien symbolique, et Git sur Windows restitue un lien symbolique commité comme un simple fichier texte d'une ligne, sauf si core.symlinks est activé. Si quelqu'un dans votre équipe utilise Windows, choisissez l'import.

Dans tous les cas, exécutez /context all dans votre prochaine session et vérifiez que CLAUDE.md apparaît sous Memory files.

Un seul AGENTS.md pour Codex, Cursor et Claude Code

L'avantage, c'est une source unique de vérité. Placez vos commandes de build, vos commandes de test et vos conventions dans AGENTS.md à la racine du dépôt. Codex, Cursor et Claude Code le liront tous.

Une organisation qui tient en pratique :

• AGENTS.md à la racine : tout ce dont chaque agent a besoin. Commandes, carte des dossiers, règles de style, ce qu'il ne faut pas toucher.
• AGENTS.md dans les grands sous-dossiers : les règles qui ne s'appliquent qu'à ces endroits, comme services/payments/AGENTS.md. Claude Code les charge à la demande quand il lit un fichier dans ce dossier.
• Un CLAUDE.md facultatif : seulement si vous avez besoin d'un comportement propre à Claude, comme le mode plan ou les hooks. Commencez-le par @AGENTS.md.

Une réserve : un AGENTS.md chargé via le réglage ne déclenche pas les hooks InstructionsLoaded, et n'est pas chargé depuis les répertoires --add-dir. Si vous dépendez de l'un ou l'autre, passez par l'import @AGENTS.md.

Apprenez à votre agent à tester vos APIs avec Apidog CLI dans AGENTS.md

Écrivez vos règles de test d'API une seule fois, et quel que soit l'agent qui ouvre le dépôt, les tests s'exécutent de la même manière. L'Apidog CLI fournit à l'agent une sortie JSON structurée qu'il peut lire, si bien que la boucle reste dans le terminal.

Configurez-le une fois par machine :

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Astuce : dites à votre agent « Lis https://apidog.com/apidog-cli-installation-guide.md et configure Apidog CLI ». Ce guide est rédigé pour les agents et couvre l'installation, la connexion et la skill.

Ajoutez ensuite une section comme celle-ci à votre AGENTS.md :

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Désormais, un seul prompt fait le travail dans Claude Code, Codex ou Cursor :

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

L'agent suit vos règles et exécute des commandes comme celles-ci :

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Chaque option ci-dessus provient de apidog <cmd> --help sur Apidog CLI 2.2.12. La même ligne apidog run avec -r junit s'intègre dans un pipeline CI, et --upload-report envoie le résumé de l'exécution vers l'application pour que votre équipe puisse le consulter. Pour le côté Claude Code en détail, voir comment utiliser l'Apidog CLI dans Claude Code ; les utilisateurs de Codex peuvent suivre l'Apidog CLI dans Codex. Apidog Free couvre jusqu'à 4 utilisateurs, une petite équipe peut donc essayer dès aujourd'hui.

Dépannage : mon AGENTS.md ne se charge pas

1. Cherchez un CLAUDE.md sur le chemin. Un CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md dans votre répertoire de travail ou au-dessus l'emporte par défaut. Votre ~/.claude/CLAUDE.md ne compte pas.
2. Vérifiez votre version. Exécutez claude --version. Il vous faut la 2.1.277 ou ultérieure, et la 2.1.281 ou ultérieure sur Bedrock, Vertex AI, Foundry, les passerelles ou avec la télémétrie désactivée.
3. Vérifiez le réglage. Ouvrez /config et assurez-vous que Project instructions n'est pas sur claude-md ou managed-only.
4. Confirmez le chargement. Exécutez /memory et cherchez le chemin d'AGENTS.md dans la liste.

FAQ

Claude Code lit-il AGENTS.md maintenant ? Oui, depuis la v2.1.277. En l'absence de CLAUDE.md dans votre répertoire de travail ou au-dessus, Claude Code lit automatiquement AGENTS.md comme instructions de projet.

Si j'ai à la fois CLAUDE.md et AGENTS.md, lequel Claude Code utilise-t-il ? CLAUDE.md uniquement, par défaut. Réglez Project instructions sur claude-md-and-agents-md dans /config pour charger les deux, CLAUDE.md en premier.

Faut-il supprimer mon CLAUDE.md qui importe @AGENTS.md ? Pas nécessaire. L'import ne charge jamais AGENTS.md deux fois, et il continue de fonctionner pour vos collègues sur des versions antérieures à 2.1.277. Supprimez-le seulement s'il ne contient rien d'autre et que tout le monde est passé à la nouvelle version.

Claude Code lit-il AGENTS.override.md comme Codex ? Non. Claude Code ignore AGENTS.override.md, AGENTS.local.md et tout ce qui se trouve sous .agents/.

AGENTS.md fonctionne-t-il sur Amazon Bedrock ou Google Vertex AI ? Oui, depuis la v2.1.281. Les versions antérieures sur Bedrock, Vertex AI, Foundry, les passerelles ou avec la télémétrie désactivée ne lisent que CLAUDE.md ; utilisez-y un import @AGENTS.md.