Claude Code et AGENTS.md : comment fonctionnent les fichiers d'instructions des agents IA en 2026

Ce qu'est AGENTS.md et pourquoi il existe

Pendant un temps, chaque outil de programmation a inventé son propre fichier d'instructions. Cursor avait .cursorrules, Claude Code avait CLAUDE.md, Aider avait .aider.conf.yml, Gemini avait GEMINI.md, et ainsi de suite. Si vous annotiez votre dépôt pour un agent, il fallait tout recommencer pour le suivant.

AGENTS.md est la solution : un format ouvert pour guider les agents de programmation, un seul fichier en Markdown simple à la racine du dépôt que de nombreux agents lisent. Le projet l'appelle un "README for agents", la formule la plus claire que je connaisse. Votre README.md s'adresse aux humains (démarrage rapide, guide de contribution) ; AGENTS.md contient le contexte supplémentaire dont un agent a besoin (étapes de build, tests, conventions) et qui encombrerait un README.

Il n'y a aucun champ obligatoire. C'est du Markdown : utilisez les titres que vous voulez et l'agent interprète le texte. Le standard est né d'une collaboration à l'échelle de l'écosystème, avec notamment OpenAI Codex, Amp, Jules de Google, Cursor et Factory, et le premier commit date du 19 août 2025. Il a depuis trouvé un foyer neutre et est désormais piloté par l'Agentic AI Foundation, sous l'égide de la Linux Foundation, avec le dépôt hébergé sur agentsmd/agents.md sous licence MIT.

Ce n'est pas une expérience de niche. Le dépôt compte 24,5k étoiles, une recherche de code sur GitHub renvoie plus de 60k fichiers d'exemple, et même le dépôt d'OpenAI en contient 88. Si vous l'aviez écarté comme un effet de mode, c'est le moment où j'arrêterais.

Quels agents le lisent réellement

La page d'accueil recense 24 outils compatibles, et la liste couvre une bonne part de la catégorie : Zed, OpenAI Codex, Gemini CLI, Cursor, Jules, Devin, Warp, Windsurf, VS Code, l'agent de programmation de GitHub Copilot, Aider, goose, Amp, et d'autres. Et, depuis ce mois-ci, Claude Code aussi. Quand autant d'éditeurs concurrents s'accordent discrètement sur le même fichier simple, le format a pratiquement gagné.

Claude Code lit-il AGENTS.md ? Oui, nativement désormais

