AGENTS.md : modèle et règles pour rédiger vos instructions

Ressources pratiques sur le vibe coding et le travail avec des agents : documentation Ailoot.

AGENTS.md en un paragraphe#

Le format est présenté ci-dessous à partir de agents.md, de la documentation OpenAI Codex, de JetBrains Junie, de la documentation Cursor Rules, du journal des modifications de GitHub Copilot Coding Agent et du communiqué de presse de la Linux Foundation sur l’Agentic AI Foundation. Tous les chiffres et les fonctionnalités sont à jour au 30 mai 2026. La prise en charge d’AGENTS.md dans Claude Code est décrite selon la documentation d’Anthropic, avec une mise à jour du 24 septembre 2026.

Si vous ne savez pas ce que représente ce zoo d’outils sur le marché ni pourquoi ils ont besoin d’un fichier commun, lisez d’abord le guide « Avec quoi coder en 2026 : 8 outils d’IA, de Claude Code à Antigravity ». Cet article porte précisément sur le format AGENTS.md et sur la manière d’en rédiger un vous-même en 30 minutes.

Qu’est-ce que AGENTS.md et d’où vient-il ?#

Auparavant, chaque outil d’IA avait son propre fichier de règles : Anthropic avait CLAUDE.md, Cursor avait .cursorrules, GitHub avait .github/copilot-instructions.md, Aider avait .aider.conf.yml et JetBrains avait .junie/guidelines.md. Si votre équipe avait trois agents différents, cela signifiait trois fichiers parallèles au contenu identique qui divergeaient en une semaine.

OpenAI a été le premier à s’en lasser. En août 2025, l’entreprise a publié Codex CLI et lancé simultanément agents.md, un format ouvert. Le site indique :

« Considérez AGENTS.md comme un README pour les agents. »

(agents.md, traduit de l’anglais)

L’idée essentielle est qu’AGENTS.md complète README. README s’adresse aux personnes : « ce qu’est le projet, comment le lancer localement, comment y contribuer ». AGENTS.md s’adresse à l’agent : commandes shell exactes, critères vérifiables pour déterminer que le travail est « terminé » et limites telles que « ne touchez jamais à ceci ».

Le site indique :

« AGENTS.md complète README : il contient du contexte supplémentaire, parfois détaillé, dont l’agent a besoin — étapes de build, tests et conventions qui encombreraient README ou ne seraient tout simplement pas nécessaires aux contributeurs humains. »

(agents.md, traduit de l’anglais)

En septembre 2025, GitHub Copilot Coding Agent prenait en charge ce format (journal des modifications, 28.08.2025). En décembre, Cursor, Junie, Gemini CLI, Aider et une douzaine d’autres outils l’avaient rejoint. Le 9 décembre 2025, la Linux Foundation a créé l’Agentic AI Foundation (AAIF) : ses trois projets fondateurs étaient AGENTS.md d’OpenAI, MCP d’Anthropic et goose de Block. Les membres fondateurs étaient AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft et OpenAI. Au 24 février 2026, la fondation comptait déjà 146 organisations, dont Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath et Hitachi.

À partir de là, AGENTS.md a cessé d’être « un truc de plus signé OpenAI » pour devenir un standard de fait.

Quels agents d’IA lisent AGENTS.md, et lesquels ne le font pas ?#

Tableau de compatibilité au 30 mai 2026 ; la ligne Claude Code a été mise à jour le 24 septembre 2026 :

Anthropic a été le dernier des grands acteurs à rejoindre le mouvement. En août 2025, l’issue #6235 demandant la prise en charge d’AGENTS.md a été ouverte dans le dépôt officiel anthropics/claude-code.

L’issue est restée ouverte presque un an et a été fermée le 17 août 2026 ; la version 2.1.277 prenant en charge AGENTS.md est sortie le 18 septembre. La logique d’Anthropic est la suivante : CLAUDE.md a la priorité, et AGENTS.md est lu lorsqu’il n’y a pas de CLAUDE.md dans le dossier de travail ou dans un dossier parent. Selon la documentation, voici comment cela fonctionne :

