Comment écrire un AGENTS.md qui aide vraiment votre agent de codage IA

Si vous avez utilisé un agent de codage IA sur un vrai projet, vous avez probablement vécu le moment où il exécute la mauvaise commande de test, ignore votre formateur, ou réinvente un utilitaire que vous avez déjà. La solution n'est généralement pas un modèle plus intelligent — c'est de donner à l'agent le contexte spécifique au projet qu'il ne peut pas déduire. C'est à cela que sert un fichier AGENTS.md.

Ce qu'est AGENTS.md

AGENTS.md est un format Markdown simple et ouvert qui donne aux agents de codage un endroit prévisible où trouver le contexte et les instructions du projet. Il est né d'une collaboration entre OpenAI Codex, Amp, Google Jules, Cursor et Factory, et est désormais administré par l'Agentic AI Foundation sous l'égide de la Linux Foundation. Plus de 25 outils le lisent — dont Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed et goose — et il apparaît dans plus de 60 000 dépôts open source.

Voyez-le comme un README rédigé pour l'agent au lieu d'un humain : le README explique votre projet à un nouveau contributeur ; AGENTS.md indique à l'agent les choses qu'il devinerait sinon de travers. (Les utilisateurs de Claude Code reconnaîtront CLAUDE.md comme l'équivalent ; beaucoup d'équipes gardent les deux, ou créent un lien symbolique de l'un vers l'autre.)

Où il se place

Placez AGENTS.md à la racine du dépôt. Dans un monorepo, ajoutez des fichiers imbriqués dans chaque paquet — les agents lisent le fichier le plus proche dans l'arborescence, donc un packages/api/AGENTS.md prime sur celui de la racine lorsque l'agent travaille dans ce dossier. Cela permet à un service Python et à un frontend TypeScript d'obtenir chacun des instructions sur mesure.

Ce qu'il faut y mettre

Le format n'est que du Markdown — utilisez les titres que vous voulez. Les sections couramment utiles incluent :

• Commandes de build et de test — les commandes exactes, pas des approximations
• Style de code — formateur, linter, et toute convention qu'un linter n'attrapera pas
• Instructions de test — comment exécuter un seul test, ce qui doit passer avant qu'un changement soit terminé
• Considérations de sécurité — fichiers ou opérations à ne jamais toucher
• Conventions de commit / PR — format des messages, nommage des branches
• Étapes de déploiement — seulement si l'agent est censé y toucher

Voici un exemple minimal et à fort signal :

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Remarquez ce qui n'y est pas : pas de cours sur l'architecture, pas de redite de la structure des dossiers, pas de « ceci est une application web moderne construite selon les meilleures pratiques ». C'est délibéré.

Plus court vaut généralement mieux

Il y a la tentation de demander à l'agent de vous générer un AGENTS.md géant. Résistez-y. Une étude de l'ETH Zurich de 2026, rapportée par InfoQ, a mesuré l'impact réel de ces fichiers et a constaté que l'effet est marginal et mitigé. Les fichiers de contexte générés par LLM ont en réalité réduit les taux de réussite des tâches d'environ 3 % en moyenne tout en augmentant les coûts d'inférence de plus de 20 %. Les fichiers rédigés par des humains ont aidé modestement — un gain d'environ 4 % de réussite — mais ont tout de même poussé les agents à effectuer plus d'étapes, augmentant le coût jusqu'à ~19 %.

Le mécanisme est instructif : les agents suivent docilement ce que dit le fichier, donc un document tentaculaire leur dit d'exécuter des tests supplémentaires, de lire plus de fichiers et d'effectuer des contrôles qualité qui n'étaient pas nécessaires pour la tâche en cours. La recommandation des chercheurs : sautez entièrement les fichiers de contexte auto-générés, et limitez les instructions rédigées par des humains aux détails non déductibles — l'outillage spécifique et les commandes personnalisées que l'agent ne peut véritablement pas découvrir tout seul.

Autrement dit, chaque ligne devrait gagner sa place en empêchant une erreur concrète que vous avez réellement vu l'agent commettre.

Un workflow qui fonctionne

1. Commencez vide. N'écrivez pas AGENTS.md avant d'avoir vu l'agent se tromper sur quelque chose.
2. Ajoutez la correction, pas la théorie. Quand il exécute la mauvaise commande de test, ajoutez la bonne. Quand il reformate un fichier à sa manière et que le linter se plaint, ajoutez la règle.
3. Gardez-le concis. Si une ligne ne fait que redire ce que l'agent pourrait lire dans package.json ou les noms de dossiers, supprimez-la.
4. Utilisez l'imbrication pour les monorepos pour que le fichier de chaque paquet reste petit.
5. Relisez-le chaque mois. Des instructions périmées sont pires que pas d'instructions du tout — un agent qui suit une commande de build obsolète échoue avec assurance.

Les meilleurs fichiers AGENTS.md se lisent comme une antisèche d'intégration concise pour le seul coéquipier qui n'oublie jamais mais ne déduit jamais non plus. Notez les choses qu'il ne peut pas deviner, et rien d'autre.