C'est la question avec laquelle la plupart des gens arrivent, voici donc la réponse directe : Claude Code lit AGENTS.md nativement, à condition d'avoir la v2.1.277 ou ultérieure (sortie le 18 septembre 2026, lorsqu'Anthropic a adopté la spécification commune à plusieurs outils). Un dépôt que d'autres agents comprennent déjà fonctionne avec Claude Code sans que vous ajoutiez un CLAUDE.md, une ligne d'import ou un réglage.

Le piège, c'est ce qui se passe quand les deux fichiers existent. Le comportement par défaut :

Le piège est donc un CLAUDE.md périmé qui l'emporte en silence sur un AGENTS.md soigneusement entretenu. Si vous voulez les deux, le réglage Project instructions (/config) propose les valeurs claude-md-or-agents-md (par défaut), claude-md-and-agents-md (les deux, CLAUDE en premier), claude-md (CLAUDE seul) et managed-only. À savoir : un CLAUDE.local.md compte aussi comme fichier de la famille CLAUDE ; en ajouter un empêche donc Claude de lire l'AGENTS.md tant que vous ne modifiez pas ce réglage. Votre ~/.claude/CLAUDE.md, les fichiers de politique gérée et .claude/rules/ ne comptent pas dans la vérification « a un CLAUDE.md » et continuent donc de se charger avec AGENTS.md.

Une dernière particularité à garder en tête : un AGENTS.md lu directement n'apparaît pas dans /memory ni dans /context, et les hooks InstructionsLoaded ne se déclenchent pas pour lui. Vous confirmez son chargement grâce à la ligne AGENTS.md loaded au début de la session. Si vous découvrez l'outil, notre guide de prise en main et la référence de la CLI couvrent les bases.

CLAUDE.md vs AGENTS.md : la différence, honnêtement

On présente souvent cela comme une rivalité. Ce n'en est pas vraiment une. AGENTS.md est le standard commun à plusieurs outils ; CLAUDE.md est le système d'instructions plus riche propre à Claude Code. Les deux sont du Markdown simple, et Claude lit désormais l'un comme l'autre.

En pratique : si votre équipe utilise un mélange d'agents de programmation, gardez la source de vérité dans AGENTS.md. Si vous n'utilisez que Claude Code et voulez des imports ou des règles par chemin, CLAUDE.md offre plus de mécanismes. Et vous pouvez avoir les deux, à condition de les relier volontairement plutôt que par accident.

Autant le dire clairement : CLAUDE.md ne disparaît pas et n'est pas « moins bon ». Il propose des fonctions qu'AGENTS.md laisse volontairement de côté (la spécification reste minimale à dessein). Choisir l'un ou l'autre dépend du nombre d'outils que vous utilisez, pas de celui qui est le mieux conçu.

Comment Claude Code charge les fichiers d'instructions

Les fichiers CLAUDE.md se chargent de la portée la plus large à la plus précise, et tout ce qui est trouvé est concaténé plutôt que remplacé, si bien que les instructions les plus proches de l'endroit où vous avez lancé Claude sont lues en dernier. Il y a quatre portées :

1. Politique gérée (à l'échelle de l'organisation, chargée en premier, impossible à exclure). Elle se trouve à des chemins propres à chaque système, comme /Library/Application Support/ClaudeCode/CLAUDE.md sous macOS.
2. Utilisateur (~/.claude/CLAUDE.md), vos préférences personnelles pour tous les projets.
3. Projet (./CLAUDE.md ou ./.claude/CLAUDE.md), partagé avec l'équipe via le gestionnaire de versions.
4. Local (./CLAUDE.local.md), vos notes privées par projet, que vous ajoutez à .gitignore.

La découverte est récursive : Claude charge les fichiers CLAUDE.md de votre répertoire de travail et de tous les répertoires au-dessus. Les fichiers des sous-répertoires situés en dessous de vous ne sont pas chargés au lancement ; ils sont chargés à la demande lorsque Claude lit des fichiers dans ces dossiers. Ce comportement par sous-arborescence est exactement ce qui garde les monorepos gérables, et il reflète le fonctionnement d'AGENTS.md : le fichier le plus proche l'emporte, et une instruction explicite dans le chat prime sur tout. Pour donner l'échelle, le dépôt principal d'OpenAI contient 88 fichiers AGENTS.md distincts, un par paquet.

Ce découpage par paquet compte plus qu'il n'y paraît, car un seul fichier à la racine atteint un plafond sur une grosse base de code. C'est la plainte la plus fréquente que je vois chez ceux qui utilisent ces outils à grande échelle :

"AGENTS dot md files don't scale beyond modest codebases. Lots of discussions on this lately. If you're building serious software with Claude Code or any agentic tool, a single AGENTS dot md will eventually fail you."

elvis (@omarsar0), X

La solution n'est pas un fichier plus gros mais plus de fichiers : un fichier racine court, plus un fichier imbriqué dans chaque paquet, pour que l'agent lise toujours des instructions adaptées à ce qu'il touche.

Les imports et la limite de 4 niveaux

CLAUDE.md peut inclure d'autres fichiers avec la syntaxe @path/to/import. Les chemins relatifs et absolus fonctionnent, les fichiers importés peuvent en importer d'autres jusqu'à une profondeur maximale de quatre niveaux, et entourer un chemin de backticks empêche l'import (pratique quand vous voulez simplement mentionner un fichier). Un piège pour ceux qui veulent réduire leur contexte : découper en imports ne réduit pas la consommation de tokens, car les fichiers importés sont tout de même chargés au lancement. Cela aide à l'organisation, pas à la taille.

Que mettre dans un bon AGENTS.md (ou CLAUDE.md)

Aucune section n'est obligatoire, mais les plus courantes sont la présentation du projet, les commandes de build et de test, le style de code, les consignes de test, les notes de sécurité et les règles de PR ou de commit. L'exemple canonique de la spécification ressemble à ceci :

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <project_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Le détail qui en fait plus qu'une documentation : les commandes de test que vous listez sont exécutées automatiquement. L'agent essaiera de lancer les vérifications pertinentes et de corriger les échecs avant de terminer. Une ligne précise avec pnpm test n'est donc pas une note, c'est une instruction sur laquelle l'agent agit.

Pour la rédaction elle-même, le guide d'Anthropic pour CLAUDE.md s'applique tout aussi bien à AGENTS.md, car les deux sont chargés dans la fenêtre de contexte et traités comme du contexte, non comme une configuration imposée :

• Restez bref. Visez moins de 200 lignes ; les fichiers plus longs consomment du contexte et, d'après la documentation, réduisent en réalité la façon dont l'agent les suit.
• Soyez précis. Selon le guide de rédaction, "Use 2-space indentation" vaut mieux que "Format code properly" ; "Run npm test before committing" vaut mieux que "Test your changes." Écrivez des règles assez concrètes pour être vérifiables.
• Structurez. Des titres et des puces en Markdown pour regrouper les instructions apparentées.
• Restez cohérent. Si deux règles se contredisent, Claude peut en choisir une arbitrairement ; relisez donc régulièrement les fichiers imbriqués.

Bien fait, cela rapporte plus que la plupart ne l'imaginent. Comme l'a dit un développeur dans un fil Ask HN sur l'entretien de ces fichiers :

"AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes."

bisonbear, Hacker News

Le moyen le plus rapide d'obtenir un premier brouillon est /init, qui analyse votre base de code pour y trouver commandes de build, tests et conventions, et écrit un fichier de départ (il peut aussi migrer un fichier Cursor ou Copilot). Modifiez-le ensuite avec /memory et vérifiez ce qui a réellement été chargé avec /context. Et comme un CLAUDE.md est transmis comme un message utilisateur après le prompt système, il n'y a aucune garantie de respect strict ; si vous avez besoin qu'une règle soit appliquée coûte que coûte, la documentation renvoie vers un hook PreToolUse plutôt que vers le fichier d'instructions.

Comment partager un seul fichier entre tous les agents

Si vous utilisez Claude Code aux côtés de Codex, Cursor ou Gemini, l'objectif est une source de vérité unique. Avec la prise en charge native, c'est désormais le comportement par défaut : mettez tout dans AGENTS.md et n'ajoutez pas de CLAUDE.md.

Si vous êtes sur une version plus ancienne, ou dans une configuration où la lecture native n'est pas disponible (Amazon Bedrock, autres fournisseurs tiers ou télémétrie désactivée), la solution de repli consiste à l'importer depuis un CLAUDE.md :

# CLAUDE.md
@AGENTS.md

Il y a aussi le classique lien symbolique, même si la documentation le considère désormais comme un dernier recours :

ln -s AGENTS.md CLAUDE.md

La voie du lien symbolique a de vraies limites : les outils Edit et Write de Claude refusent d'écrire à travers le lien (ils redirigent les modifications vers l'AGENTS.md cible), et sous Windows un lien symbolique commité est extrait comme du texte brut si core.symlinks n'est pas activé. C'est pourquoi l'import est aujourd'hui la solution la plus propre. La commande officielle en une ligne pour migrer un ancien fichier est :

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Erreurs courantes à éviter

