CLAUDE.md vs AGENTS.md : que choisir pour ton repo IA ?

60 000 dépôts open source embarquent désormais un fichier AGENTS.md à leur racine. En parallèle, le repo claude-code-best-practice de shanraisshan a dépassé les 36 000 étoiles sur GitHub en quelques semaines — porté par un seul fichier : CLAUDE.md. Et en décembre 2025, la Linux Foundation a créé l’Agentic AI Foundation (AAIF) pour standardiser tout ça, avec OpenAI, Anthropic et Google autour de la table.

Le message est limpide : tes prochains “collègues” les plus assidus sur ton code ne seront pas des humains. Ce seront des agents IA. Et le README classique ne leur suffit plus.

Mais entre CLAUDE.md (puissant, spécifique à Claude) et AGENTS.md (ouvert, universel), lequel choisir ? Faut-il les deux ? Ni l’un ni l’autre ? Voici un comparatif sans complaisance — avec des exemples concrets et un avis tranché.

Pourquoi ton README ne parle pas aux agents IA

Quand Andrej Karpathy a annoncé début 2026 qu’il était passé de 80 % de code écrit à la main à 80 % de code généré par des agents, le monde du développement a pris note. Ce n’est plus un cas isolé : selon Anthropic, les développeurs utilisant Claude Code passent en moyenne 2 à 3 heures par jour à piloter des agents qui lisent, modifient et testent leur code.

Le problème ? Ces agents ne lisent pas ton repo comme un humain. Un développeur qui arrive sur un projet ouvre le README, parcourt l’arborescence, lit quelques fichiers clés et se fait une image mentale. Un agent IA, lui, a une fenêtre de contexte limitée — chaque fichier lu consomme des tokens, et les performances dégradent dès 60 % de capacité. Il ne peut pas “parcourir” — il a besoin qu’on lui dise précisément quoi savoir.

Un README classique explique ce que fait un projet. Un fichier contexte IA explique comment travailler dedans : quelles commandes lancer, quels patterns suivre, quels fichiers ne jamais toucher. C’est la différence entre une brochure touristique et un briefing opérationnel.

Des chercheurs de Columbia University l’ont résumé dans une étude de mars 2026 : les agents ont besoin de savoir “où sont les choses, quelles règles suivre et comment implémenter les changements” — pas d’un résumé de haut niveau du projet. Le README parle aux humains. Les fichiers contexte parlent aux machines.

CLAUDE.md : le couteau suisse de Claude Code

CLAUDE.md est un fichier Markdown que Claude Code lit automatiquement au début de chaque session. Tu y mets les commandes de build, les conventions de code, les règles de workflow — tout ce que Claude ne peut pas deviner en lisant le code seul.

Ce qui le rend puissant

CLAUDE.md est taillé sur mesure pour Claude Code. Il peut exploiter des fonctionnalités exclusives : délégation à des sous-agents, niveaux de permission, gestion de session, référence directe aux capacités de Claude. C’est l’avantage du vendor-lock — quand tu cibles un seul outil, tu peux aller beaucoup plus loin.

Le fichier supporte aussi une hiérarchie de répertoires : un CLAUDE.md à la racine pour les règles globales, des fichiers spécifiques dans /frontend ou /api pour les contextes locaux. Claude charge automatiquement le fichier le plus proche du code sur lequel il travaille.

Autre force : l’écosystème. Les skills (fichiers .skill chargés à la demande) permettent de garder le CLAUDE.md léger en déportant les workflows spécifiques. Les hooks automatisent des actions déterministes (linter après chaque edit, bloquer les commits sur certains dossiers). Et les plugins ajoutent des intégrations en un clic.

Le repo andrej-karpathy-skills — un simple CLAUDE.md distillant 4 principes issus des observations de Karpathy sur les erreurs récurrentes des LLMs — a atteint 17 000 étoiles. Preuve que même un fichier minimaliste peut avoir un impact majeur.

Où ça coince

Vendor-lock. CLAUDE.md ne sert qu’à Claude Code. Si ton équipe utilise aussi Cursor, Copilot, Codex ou Gemini CLI, ils ignorent ce fichier. Tu te retrouves à maintenir des instructions en double.

