Agents.md : des instructions pour les agents

Auteur : Rédaction Domeny.ForSale Publié le 27.09.2026

En bref : AGENTS.md est un fichier texte contenant des instructions pour les agents AI qui travaillent sur un projet, le plus souvent sur du code. Il décrit notamment comment lancer les tests, comment le projet est organisé et quelles règles suivre pour apporter des modifications. Il ne lance rien lui-même : son effet dépend de la capacité de l’outil utilisé à lire ce fichier et de la manière dont il interprète les consignes.

À quoi sert le fichier AGENTS.md

Un agent AI est un outil qui ne se contente pas de répondre aux questions : il peut aussi effectuer des tâches, par exemple parcourir des fichiers, modifier du code et exécuter des commandes. Pour cela, il a besoin de connaître le contexte du projet. Sans ces informations, il risque de choisir une méthode inadaptée pour installer les dépendances ou de modifier des fichiers que l’équipe n’édite pas manuellement.

AGENTS.md permet de consigner ce contexte dans le dépôt, c’est-à-dire l’endroit où sont conservés le code et l’historique de ses modifications. Le fichier utilise Markdown, un format texte simple qui prend en charge les titres, les listes et les blocs de code. Il peut être modifié dans un éditeur ordinaire et examiné avec les autres modifications du projet.

Il s’agit d’une convention pour transmettre des instructions, et non d’un programme, d’un modèle AI ou d’un mécanisme d’attribution de permissions. La consigne « ne modifie pas la configuration de production » guide l’agent, mais ne bloque pas techniquement l’accès à cette configuration.

AGENTS.md et README : deux rôles distincts

README.md présente généralement le projet à un lecteur humain : il explique son objectif, son installation et son utilisation de base. AGENTS.md précise plutôt comment l’agent doit travailler dans le dépôt concerné. Les deux fichiers peuvent se compléter au lieu de répéter la même documentation.

Par exemple, le README d’une bibliothèque peut montrer comment l’utiliser dans sa propre application. Les instructions destinées à l’agent peuvent, quant à elles, préciser qu’une modification de l’interface publique doit être suivie d’une mise à jour des exemples et de l’exécution d’un ensemble de tests donné.

Il ne faut pas non plus confondre AGENTS.md avec llms.txt, un fichier proposé pour mettre à disposition des modèles de langage des informations sur le contenu d’un site. AGENTS.md concerne avant tout le travail sur un projet, et non la présentation du contenu d’un site. Sa présence ne constitue pas une déclaration de visibilité du site dans les moteurs de recherche ou les services AI.

Où placer le fichier et quels outils le lisent

Le fichier se trouve habituellement à la racine du dépôt. Lors de sa création, utilisez le nom AGENTS.md, en majuscules : sur les systèmes sensibles à la casse, Agents.md peut désigner un autre fichier. Ne supposez pas que l’outil reconnaîtra toutes les variantes du nom.

Dans les projets plus importants, on peut trouver des fichiers AGENTS.md supplémentaires dans des sous-répertoires, par exemple un pour l’interface utilisateur et un autre pour la partie serveur. Cela permet de séparer les règles propres aux différentes technologies. La portée des instructions et la manière de résoudre les contradictions dépendent toutefois de l’outil : il ne faut donc pas supposer que tous les agents appliquent la même hiérarchie.

Avant de mettre ce fichier en place, vérifiez dans la documentation officielle de l’agent utilisé :

s’il prend en charge AGENTS.md et si une configuration supplémentaire est nécessaire ;
dans quels répertoires il cherche les instructions ;
s’il lit les fichiers des sous-répertoires ;
comment il combine ces consignes avec la demande de l’utilisateur et les autres instructions.

Le simple ajout du fichier au dépôt ne signifie pas que toutes les fonctions AI de l’éditeur commenceront à l’utiliser.

Que mettre dans les instructions destinées à l’agent

Les informations les plus utiles sont celles qui évitent à l’agent de deviner : les commandes réellement utilisées, l’emplacement des fichiers importants et les limites de la modification demandée. Une recommandation générale comme « écris du bon code » ne lui indique pas comment vérifier le résultat.

Voici à quoi pourrait ressembler un fichier pour un projet JavaScript utilisant npm. Ces commandes ne sont pertinentes que si elles correspondent à la configuration du dépôt :

## Travail sur le projet

## Exécution et vérification
- Installe les dépendances avec la commande `npm ci`.
- Lance les tests avec la commande `npm test`.
- Vérifie le respect des règles de code avec la commande `npm run lint`.
- Si tu ne peux pas effectuer une vérification, indique pourquoi.

## Organisation des fichiers
- Le code de l’application se trouve dans `src/`.
- Ne modifie pas manuellement le répertoire `generated/`.

## Périmètre des modifications
- N’ajoute pas de dépendances sans confirmation de l’utilisateur.
- Lorsque tu corriges un bug, ajoute un test qui le reproduit.
- Ne combine pas la correction avec un nettoyage du code sans rapport avec le bug.

Dans un projet comportant plusieurs applications, précisez le répertoire depuis lequel chaque commande doit être exécutée. Si les tests nécessitent un service supplémentaire, décrivez ce prérequis et la manière de préparer l’environnement en toute sécurité. Ne mettez aucun mot de passe, jeton ou autre secret dans les instructions.

Comment vérifier l’efficacité du fichier et le tenir à jour

Une petite tâche constitue un bon test, par exemple corriger la validation d’un seul champ de formulaire. Observez si l’agent utilise les bonnes commandes, évite les fichiers générés automatiquement et signale les tests qu’il n’a pas exécutés. Si l’outil affiche les instructions chargées, vérifiez également cette information.

Lorsque l’agent commet une erreur, déterminez d’abord s’il a lu le fichier. Ajouter des interdictions ne servira à rien si le problème vient d’une absence de prise en charge ou d’un mauvais emplacement. Si l’instruction a bien été lue, remplacez la formulation ambiguë par une action ou une condition précise.

Traitez AGENTS.md comme une partie de la documentation à maintenir : mettez-le à jour lorsque les commandes, la structure des répertoires ou le processus de test changent. Faites respecter les restrictions d’accès par les permissions et la configuration de l’environnement, et non par de simples phrases dans le fichier. Pour commencer, consignez les commandes de vérification qui fonctionnent et les principales restrictions, puis mettez ces consignes à l’épreuve sur une petite tâche.

Voir aussi : Qu’est-ce que GitHub ?