Claude Code adopte AGENTS.md : un seul fichier d'instructions pour tous vos agents de code

Depuis la version 2.1.277 de Claude Code (18 septembre 2026), un projet sans fichier CLAUDE.md à la racine fait désormais lire à l'agent un fichier AGENTS.md à la place. C'est une bascule discrète dans le changelog, mais elle acte quelque chose de plus large : Claude Code rejoint un standard partagé avec Codex, Cursor, Aider, Zed, Warp et une vingtaine d'autres agents de code. Si vous maintenez un repo touché par plusieurs de ces outils, vous pouvez enfin tenir une seule source d'instructions au lieu d'un fichier par outil. Ce guide explique ce qu'AGENTS.md contient concrètement, comment cohabite-t-il avec CLAUDE.md, et comment migrer un projet existant sans rien casser. Si vous démarrez tout juste avec Claude Code, notre guide pour apprendre Claude et le guide d'installation de Claude Code sont un meilleur point de départ.

AGENTS.md, c'est quoi exactement

AGENTS.md est un fichier Markdown placé à la racine d'un dépôt, lu automatiquement en contexte par tout agent de code qui respecte la convention. C'est un README destiné aux agents, pas aux humains : commandes de build, conventions de code, structure du repo, zones sensibles. Le format lui-même n'a rien de propriétaire, c'est juste du Markdown avec des sections attendues.

Le standard est antérieur à l'intégration Claude Code. Il a été adopté par OpenAI Codex, Google Jules, GitHub Copilot Coding Agent, Cursor, Factory, Aider, Zed, Warp et d'autres avant qu'Anthropic ne s'y branche. Anthropic ne l'a pas créé ni ne le gouverne : Claude Code est l'un des derniers grands agents de code à rejoindre la convention, pas à l'initier. Le site officiel du standard est agents.md. Ne le confondez pas avec Agent Plugins (agent-plugins.org), un standard distinct qui empaquette des Skills et des serveurs MCP dans un format de distribution : deux standards ouverts multi-éditeurs séparés.

Concrètement, à l'ouverture d'une session Claude Code dans un dossier, l'agent cherche CLAUDE.md à la racine. S'il n'en trouve pas et que la version est 2.1.277 ou supérieure, il lit AGENTS.md à la place. Le contenu est injecté en début de contexte et guide toutes les décisions de la session : commandes qu'il tape, structure de fichiers qu'il respecte, fichiers qu'il ne touche pas.

Pourquoi Anthropic abandonne (partiellement) CLAUDE.md

Le point de départ était intenable pour quiconque bosse à plusieurs agents sur un même repo. Claude Code lisait CLAUDE.md, Cursor lisait .cursorrules, Codex lisait ses propres fichiers, Aider avait CONVENTIONS.md. Un même repo pouvait embarquer quatre fichiers d'instructions qui disaient à peu près la même chose. Chaque modification devait être répliquée quatre fois, et ces fichiers dérivaient inévitablement.

La bascule d'Anthropic ne supprime pas CLAUDE.md. La rétrocompatibilité est stricte : si CLAUDE.md existe, il continue d'être lu en priorité, AGENTS.md est ignoré. Aucun repo existant ne casse. Le fichier lu par défaut se change dans /config si vous voulez forcer l'un ou l'autre.

Une nuance à connaître : cette bascule est disponible sur Claude Code standard, pas sur les déploiements Amazon Bedrock, Google Vertex AI ou Microsoft Foundry, qui continuent de ne lire que CLAUDE.md pour l'instant. Si votre équipe passe par une de ces plateformes, gardez CLAUDE.md comme source primaire.

CLAUDE.md vs AGENTS.md : que garder, que migrer

Trois cas couvrent la quasi-totalité des situations.

La règle de précédence est simple : CLAUDE.md gagne toujours si présent. Vous pouvez donc traiter AGENTS.md comme votre base commune et CLAUDE.md comme votre override Claude Code. Aucun mécanisme de fusion automatique entre les deux fichiers n'est documenté : si CLAUDE.md existe, AGENTS.md n'est pas lu du tout par Claude Code, il faut donc dupliquer explicitement ce que vous voulez conserver.

