Comment rédiger un fichier AGENTS.md pour que n'importe quel agent de codage IA comprenne votre projet

Si vous avez déjà vu un agent de codage IA exécuter la mauvaise commande de test, formater le code dans un style que votre projet interdit, ou réinventer un utilitaire qui existait déjà, la solution n'est généralement pas un modèle plus intelligent — c'est du contexte. AGENTS.md est la manière standard de fournir ce contexte aux agents, et cela fonctionne avec presque tous les outils.

Ce qu'est réellement AGENTS.md

AGENTS.md est « un README pour agents » : un simple fichier Markdown que vous déposez à la racine de votre dépôt pour indiquer aux outils de codage IA comment fonctionne votre projet (agents.md). Ce n'est pas un nouveau langage de configuration — il n'y a aucun champ obligatoire et aucune syntaxe particulière. Utilisez les titres Markdown que vous voulez.

Le format compte parce qu'il est réellement compatible entre outils. À la mi-2026, il est lu nativement par OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie, et des dizaines d'autres — plus de 28 outils et plus de 60 000 dépôts open source (agents.md ; Codersera). Il est désormais géré par l'Agentic AI Foundation de la Linux Foundation, aux côtés du Model Context Protocol d'Anthropic. Claude Code lit lui aussi AGENTS.md, même si son format natif plus riche reste CLAUDE.md (DeployHQ).

Un seul fichier, et la plupart de vos outils se comportent de manière cohérente.

Pourquoi un fichier vaut mieux que de vous répéter dans le chat

Lorsque vous collez des instructions dans un message de chat, elles ne vivent que le temps d'une seule conversation. La session suivante — ou le prochain coéquipier, ou un agent cloud qui exécute votre tâche pendant la nuit — repart de zéro. Un AGENTS.md est chargé automatiquement au début de chaque exécution, de sorte que vos conventions sont appliquées par défaut au lieu de dépendre du fait que vous ayez pensé à les mentionner. C'est tout l'intérêt : sortir la connaissance du projet de votre tête et des chats jetables, pour la mettre dans un fichier que les outils lisent à chaque fois.

Quoi y mettre

Pensez à ce dont un nouveau coéquipier compétent aurait besoin dès le premier jour — c'est exactement ce dont un agent a besoin. Les sections les plus utiles sont :

• Vue d'ensemble du projet — un paragraphe sur ce que c'est et la pile technique.
• Commandes d'installation et de build — les commandes exactes pour installer, lancer et construire.
• Tests — comment exécuter les tests, et la règle selon laquelle les tests doivent passer avant qu'un changement soit considéré comme terminé.
• Style de code — formateur, linter, conventions de nommage, motifs à privilégier ou à éviter.
• Consignes pour les commits et les PR — format des messages, règles de branches, ce qu'il ne faut pas toucher.
• Pièges — tout ce qui n'est pas évident et fait trébucher les gens.

Soyez concret. « Écrire du code propre » ne dit rien à un agent. « Utilise pnpm, pas npm ; lance pnpm test avant de terminer ; ne modifie jamais les fichiers dans src/generated/ » est applicable.

Un exemple concret

Voici un AGENTS.md compact pour une application web typique :

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Donnez-le à Claude Code, Cursor ou Copilot et chacun reprendra les mêmes règles.

Monorepos : utilisez des fichiers imbriqués

Dans un monorepo, vous pouvez placer un AGENTS.md dans chaque paquet ainsi qu'un à la racine. Lorsqu'un agent travaille dans un sous-répertoire, le fichier le plus proche l'emporte (agents.md). Gardez les conventions partagées à la racine et les commandes propres à chaque paquet dans les fichiers imbriqués, afin qu'un agent qui modifie packages/api/ récupère automatiquement les commandes de build et de test de ce paquet.

AGENTS.md vs CLAUDE.md vs règles Cursor

Vous avez peut-être déjà des fichiers propres à certains outils comme CLAUDE.md ou .cursor/rules. Vous n'avez pas à les jeter. En pratique, les équipes mettent les conventions partagées et indépendantes de l'outil dans AGENTS.md — ce dont chaque agent a besoin — et conservent les compléments spécifiques dans le fichier natif de l'outil qui prend en charge des fonctionnalités plus riches (DeployHQ). Claude Code, par exemple, lit les deux, avec CLAUDE.md comme format plus expressif. Un motif courant consiste à conserver un AGENTS.md canonique unique et, là où un outil a besoin de son propre fichier, à faire pointer ce fichier vers AGENTS.md pour qu'il y ait une seule source de vérité. Commencez par AGENTS.md ; ne recourez au fichier spécifique à l'outil que lorsque vous avez besoin d'une fonctionnalité qu'il est le seul à prendre en charge.

Restez court et précis

Plus n'est pas mieux. Un AGENTS.md gigantesque qui reprend l'intégralité de votre guide de style entre en concurrence pour l'attention du modèle et enterre les règles qui comptent vraiment. Visez la poignée de choses qu'un agent se trompera sans indication — la commande non évidente, le répertoire à ne pas toucher, le motif que votre base de code privilégie. Si une règle est déjà évidente à la lecture du code, vous n'avez probablement pas besoin de l'écrire.

Comment le garder utile

Un AGENTS.md ne justifie sa place que s'il reste vrai. Traitez-le comme du code : lorsqu'une commande ou une convention change, mettez le fichier à jour dans le même commit. Et quand un agent commet deux fois la même erreur, ne vous contentez pas de le corriger dans le chat — écrivez la règle. Cette seule habitude transforme chaque faux pas en correction permanente, et c'est la chose la plus rentable que vous puissiez faire pour rendre les agents IA fiables sur votre projet.