Taxe sur le contexte. Chaque token dans CLAUDE.md est un token que tu ne peux plus utiliser pour ta conversation. Un fichier trop long dégrade les performances de façon mesurable — Anthropic recommande de se poser la question : “Si je supprime cette ligne, est-ce que Claude fera des erreurs ?” Si non, il faut couper.

Le piège de la génération automatique. Une étude d’ETH Zurich (arxiv 2602.11988) sur 138 repos a montré que les fichiers contexte générés par des LLMs réduisent le taux de succès des agents de 3 % par rapport à… aucun fichier du tout. Pire, ils augmentent les coûts d’inférence de 20 %. Les fichiers écrits par des humains font à peine mieux : +4 % de réussite. Le message est clair — un fichier contexte n’est pas un README v2 à générer une fois et oublier. C’est un outil chirurgical, ou c’est du bruit.

AGENTS.md : le standard ouvert qui unifie l’écosystème

Si CLAUDE.md est le couteau suisse d’un seul fabricant, AGENTS.md est la norme ISO que tout le monde peut lire.

Les origines

Lancé initialement par Sourcegraph, AGENTS.md a rapidement été adopté par l’industrie. En décembre 2025, la Linux Foundation a créé l’Agentic AI Foundation (AAIF) pour en assurer la gouvernance, aux côtés de deux autres projets fondateurs : le Model Context Protocol (MCP) d’Anthropic et goose de Block.

Les membres platine de l’AAIF ? AWS, Anthropic, Bloomberg, Cloudflare, Google, Microsoft et OpenAI. Quand tes concurrents les plus féroces s’assoient à la même table pour un standard, c’est que le sujet est sérieux.

Qui le supporte

La liste ne cesse de s’allonger : GitHub Copilot, OpenAI Codex, Google Jules, Cursor, Gemini CLI, Amp, Factory, RooCode, Zed, Warp — et d’autres encore. Un seul absent notable : Claude Code, qui ne lit pas AGENTS.md nativement (malgré les demandes de la communauté). C’est l’ironie : Anthropic est membre platine de l’AAIF, mais son outil phare ne supporte pas encore le standard qu’elle co-gouverne.

Ce qu’il faut y mettre

L’analyse de 2 500 dépôts par GitHub a identifié les 6 sections qui font la différence :

Commandes — build, test, lint (avec les flags exacts)
Structure du projet — modules principaux, points d’entrée
Style de code — un exemple concret vaut 3 paragraphes de description
Workflow git — branches, conventions de commit, process PR
Stack technique — versions spécifiques, pas juste “projet React”
Limites — ce qu’il ne faut jamais toucher (secrets, configs prod, vendor)

La règle d’or ? Court et précis. OpenAI recommande un maximum de 100 lignes. L’étude d’ETH Zurich confirme : les fichiers trop longs ajoutent du bruit qui rend les tâches plus difficiles pour l’agent. Cinq lignes ciblées battent systématiquement 2 000 mots génériques.

Le match : CLAUDE.md vs AGENTS.md en 2026

Voici la comparaison factuelle :

Critère	CLAUDE.md	AGENTS.md
Outils supportés	Claude Code uniquement	Copilot, Codex, Jules, Cursor, Gemini CLI, Zed, Warp…
Gouvernance	Anthropic	Linux Foundation (AAIF)
Fonctionnalités spécifiques	Skills, hooks, sous-agents, permissions	Standard Markdown, pas de features spéciales
Hiérarchie de fichiers	Oui (racine + sous-dossiers)	Oui (racine + sous-dossiers)
Adoption	~37k stars (best-practice repo)	60 000+ repos
Portabilité	Aucune	Totale
Précision	Maximale (cible un seul outil)	Bonne (dénominateur commun)

Quand utiliser quoi

AGENTS.md seul — tu travailles en équipe avec des outils mixtes (Copilot + Cursor + Claude), ou tu maintiens un projet open source. C’est le bon défaut. Un fichier, tous les agents le lisent.

CLAUDE.md seul — tu es solo, all-in sur Claude Code, et tu exploites les skills, hooks et sous-agents. Pas besoin de portabilité.

Les deux — c’est le setup le plus robuste pour un projet sérieux. AGENTS.md pour les instructions universelles (commandes, stack, limites). CLAUDE.md pour les spécificités Claude (skills à charger, workflows avec sous-agents, imports @ vers d’autres fichiers). La migration est triviale :