Le piège : un fichier personnel CLAUDE.local.md compte également, et Claude Code cesse alors de lire AGENTS.md. Vous pouvez modifier ce comportement dans /config, sous Project instructions — par exemple, pour faire lire les deux fichiers à Claude Code. Dans les versions antérieures à 2.1.277, AGENTS.md n’est pas pris en compte automatiquement ; la ligne @AGENTS.md dans CLAUDE.md reste la solution de contournement.

Quelle est la différence entre AGENTS.md, CLAUDE.md et .cursorrules ?#

Comparaison des quatre formats au 30 mai 2026 :

L’idée clé : AGENTS.md peut contenir les instructions partagées du projet, tandis que le chargement et les paramètres personnels restent à configurer séparément dans chaque client. Claude Code dispose de CLAUDE.local.md pour cela, et Cursor propose des fichiers .mdc locaux sous user. AGENTS.md seul ne le permet pas : il faut soit le combiner avec d’autres fichiers, soit convenir en équipe de placer les règles personnelles dans des sections ignorées par Git.

Un autre détail important concerne les monorepos. Codex et Cursor appliquent la règle « le fichier AGENTS.md le plus proche l’emporte » :

« Dans un monorepo, placez un fichier AGENTS.md distinct dans chaque paquet. Les agents lisent automatiquement le fichier le plus proche dans l’arborescence, et c’est celui-là qui l’emporte. »

(agents.md, traduit de l’anglais)

agents.md indique que le monorepo principal d’OpenAI contient 88 fichiers AGENTS.md pour différents sous-paquets. Si vous travaillez dans un monorepo, répartissez les règles par niveau : les règles générales à la racine, les règles spécifiques dans les sous-dossiers.

Que doit contenir un bon AGENTS.md ?#

Le site agents.md propose un format flexible — « n’importe quel Markdown ». Mais 80 % des bons fichiers disponibles contiennent les mêmes huit sections. Règle principale : chaque point doit être une commande précise ou un exemple concret. L’agent ignorera une idée abstraite comme « écrivez du code propre ».

1. Présentation du projet — 2–3 lignes. Quel est le projet, à qui s’adresse-t-il et quel est son objectif principal ? Pas de marketing. Exemple : « Bot Telegram pour l’intégration à un atelier payant. Stack : Next.js 14, Prisma, PostgreSQL. Déclenché par une nouvelle entrée dans purchases. »
2. Commandes d’installation — commandes shell exactes pour travailler en local. npm install, npm run dev, npm run build. Pas de « c’est généralement comme ça qu’on fait ».
3. Style de code / conventions — règles précises accompagnées d’un exemple, pas « écrivez proprement ». Par exemple : « TypeScript strict, guillemets simples, pas d’exports par défaut, noms de composants en PascalCase, hooks commençant par use. »
4. Conseils sur l’environnement de développement — emplacement des éléments importants. Quelles variables sont nécessaires dans .env, où sont stockés les secrets, quels ports sont utilisés et comment travailler avec la DB locale.
5. Instructions de test — comment lancer un test précis et ce qui est considéré comme « vert ». Par exemple : npm test -- --testPathPattern=user-auth ; 100 % de réussite sont attendus.
6. Règles relatives aux PR et aux commits — format des messages de commit, liste de vérification avant PR (tests, linter, documentation) et personnes chargées de l’approbation.
7. Considérations de sécurité — ce qui ne doit jamais se produire. « Ne commitez jamais .env. Les secrets doivent se trouver uniquement dans Vault. N’affichez pas de données personnelles des utilisateurs dans les logs. »
8. Limites / À ne jamais faire — interdictions accompagnées d’une solution de remplacement. « N’utilisez pas git push --force sur main. Pour annuler, utilisez git revert ou git reset sur une branche de fonctionnalité. »

Dans chaque section, appliquez le principe « une commande plutôt qu’une idée ». L’agent ignorera « faites attention aux migrations ». Il suivra « Avant alembic upgrade head, lancez alembic check. Si une erreur est signalée, n’appliquez pas la migration ; demandez-moi quoi faire. »

Modèle AGENTS.md prêt à l’emploi (à copier et adapter)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

En moyenne, le modèle compte 80 à 120 lignes. Si le fichier dépasse 150 lignes, c’est le signe qu’il faut le remanier : déplacer certains éléments dans docs/, ajouter un lien vers un document ou condenser certains points en une ligne. En pratique, les fichiers de 100 à 150 lignes fonctionnent le mieux ; au-delà, les gains de qualité commencent à s’inverser.

