AGENTS.md : des consignes utiles pour un agent de code
Neaptide · 6 septembre 2026 · 7 min de lecture · Mis à jour: 3 octobre 2026
Où placer AGENTS.md, quelles consignes y écrire et comment vérifier leur application dans Codex. Avec un exemple et un schéma des dossiers concernés.
Dans cet article
Si l’agent modifie toujours le mauvais dossier ou propose une commande inexistante, mieux vaut enregistrer la règle que la répéter dans chaque conversation. AGENTS.md est un fichier Markdown destiné aux consignes de travail du projet. Il sert surtout à dire ce que le code ne laisse pas deviner facilement.
Répartir les informations
| Support | Contenu |
|---|---|
| README | Installation et compréhension du projet |
| AGENTS.md | Conventions de travail durables |
| Skill (procédure réutilisable) | Procédure de recherche ou de révision |
| Message de la tâche | Demande actuelle et exception éventuelle |
Remplacez « produire du bon code » par une consigne dont on peut vérifier l’application : indiquez le dossier à modifier et le contrôle à exécuter ensuite. Pour les explications déjà disponibles, ajoutez un lien vers la documentation et précisez quand la consulter. Vous n’aurez pas plusieurs copies du même texte à mettre à jour.
Un exemple pour un site éditorial
Les chemins et la commande ci-dessous existent sur notre site. Adaptez-les après vérification dans votre projet. Le téléchargement est un fichier .txt : enregistrez la version adaptée sous le nom AGENTS.md.
# Travailler sur ce projet
- Lire package.json et les fichiers voisins avant de modifier.
- Les articles sont dans content/blog/articles, pas dans les dictionnaires d’interface.
- Conserver le slug publié sauf si la tâche exige un changement d’URL.
- Exécuter npm run build après une modification du contenu.
- Pour une nouvelle logique, exécuter les vérifications pertinentes dans scripts.
- Indiquer les vérifications effectuées et les limites restantes.N’ajoutez pas npm test par habitude si ce script n’existe pas. Choisissez les contrôles utiles à la modification : une légende ne demande pas automatiquement un audit complet.
Comment Codex découvre les fichiers
Au démarrage, Codex lit les consignes globales, puis les fichiers d’instructions situés sur le chemin entre la racine du projet et son dossier de travail actuel. Dans chaque dossier, il cherche AGENTS.override.md avant AGENTS.md et retient au maximum un fichier. Les consignes les plus proches du dossier de travail précisent les précédentes. Les autres agents peuvent fonctionner autrement : consultez leur documentation.
Ajoutez un AGENTS.md dans un sous-dossier si cette partie du projet utilise des commandes ou des conventions particulières. Gardez les règles communes à la racine au lieu de les recopier dans chaque dossier.
Vérifier ce qui est réellement appliqué
- Contrôlez le nom du fichier et le dossier de travail.
- Après une modification, commencez une nouvelle exécution et demandez quels fichiers s’appliquent.
- Faites effectuer une petite modification réelle et inspectez chemins, commandes et résultat.
- En cas d’écart, recherchez un conflit ou un fichier AGENTS.override.md, puis précisez la formulation.
Un agent peut réciter une règle et mal l’appliquer. Son résumé aide au diagnostic, mais seules les actions montrent le résultat. Codex plafonne aussi la taille cumulée des consignes (32 Kio par défaut) : un long fichier ne sera pas forcément chargé en entier.
Ce que le fichier ne remplace pas
Écrire « ne pas lire les clés secrètes » ne limite pas les droits d’accès, pas plus que demander à l’agent de lancer les tests ne met en place des contrôles automatiques. Configurez séparément les permissions, la protection des branches et l’intégration continue (CI). Ne mettez pas de véritables identifiants secrets dans les exemples.
Mettez AGENTS.md à jour avec le projet. Ajoutez une règle pour un problème récurrent, vérifiez son effet et supprimez-la lorsqu’elle devient inutile. Le fichier est là pour réduire les hésitations. L’historique de toutes les erreurs passées n’y a pas sa place.