Quelques pièges que je vois sans cesse, dont la plupart découlent directement des règles de priorité :

• Un CLAUDE.md oublié qui écrase en silence votre AGENTS.md. Si les deux existent, Claude lit le CLAUDE.md. Supprimez le périmé ou importez l'autre.
• Traiter les imports comme un régime. Découper un énorme fichier en imports avec @ ne réduit pas le contexte ; tout est tout de même chargé. Réduisez plutôt le contenu.
• Des règles vagues. "Write clean code" ne sert à rien. Donnez la commande exacte, l'indentation exacte, le format exact du titre de PR.
• Un fichier de 600 lignes. Au-delà d'environ 200 lignes, le respect des consignes baisse. Déplacez les procédures en plusieurs étapes vers des skills ou des sous-agents, et les règles propres à une partie de la base de code vers des fichiers .claude/rules/ ciblés par chemin.
• Supposer que c'est appliqué de force. Les fichiers d'instructions sont du contexte, pas une barrière stricte. Pour un vrai blocage, utilisez un hook.

Pour l'environnement autour de vos fichiers d'instructions, jetez un œil au guide de settings.json et aux permissions, car les deux influent sur la façon dont les règles sont réellement appliquées.

Essayer eesel : la même idée, pour les agents qui gèrent votre support

Voici le lien. AGENTS.md et CLAUDE.md sont le moyen de confier à un agent de programmation ses instructions permanentes dans un fichier. Cet agent de programmation est une infrastructure que vous configurez. eesel est l'autre moitié du tableau : au lieu d'un outil que vous instruisez, c'est un coéquipier IA prêt à travailler que vous embauchez pour une mission précise, aujourd'hui un agent de helpdesk IA qui traite votre file de support et un rédacteur de blog IA.

Et il repose sur la même philosophie : « les instructions vivent au même endroit ». Les règles permanentes d'un agent eesel ne sont pas éparpillées dans des écrans de réglages ; c'est un seul ensemble d'instructions modifiable, plus vos vraies connaissances (anciens tickets, centre d'aide, documentation). C'est le modèle mental d'AGENTS.md appliqué à un coéquipier du support.

Si vous vivez déjà dans le terminal, cela vous sera familier. eesel propose une vraie CLI (@eesel/cli), et sa documentation est claire sur l'intention : tout ce que vous pouvez faire dans le tableau de bord, vous pouvez le faire depuis le terminal, y compris en laissant un agent de programmation IA s'occuper de la configuration. Vous pouvez l'exécuter sans installation (npx @eesel/cli init), discuter avec l'agent (eesel chat), modifier ses règles permanentes (eesel instructions) et voir ce qu'il a fait (eesel activity). Chaque commande affiche du JSON et prend en charge --dry-run, ce qui le rend pilotable par un script ou un agent plutôt que par une personne qui clique.

Mieux encore, chaque espace de travail eesel est aussi un serveur MCP. Lancez eesel mcp token et il affiche une ligne claude mcp add prête à coller, pour que Claude Code (ou Cursor, ou Codex) puisse gérer les instructions de votre agent de support, consulter son activité et approuver les actions en attente sans quitter votre éditeur. Le même agent, trois surfaces : terminal, scripts et agents de programmation via MCP.

La tarification est un prix mensuel fixe à partir de $299/mois pour 500 crédits (1 crédit par ticket ou chat), les questions dans le tableau de bord sont pour la plupart gratuites, et il existe une offre gratuite avec 100 crédits et sans carte. Si vous écrivez déjà des fichiers AGENTS.md, vous serez à l'aise. Essayez eesel ou pointez Claude Code vers lui et laissez-le faire le câblage.