Quelles sont les 5 règles qui rendent AGENTS.md vraiment utile ?#

1. Des commandes plutôt que des idées. Un agent ne comprend pas « faites attention aux migrations ». Il suivra alembic check avant alembic upgrade head. Les agents fonctionnent avec des commandes et des conditions, pas avec des états d’esprit. Formulez toutes les règles clés sous la forme « faites X, sinon faites Y ».

2. Des interdictions assorties d’une solution de remplacement. Un simple « ne forcez pas le push » sera discrètement ignoré par l’agent après deux ou trois prompts. L’association « ne faites pas X ; faites plutôt Y » fonctionne. Exemple : « N’utilisez pas git push --force sur main ; si vous devez annuler, utilisez git revert ou ouvrez une nouvelle PR. »

3. Une seule source de vérité. Le fichier AGENTS.md à la racine est la source de vérité pour tout le projet. Dans un monorepo, utilisez des fichiers AGENTS.md imbriqués dans les sous-dossiers, selon la règle « le plus proche l’emporte ». Pas de fichiers parallèles aux instructions contradictoires.

4. Des critères d’achèvement vérifiables. « Les tests doivent réussir » ne sert à rien. Un critère précis est : npm test renvoie le code de sortie 0 et n’affiche pas FAIL sur stdout. « Le code doit être propre » ne sert à rien non plus. Un critère précis est : npm run lint réussit sans avertissement. Un agent ne comprend ce que signifie « terminé » que si vous décrivez explicitement la condition.

5. Un fichier de moins de 150 lignes. Au-delà de 150 lignes, les indicateurs commencent à se dégrader : l’agent consacre davantage de contexte à la lecture et manque des règles importantes. Si tout ne tient pas, déplacez les détails dans docs/architecture.md et créez un lien vers ce fichier dans AGENTS.md, en ne gardant dans ce dernier que les commandes et les limites.

Quelles sont les 10 erreurs qui transforment AGENTS.md en déchet ?#

1. Des règles vagues sans commandes. L’agent ignorera « faites attention aux migrations » : cette phrase ne signifie rien pour lui. Seule une commande précise assortie d’une condition fonctionne : « Lancez alembic check avant alembic upgrade head. En cas d’erreur, n’appliquez pas la migration ; demandez-moi quoi faire. »

2. « Du code propre. » Une formule inutile. Remplacez-la par un modèle précis : « Utilisez des composants fonctionnels avec des hooks. Exemple : function LoginForm() { const [email, setEmail] = useState(''); ... } »

3. Un texte sans structure. Si AGENTS.md compte 300 lignes de texte sans titres, l’agent consacrera 80K tokens de contexte à des passages sans pertinence et manquera l’essentiel. Utilisez des titres H2/H3, des sections courtes et des listes à puces.

4. Un fichier de plus de 150 lignes. Les indicateurs de qualité se dégradent au-delà de ce seuil. Répartissez le contenu entre un fichier principal et des liens vers les détails dans docs/.

5. Plus de 30 interdictions sans solution de remplacement. Si le fichier contient une longue liste de « ne faites pas X, ne faites pas Y » sans expliquer « faites plutôt Z », l’agent avancera à l’aveuglette.

6. Dupliquer README.md. Si vous avez déjà indiqué dans README comment installer et lancer le projet, ne copiez pas ces informations dans AGENTS.md. Faites plutôt référence à README en une ligne et décrivez dans AGENTS.md ce dont l’agent a besoin, mais pas les contributeurs humains.

7. Inscrire des secrets en dur. AGENTS.md peut être public puisqu’il se trouve dans Git. N’y mettez aucune véritable clé API, aucun jeton ni mot de passe. Indiquez uniquement où trouver les secrets : « Voir Vault : secret/staging/db. »

8. Des priorités contradictoires sans ordre explicite. « Avancer vite » + « maintenir une couverture de tests de 90 % » ne permet pas à l’agent de savoir quoi choisir. Indiquez clairement l’ordre de priorité : « Couverture des tests ≥80 % d’abord, puis vitesse. En cas de conflit, les tests sont prioritaires. »