Pour un projet Next.js typique déployé sur Vercel avec Supabase (le genre de stack qu'on utilise pour construire une application avec Claude Code), le contenu partagé est massif : commandes pnpm, conventions TypeScript, structure app/, règles Tailwind. Ça, c'est AGENTS.md. Les commandes slash Claude Code custom, les hooks PreToolUse, la configuration du sandbox : ça, c'est CLAUDE.md.

Que mettre dans un AGENTS.md qui sert vraiment

Un bon fichier tient en 100 à 300 lignes. Au-delà, l'agent commence à ignorer les sections lointaines ou à mélanger les priorités, et vous polluez le contexte de chaque session avec du texte inutile.

Les sections qui servent vraiment :

• Setup : gestionnaire de paquets utilisé, version de Node, variables d'environnement obligatoires
• Commands : dev, build, test, lint, typecheck. Les commandes exactes, avec leurs flags
• Code style : nommage (camelCase, PascalCase), quotes, imports absolus vs relatifs, patterns interdits
• Repo structure : où sont les composants, les routes API, les migrations, les tests
• Commit workflow : format des messages, branches, exigences avant push (tests verts, lint clean)
• Do not touch : fichiers générés, secrets, migrations passées, dépendances gelées

Ce qu'il ne faut jamais y mettre : documentation produit, historique des décisions, contexte business. Ça encombre le contexte sans jamais aider l'agent à écrire une meilleure ligne de code. Gardez ces choses dans un README.md ou un dossier docs/.

Exemple de AGENTS.md pour un projet Next.js déployé sur Vercel

Voici un fichier complet, prêt à copier, pour un projet Next.js 15 + TypeScript + Tailwind + Supabase + déployé sur la stack Vercel + Next.js recommandée.

# AGENTS.md

## Setup

- Package manager: pnpm (10.x)
- Node: 22.x (voir .nvmrc)
- Copier .env.example vers .env.local avant tout run
- Variables requises: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY

## Commands

- pnpm dev            # dev server sur :3000
- pnpm build          # build production
- pnpm test           # vitest en mode run
- pnpm test:watch     # vitest en mode watch
- pnpm lint           # eslint + prettier check
- pnpm typecheck      # tsc --noEmit
- pnpm db:migrate     # applique les migrations Supabase

Avant tout commit: pnpm lint && pnpm typecheck && pnpm test

## Code style

- TypeScript strict, pas de any
- Composants React en PascalCase, hooks en camelCase avec prefixe use
- Imports absolus depuis @/, jamais de ../../..
- Server Components par défaut, 'use client' seulement si nécessaire
- Pas de default export sauf pour les pages Next.js (route.tsx, page.tsx)

## Repo structure

- app/                # routes App Router
- app/api/            # routes API (route handlers)
- components/         # composants réutilisables
- components/ui/      # primitives (shadcn)
- lib/                # utilitaires, clients Supabase
- lib/db/             # requêtes DB, types Drizzle
- supabase/migrations # migrations SQL, ne jamais editer une migration existante

## Testing

- Vitest pour unit + integration
- Playwright pour e2e (dossier e2e/)
- Un test par fonction publique dans lib/

## Deployment

- Preview auto sur chaque PR (Vercel)
- main = production
- Ne jamais push direct sur main

## Do not touch

- supabase/migrations/*.sql (past migrations)
- pnpm-lock.yaml sauf via pnpm install
- .next/, node_modules/
- Fichiers *.generated.ts

Ce fichier fait environ 50 lignes utiles. C'est suffisant pour cadrer 80 % des sessions. Chaque équipe ajoutera ce qui lui manque (règles i18n, conventions API, patterns d'error handling), mais pas au-delà de 300 lignes.

Migrer un projet existant en 10 minutes

La procédure est courte et sans risque grâce à la rétrocompatibilité.

1. Créer AGENTS.md à la racine. Copier depuis CLAUDE.md tout ce qui est générique (commandes, style, structure, commit workflow, do not touch).
2. Alléger CLAUDE.md pour ne garder que le spécifique Claude Code : commandes slash custom, hooks, references à des skills, comportement particulier attendu de Claude. Si vous n'avez rien de spécifique, supprimez purement CLAUDE.md.
3. Committer les deux fichiers sur une branche. Nommer le commit clairement : "chore: adopt AGENTS.md, split Claude-specific config into CLAUDE.md".
4. Tester en session Claude Code. Lancer claude dans le dossier, vérifier avec /status ou /context que le fichier attendu est bien chargé. Poser une question qui touche à une convention ("quelle commande de test on utilise ?") pour valider que le contexte est effectif.
5. Répliquer sur les autres agents. Si Cursor tournait sur .cursorrules, pointer sa config vers AGENTS.md (via son param custom rules file) et supprimer .cursorrules. Idem pour Codex, Aider.

Sur un repo Next.js/Supabase standard, l'opération prend 10 minutes si vous avez déjà un CLAUDE.md propre. Elle en prend 30 si votre CLAUDE.md est un fourre-tout de 800 lignes qu'il faut d'abord trier. Profitez de la migration pour élaguer, votre agent ira mieux.

Limites et pièges à connaître

AGENTS.md n'est pas un standard strict. Chaque équipe invente ses sections, chaque agent lit le fichier à sa façon. Certains ne prennent que les premières lignes, d'autres tout, aucun ne garantit qu'une instruction précise sera respectée à 100 %. Le fichier est un guide, pas un contrat.

Le piège classique est le fichier obèse. Un AGENTS.md qui grossit au fil des mois finit par occuper une portion significative de la fenêtre de contexte de chaque session. Sur des modèles avec des tokenizers récents (Sonnet 5, Opus 5, Fable 5.1), 500 lignes de Markdown pèsent déjà lourd. Élaguer trimestriellement.

Autre piège : l'agent peut ignorer une règle claire. "Ne jamais toucher supabase/migrations/*.sql" peut être respecté 95 fois sur 100 puis violé au 96e passage. Le mode auto de Claude Code (devenu défaut en août 2026) bloque une bonne partie des actions destructrices, mais ne remplace pas une revue humaine du premier commit d'un agent sur un nouveau projet. Relire systématiquement.

Enfin, méfiez-vous des instructions contradictoires entre AGENTS.md et CLAUDE.md quand les deux coexistent. Claude Code lit CLAUDE.md et ignore AGENTS.md dans ce cas, mais si vous avez oublié cette précédence, vous croirez que l'agent ignore vos règles alors qu'il lit un autre fichier. Un commentaire en tête de CLAUDE.md du type "# Claude-specific overrides, voir AGENTS.md pour le reste" évite la confusion en équipe.

Passer à la pratique

Si vous maintenez un seul projet avec Claude Code, gardez CLAUDE.md, la migration n'apporte rien. Si vous jonglez déjà entre plusieurs agents sur un même repo, faites la bascule cette semaine, vous gagnerez des heures dès le mois prochain. Pour aller plus loin sur la façon de configurer Claude pour un usage quotidien ou sur les patterns d'architecture d'un projet piloté par plusieurs agents, l'idée est de traiter AGENTS.md comme du code : versionné, revu en PR, élagué régulièrement. Si vous voulez apprendre à construire un vrai produit IA avec cette rigueur d'ingénierie, dans une cohorte encadrée avec code review sur vos commits, jetez un œil à Construire votre produit IA en 5 semaines.