AGENTS.md vs CLAUDE.md : Le Standard Universel des Agents IA 2026

Sommaire

---

AGENTS.md Claude Code : la réponse en 30 secondes {#promesse}

AGENTS.md est le standard ouvert universel adopté par l'Agentic AI Foundation de la Linux Foundation pour configurer tous les agents IA de coding : Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Devin, Factory et plus de 60 000 dépôts open source en juin 2026. C'est un simple fichier Markdown à la racine du projet qui décrit ce qu'un agent doit savoir pour travailler correctement sur votre code : commandes, conventions, tests, sécurité.

Claude Code lit nativement CLAUDE.md, pas AGENTS.md — mais le workaround officiel consiste à créer un symlink : ln -s AGENTS.md CLAUDE.md. Vous obtenez ainsi un seul fichier source de vérité partagé entre tous vos outils.

Cet article explique pourquoi adopter AGENTS.md avec Claude Code change la donne pour les équipes multi-outils, comment l'écrire correctement, et l'exemple complet à copier dans votre projet.

Qu'est-ce que AGENTS.md exactement ? {#definition}

AGENTS.md est un format Markdown ouvert, initialement publié par OpenAI en août 2025, puis donné à l'Agentic AI Foundation (AAIF) sous la Linux Foundation en décembre 2025 aux côtés du Model Context Protocol (MCP) d'Anthropic et de goose de Block.

L'objectif ? Éviter aux équipes de maintenir cinq fichiers de configuration différents (CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, GEMINI.md, AGENT.md) pour cinq outils qui font tous la même chose : aider l'agent à comprendre votre projet.

Qui adopte AGENTS.md en 2026 ?

L'adoption a explosé : plus de 60 000 dépôts publics contiennent un AGENTS.md en juin 2026, selon les chiffres communiqués par GitHub et la Linux Foundation.

À quoi sert vraiment AGENTS.md ?

Le fichier AGENTS.md répond à six questions pratiques qu'un agent IA doit pouvoir résoudre sans deviner :

C'est la définition même d'un standard agents IA réutilisable : la même question, posée à n'importe quel agent, doit produire la même réponse.

AGENTS.md vs CLAUDE.md : quelles différences en 2026 ? {#vs}

Le débat AGENTS.md vs CLAUDE.md revient dans toutes les équipes qui passent de mono-outil à multi-outils en 2026. Voici les vraies différences.

Tableau de comparaison synthétique

Quand utiliser lequel ?

Pour une plongée profonde dans CLAUDE.md côté Anthropic, consultez notre [guide complet du fichier CLAUDE.md](/blog/claude-md-fichier-configuration-guide-complet-2026).

Claude Code lit-il AGENTS.md nativement ? {#compatibilite}

Non. En juin 2026, Claude Code ne lit pas AGENTS.md nativement. Il cherche CLAUDE.md à la racine du projet, dans le home utilisateur (~/.claude/CLAUDE.md) et dans .claude/ sous-dossiers.

Anthropic a publiquement déclaré son support de l'Agentic AI Foundation en y donnant le MCP, mais préfère pour l'instant garder CLAUDE.md comme convention propriétaire avec ses fonctionnalités avancées (imports @, modèle de mémoire à 3 couches, intégration avec les sub-agents).

Les workarounds qui marchent vraiment

Il existe trois patterns documentés pour faire cohabiter AGENTS.md et Claude Code :

1. Le symlink (recommandé)

# À la racine de votre projet
ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md AGENTS.md

Claude Code lit CLAUDE.md (qui pointe vers AGENTS.md), tous les autres outils lisent AGENTS.md directement. Un seul fichier source de vérité.

2. Le contenu dupliqué (Windows-friendly) Si vos développeurs sont sur Windows avec un Git qui ne suit pas les symlinks, écrivez les deux fichiers à l'identique et synchronisez-les via un hook pre-commit. C'est moins propre mais ça fonctionne.

3. Le pointeur unidirectionnel (équipes hybrides) Votre CLAUDE.md Claude Code contient simplement :

# Configuration projet
Toute la configuration partagée se trouve dans @AGENTS.md.
Ce fichier ajoute uniquement les sub-agents propres à Claude Code.

Vous gardez AGENTS.md comme source partagée et CLAUDE.md comme extension Anthropic-spécifique.

Pour aller plus loin, cette vidéo de Network Chuck explique en quoi AGENTS.md a bouleversé l'écosystème Claude Code en 2025 :

Comment écrire un AGENTS.md pour Claude Code ? {#ecrire}

Écrire un bon AGENTS.md demande de la discipline : ce n'est pas une documentation interne, c'est un contrat d'instructions lu par une machine qui doit prendre des décisions techniques.

Les 6 sections à couvrir absolument

GitHub a analysé plus de 2 500 dépôts contenant un AGENTS.md de qualité et identifié six sections récurrentes :

Règles de rédaction qui marchent

Pour des conventions pointues sur les prompts qui orientent l'agent vers les bons fichiers, lisez notre [guide pour écrire un bon prompt Claude Code](/blog/comment-ecrire-bon-prompt-claude-code).

Quand splitter en plusieurs AGENTS.md ?

Dans un monorepo, posez un AGENTS.md racine avec les conventions globales puis un AGENTS.md par package avec les spécificités. Les outils compatibles (Codex, Cursor, Gemini CLI) cherchent automatiquement le fichier le plus proche du fichier en édition. Pour Claude Code, la même logique s'applique à CLAUDE.md via la mémoire dynamique.

Exemple complet d'AGENTS.md prêt à copier {#exemple}

Voici un AGENTS.md de production réel, condensé pour un projet TypeScript / Next.js avec tests Vitest. Adaptez-le à votre stack.

# AGENTS.md

## Project context
Application Next.js 16 (App Router) + Prisma + PostgreSQL.
Frontend en TypeScript strict. UI en Tailwind CSS 4. Tests en Vitest.
Public : équipe interne, environnement multi-tenant.

## Setup
- Node.js 22+ obligatoire (voir `.nvmrc`)
- Package manager : `pnpm@9`, ne **jamais** utiliser npm ou yarn
- Install : `pnpm install`
- Variables d'environnement : copier `.env.example` vers `.env.local`

## Commands
- Dev local : `pnpm dev` (port 3000)
- Build production : `pnpm build`
- Tests : `pnpm test` (unitaires) + `pnpm test:e2e` (Playwright)
- Lint : `pnpm lint` (ESLint + Prettier check)
- Format : `pnpm format` (Prettier write)
- Type check : `pnpm typecheck`
- Migration BDD : `pnpm prisma migrate dev --name <description>`

## Code style
- TypeScript strict, jamais de `any` non commenté
- Imports absolus avec alias `@/` (configurer dans tsconfig)
- Composants React : PascalCase, un composant par fichier
- Hooks custom : préfixe `use`, dans `/src/hooks/`
- Pas de `console.log` en production (utiliser le logger interne)
- Pas de `useState` dans les Server Components

## Testing
- Coverage minimale : 80% sur `/src/lib/` et `/src/server/`
- Tests unitaires colocalisés : `foo.ts` + `foo.test.ts`
- Tests E2E dans `/tests/e2e/`
- Lancer `pnpm test:changed` avant chaque commit

## Git workflow
- Branches : `feat/<ticket>`, `fix/<ticket>`, `chore/<description>`
- Commits : Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`)
- Aucun commit direct sur `main` (protégé)
- PR template obligatoire (voir `.github/PULL_REQUEST_TEMPLATE.md`)
- Squash & merge pour les features, rebase pour les hotfix

## Security & boundaries
- Ne jamais committer `.env`, `.env.local`, `.env.production`
- Secrets exclusivement via variables d'environnement
- Aucun appel à un LLM externe sans validation côté serveur
- Migrations destructives interdites sans `-- review` dans le commit
- Aucun `git push --force` sur branches partagées
- `/scripts/maintenance/` n'est jamais exécuté en CI sans approbation

## Notes pour Claude Code spécifiquement
- Utiliser les sub-agents définis dans `.claude/agents/` (reviewer, test-writer)
- Skills disponibles : `/security-review`, `/spec` (voir `.claude/skills/`)
- La mémoire dynamique de session vit dans `.claude/memory/`

Ce template tient en moins de 80 lignes, couvre les six sections critiques et reste lisible. Vous pouvez l'enrichir mais surveillez la longueur.

Symlink AGENTS.md vers CLAUDE.md : le pattern recommandé {#symlink}

Le symlink AGENTS.md CLAUDE.md est la solution la plus propre pour qu'un projet soit immédiatement compatible avec Claude Code, Codex, Cursor et tous les autres agents IA en une seule commande.

La commande qui fonctionne sur macOS et Linux

# À la racine de votre projet, depuis Bash/Zsh
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md
git commit -m "chore: link CLAUDE.md to AGENTS.md as single source of truth"

Git conserve les symlinks par défaut (avec core.symlinks=true, qui est l'état natif sur Unix). Quand un collègue clone le projet, le symlink est recréé automatiquement.

Le cas Windows

Sur Windows, Git nécessite l'activation explicite des symlinks et des droits admin pour les créer, ce qui complique le partage. Trois options dans l'ordre de préférence :

Vérifier que le symlink fonctionne avec Claude Code

# Lancer Claude Code et taper :
/memory
# Vous devez voir CLAUDE.md référencé avec son contenu (qui vient de AGENTS.md)

Si Claude Code ne montre rien, soit le symlink est cassé, soit votre version de Claude Code est trop ancienne (< 0.42). Pour gérer la mémoire de Claude Code plus largement, consultez notre [guide sur la mémoire persistante de Claude Code](/blog/memoire-persistante-claude-code-guide-2026).

Quelles erreurs éviter avec AGENTS.md ? {#erreurs}

Cinq erreurs récurrentes dans les AGENTS.md que nous voyons en revue de projets.

Erreur 1 : faire trop long

Au-delà de 200 lignes, l'agent perd en précision. La règle est claire : 150 lignes max. Si vous débordez, splittez en plusieurs fichiers (un par package en monorepo, un global + un par domaine en monolithe).

Erreur 2 : dupliquer le README

Le README.md est pour les humains qui découvrent le projet. AGENTS.md est pour une machine qui doit exécuter des actions. Les deux peuvent cohabiter mais ne doivent pas se chevaucher. Le README explique le pourquoi, AGENTS.md liste le comment.

Erreur 3 : oublier les commandes destructives

Si vous ne dites pas explicitement à l'agent ce qu'il ne doit pas faire, il le fera un jour. No force push, No migration without review, No deletion of /backup/. Cette section est aussi importante que celle des commandes autorisées.

Erreur 4 : ne pas mettre à jour

Un AGENTS.md qui mentionne yarn alors que l'équipe est passée à pnpm il y a six mois est pire que pas de fichier du tout. Auditez-le chaque trimestre et reviewez-le dans les PRs qui changent l'infrastructure.

Erreur 5 : copier celui d'un autre projet

Chaque équipe a ses contraintes. Un AGENTS.md de chez OpenAI ne marchera pas chez vous. Partez du template ci-dessus, adaptez section par section, et testez : faites travailler l'agent sur une vraie tâche et regardez s'il respecte vos conventions.

Pour avoir un agent IA bien briefé, n'oubliez pas non plus de complémenter votre AGENTS.md avec une bonne stratégie de [revue de code multi-agents](/blog/claude-code-review-multi-agent) et un [système de tests automatisés](/blog/claude-code-tests-automatises-tdd) solide.

FAQ — AGENTS.md et Claude Code {#faq}

AGENTS.md remplace-t-il CLAUDE.md pour Claude Code en 2026 ?

Non. Claude Code lit CLAUDE.md, pas AGENTS.md. Le standard recommandé est de créer un symlink CLAUDE.md → AGENTS.md pour avoir un fichier source de vérité unique partagé entre Claude Code, Codex, Cursor, Copilot et les autres agents IA compatibles.

Quelle est la différence principale entre AGENTS.md et CLAUDE.md ?

AGENTS.md est un standard ouvert géré par la Linux Foundation, lu par 10+ outils IA. CLAUDE.md est une convention propriétaire Anthropic, plus riche (imports @, mémoire à 3 couches, intégration sub-agents) mais limitée à Claude Code. Pour les équipes multi-outils, AGENTS.md gagne. Pour les équipes full Claude Code qui utilisent les fonctionnalités avancées, CLAUDE.md reste meilleur.

Combien de lignes doit faire un AGENTS.md ?

Sous 150 lignes idéalement. Au-delà, l'agent dilue son attention. Si votre projet a besoin de plus, splittez en plusieurs AGENTS.md (un par package en monorepo, un par domaine en monolithe). Les outils compatibles cherchent automatiquement le fichier le plus proche du fichier en édition.

Faut-il committer AGENTS.md dans Git ?

Oui, obligatoirement. AGENTS.md doit être versionné dans le repo principal pour que tous les développeurs et toutes les CI/CD aient la même configuration. Considérez-le comme un fichier de configuration de premier ordre, au même niveau que package.json ou tsconfig.json.

Quels outils IA lisent AGENTS.md en juin 2026 ?

OpenAI Codex (créateur), Cursor, GitHub Copilot, Gemini CLI, Devin, Factory, Aider, Windsurf, Zed, et beaucoup d'autres. Claude Code ne le lit pas nativement mais le supporte via symlink CLAUDE.md → AGENTS.md. La liste s'enrichit chaque mois selon l'Agentic AI Foundation.

AGENTS.md fonctionne-t-il en monorepo ?

Oui. Posez un AGENTS.md racine pour les conventions globales, puis un AGENTS.md dans chaque package pour les spécificités. Les agents qui éditent un fichier dans packages/web/ liront le fichier le plus proche dans la hiérarchie. C'est exactement comme .eslintrc.js dans une stack JavaScript classique.

AGENTS.md peut-il référencer d'autres fichiers ?

C'est dépendant de l'outil. CLAUDE.md (Anthropic) supporte les imports avec @chemin/fichier. AGENTS.md standard ne supporte pas nativement les imports, mais vous pouvez utiliser des liens Markdown classiques ([Voir CONTRIBUTING.md](./CONTRIBUTING.md)) que les agents IA modernes savent suivre.

Comment intégrer AGENTS.md à un workflow d'agents auto-hébergés ?

Pour des agents IA déployés en interne ou auto-hébergés (en dehors de Claude Code), le pattern reste identique : AGENTS.md à la racine, l'agent le lit à l'init. Pour explorer les alternatives open-source à Claude Code et leur compatibilité AGENTS.md, voir la [formation OpenClaw sur les agents IA auto-hébergés](https://formation-openclaw.com).

Existe-t-il un linter pour valider un AGENTS.md ?

Oui, plusieurs. Le projet officiel agents-md-lint (npm) vérifie la structure et flag les sections manquantes. Pour la qualité du contenu (commandes valides, conventions explicites), aucun outil ne remplace une revue humaine + un test avec un vrai agent qui essaye de faire une tâche réelle.

Ressources complémentaires {#ressources}