9. Une documentation obsolète. Une description de l’architecture qui parle de REST et de polling alors que le système utilise déjà des WebSockets. L’agent suit les informations obsolètes et casse l’architecture. Règle : mettez à jour AGENTS.md dans la même PR que le code à chaque changement d’architecture.

10. Une architecture excessive pour une tâche simple. Si quelqu’un demande de modifier deux lignes d’une configuration, l’agent ne devrait pas avoir à lire toute la topologie de 14 microservices. Déplacez les détails d’architecture dans docs/architecture.md ; dans AGENTS.md, gardez simplement « si la tâche touche à l’architecture, lisez docs/architecture.md ».

L’étude de GitHub Blog portant sur plus de 2 500 dépôts AGENTS.md formule ainsi sa principale conclusion :

« La plupart des fichiers destinés aux agents échouent parce qu’ils sont trop généraux. “Vous êtes un assistant de programmation serviable” ne fonctionne pas. »

(GitHub Blog, traduit de l’anglais)

Comment gérer AGENTS.md et CLAUDE.md dans un même dépôt ?#

La principale question pratique est de savoir comment utiliser les deux fichiers sans dupliquer leur contenu. Trois scénarios sont possibles :

Scénario 1 : Claude Code uniquement. Gardez CLAUDE.md et utilisez toutes les fonctionnalités de Claude Code : ~/.claude/CLAUDE.md pour les instructions au niveau utilisateur, CLAUDE.md pour le projet, CLAUDE.local.md pour les personnalisations personnelles, @import pour inclure d’autres fichiers et .claude/skills/ pour les skills spécialisés. AGENTS.md n’est pas nécessaire.

Scénario 2 : plusieurs clients de programmation. Conservez les règles partagées dans AGENTS.md, puis connectez et vérifiez chaque client séparément. Gemini CLI permet de configurer le nom du fichier de contexte ; Aider peut charger un fichier dans sa configuration de lecture. Ce sont des chemins explicites, pas une découverte automatique identique.

Dans un dépôt de test sans risque, ouvrez une nouvelle session et ajoutez une consigne inoffensive unique, par exemple « inclure le marqueur instructions-loaded dans la réponse de test ». Consultez l’affichage documenté des fichiers chargés ou les journaux du client, en plus de sa réponse. Recommencez pour chaque client et version réellement utilisés. Une réponse du modèle affirmant avoir lu le fichier ne prouve pas indépendamment ce chargement ; une vérification réussie ne prouve pas la prise en charge par tous les autres outils.

Scénario 3 : une équipe mixte (Claude Code + autres outils). C’est la configuration la plus courante en 2026. La solution consiste à faire d’AGENTS.md le fichier principal. Si vous n’avez aucune règle propre à Claude Code, ne créez pas de CLAUDE.md : depuis la version 2.1.277, Claude Code lit AGENTS.md lorsqu’il n’y a pas de CLAUDE.md dans le projet. Si vous avez de telles règles, faites de CLAUDE.md soit un lien symbolique, soit un court fichier intermédiaire avec un import @AGENTS.md.

Avant tout changement, inspectez et sauvegardez les deux fichiers. S’ils existent tous deux, fusionnez les règles communes compatibles dans AGENTS.md, gardez les règles propres à Claude dans CLAUDE.md et ajoutez @AGENTS.md. Préservez les liens symboliques existants.

Pour un CLAUDE.md ordinaire seulement si AGENTS.md est absent, ce contrôle macOS/Linux refuse d’écraser une cible ou un lien existant :

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP : AGENTS.md existe ; fusionnez les fichiers.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP : inspectez le chemin CLAUDE.md existant.' >&2
fi

Après un renommage réussi, CLAUDE.md est un lien symbolique vers AGENTS.md. Tous les agents qui lisent AGENTS.md voient le même contenu. Claude Code, qui lit CLAUDE.md, voit le même contenu via le lien symbolique.

Sous Windows, la création d’un lien symbolique nécessite le mode développeur (ou des droits d’administrateur), ce qui peut être peu pratique pour toute l’équipe. Une autre solution consiste à créer un court CLAUDE.md qui importe AGENTS.md :

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