# Si tu pars de CLAUDE.md et veux ajouter AGENTS.md
cp CLAUDE.md AGENTS.md  # Copie la base
# Puis édite CLAUDE.md pour ne garder que le spécifique Claude

Ma position

AGENTS.md devrait être le fichier par défaut de tout nouveau repo. C’est le README des agents — universel, léger, suffisant pour 90 % des cas. CLAUDE.md devient un complément pour ceux qui poussent Claude Code dans ses retranchements, pas un remplacement.

La logique est la même que pour les standards web : tu écris du HTML standard, puis tu ajoutes du CSS vendor-prefixed quand tu veux aller plus loin sur un navigateur spécifique. AGENTS.md est le standard. CLAUDE.md est le vendor-prefix.

Starter kit : prépare ton repo en 10 minutes

Template AGENTS.md minimal

# AGENTS.md

## Stack
TypeScript 5.7, Next.js 15, PostgreSQL 16, pnpm

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test -- --watch`
- Lint: `pnpm lint --fix`
- Build: `pnpm build`

## Code style
- ES modules, named exports
- Prefer `async/await` over `.then()`
- Example: see `src/lib/utils.ts` for patterns

## Git
- Branch: `feat/<description>`, `fix/<description>`
- Commits: conventional commits (`feat:`, `fix:`, `docs:`)
- Always run tests before committing

## Boundaries
- NEVER modify `.env*`, `prisma/migrations/`, or `public/`
- NEVER commit secrets or API keys

Template CLAUDE.md complémentaire

# CLAUDE.md

See @AGENTS.md for build commands and conventions.

## Claude-specific
- Use subagents for code review after implementation
- Run /compact after completing each feature
- When debugging, read error logs before exploring code

## Skills
- @.claude/skills/fix-issue/SKILL.md — workflow GitHub issues
- @.claude/skills/deploy/SKILL.md — deployment checklist

Les 3 erreurs qui ruinent un fichier contexte

Le mur de texte. Un fichier de 500 lignes que l’agent ignore à 60 %. Commence avec 20 lignes. Ajoute uniquement ce qui corrige un comportement récurrent.
Le fichier généré et oublié. /init crée un squelette, mais il doit être affiné manuellement. Les fichiers auto-générés dégradent la performance selon ETH Zurich.
Décrire l’évident. Si Claude suit déjà la convention sans qu’on lui dise, la ligne est inutile. Chaque instruction doit corriger un écart, pas confirmer un comportement par défaut.

Questions fréquentes

Est-ce que Claude Code va supporter AGENTS.md ?

C’est probable. Anthropic est membre platine de l’AAIF qui gouverne le standard, et la communauté le demande activement. En attendant, Claude Code lit les fichiers CLAUDE.md à la racine — tu peux y importer ton AGENTS.md avec la syntaxe @AGENTS.md.

Un fichier contexte peut-il remplacer une bonne documentation ?

Non. Les fichiers contexte sont des briefings opérationnels, pas de la documentation. Ils disent à l’agent comment travailler dans le code, pas ce que fait le projet. Un bon README reste indispensable pour les humains — et les agents le lisent aussi quand ils ont besoin de comprendre le “pourquoi”.

Combien de lignes pour un fichier contexte efficace ?

Le moins possible. OpenAI recommande 100 lignes maximum pour AGENTS.md. Anthropic dit que si ton CLAUDE.md est trop long, Claude ignore la moitié. Le sweet spot est entre 20 et 80 lignes — assez pour couvrir les commandes, le style et les limites, pas assez pour noyer l’agent.

Ce qu’il faut retenir :

AGENTS.md est le nouveau standard — gouverné par la Linux Foundation, supporté par 15+ outils, adopté par 60 000 repos. C’est le bon défaut pour tout projet.
CLAUDE.md reste pertinent — mais comme complément spécifique à Claude Code, pas comme fichier unique. Utilise-le pour les skills, hooks et workflows Claude-spécifiques.
Moins, c’est plus — 20 lignes ciblées battent 500 lignes génériques. Chaque ligne doit corriger un comportement réel, pas décrire l’évident. La recherche ETH Zurich le confirme : les fichiers trop longs rendent les agents moins performants.

Si tu veux aller plus loin sur le context engineering et la mémoire des agents, ou comprendre comment MCP connecte tous les agents IA, ces articles complètent parfaitement celui-ci.