Dans Claude Code, cette syntaxe inclut AGENTS.md sur une seule ligne et permet d’ajouter ensuite des règles propres à Claude Code. Si vous souhaitez supprimer AGENTS.md plus tard, il vous suffit de retirer l’import. Cette ligne n’entraîne pas de double lecture : selon la documentation de Claude Code, AGENTS.md n’est pas chargé deux fois, même s’il peut aussi être lu automatiquement.

Arborescence canonique pour une équipe utilisant plusieurs outils en 2026 :

repo-root/
├── AGENTS.md                              # source de vérité, ≤150 lignes
├── CLAUDE.md                              # seulement pour les règles propres à Claude : lien symbolique → AGENTS.md OU @AGENTS.md + compléments
├── .cursor/rules/                         # dérogations ciblées pour Cursor uniquement
├── .github/copilot-instructions.md        # « Voir AGENTS.md », si utilisé
└── docs/architecture.md                   # architecture détaillée référencée dans AGENTS.md

Vous trouverez plus d’informations sur CLAUDE.md dans le guide « Comment bien configurer CLAUDE.md ». Pour en savoir plus sur les raisons pour lesquelles un agent a besoin d’un fichier d’instructions volumineux, lisez « Qu’est-ce que l’ingénierie de contexte ? ».

Qu’est-ce qui a changé en 2026 : pourquoi l’AAIF a-t-elle placé AGENTS.md sous l’égide de la Linux Foundation ?#

La principale actualité politique de mai 2026 dans le domaine du codage assisté par l’IA n’était pas la sortie d’un nouveau modèle, mais la consolidation des formats. Auparavant, chaque fournisseur avait son propre fichier de règles ; c’était pratique pour les fournisseurs, mais pénible pour les équipes qui utilisaient plusieurs outils.

Dans un communiqué de presse daté du 9 décembre 2025, la Linux Foundation a annoncé l’Agentic AI Foundation, qui chapeaute trois formats :

• AGENTS.md d’OpenAI — un format de fichier d’instructions pour les agents
• Model Context Protocol (MCP) d’Anthropic — un protocole permettant de connecter des outils externes aux agents
• goose de Block — un framework d’agent open source

Extrait du communiqué de presse de la Linux Foundation :

« Réunir ces projets sous l’égide de l’AAIF leur permet d’évoluer avec la transparence et la stabilité que seule une gouvernance ouverte peut offrir. »

(Communiqué de presse de la Linux Foundation, 9 décembre 2025, traduit de l’anglais)

Au 24 février 2026, 146 organisations faisaient partie de l’AAIF (97 nouveaux membres en deux mois). Parmi les nouveaux membres Gold figuraient Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express et Autodesk. Anthropic est au niveau Platinum et promeut MCP. OpenAI est au niveau Platinum et promeut AGENTS.md. Block est au niveau Platinum avec goose.

Cela change la façon de présenter AGENTS.md : il est passé de « format OpenAI » à standard du secteur. Au printemps 2026, Claude Code restait encore en retrait, mais en septembre, avec la version 2.1.277, il a appris à lire AGENTS.md de lui-même. CLAUDE.md n’a pas disparu et garde toujours la priorité par défaut s’il se trouve dans le projet.

Un point de départ pratique consiste à placer les règles partagées du projet dans AGENTS.md, puis à configurer l’import, le fichier intermédiaire ou la lecture explicite requis par chaque client utilisé. Pour Claude Code, vérifiez la version installée et la priorité des fichiers d’instructions avant de choisir un import dans CLAUDE.md ou un lien symbolique. Vérifiez le chargement dans chaque client ; aucun pourcentage de couverture n’est établi ici.

Et ensuite ?#

AGENTS.md est le premier élément de base pour « s’accorder avec un agent afin qu’il fonctionne de manière prévisible ». Vient ensuite le deuxième élément : un dossier de connaissances du projet, qui contient le contexte métier, le public, les produits et les prix. Le troisième élément est l’ingénierie de contexte, qui rassemble tout : quels fichiers l’agent voit à chaque étape, comment l’état est conservé entre les sessions et comment passer d’un modèle à un autre.

Ressources pratiques : documentation Ailoot.

Autres ressources et outils : Ailoot.