Le manuel contre le règlement : un malentendu coûteux
Le fait que de nombreuses équipes comprennent mal le rôle d'un fichier AGENTS.md crée un angle mort opérationnel coûteux. Des recherches récentes menées par des ingénieurs de Coldtea révèlent une réalité frappante : seuls 27 % des 1 000 principaux dépôts GitHub possèdent un fichier AGENTS.md, et une grande majorité d'entre eux sont utilisés de manière incorrecte. Cette négligence généralisée laisse un vide critique dans la gestion des contributions de l'IA.
Le problème fondamental réside dans la confusion entre un manuel d'utilisation et un 'règlement'. La plupart des fichiers AGENTS.md existants fonctionnent comme des manuels, se concentrant sur la description de l'architecture du projet ou sur l'énumération de commandes exactes pour la construction et les tests. Ils indiquent à l'IA comment fonctionner, mais, point crucial, ils ne parviennent pas à limiter ce qu'elle doit et ne doit pas faire.
Un véritable AGENTS.md agit comme un règlement, établissant des garde-fous stricts et des contraintes négatives explicites pour les agents IA. Sans ce règlement, les agents opèrent sans limites, ce qui conduit à des contributions incohérentes, à des comportements inattendus et à l'introduction de bugs potentiels. Les dépôts plus importants, par exemple, consacrent presque deux fois plus d'espace aux règles d'interdiction (« ne pas »), un signe clair de leur compréhension de cette nécessité. L'absence de directives claires de type « doit », « toujours » et « jamais » transforme un outil potentiellement puissant en une responsabilité imprévisible.
Le pouvoir du « ne pas » : leçons de Vercel et Bun
Les recherches de Coldtea révèlent un modèle critique parmi les principaux dépôts : les fichiers AGENTS.md les plus efficaces privilégient les contraintes négatives explicites. Les 100 meilleurs dépôts consacrent près de deux fois plus d'espace aux règles sur ce qu'il ne faut pas faire, par rapport aux projets plus petits, avec 784 occurrences de phrases impliquant un « ne pas ».
Un nombre impressionnant de 90 % de ces fichiers très performants utilisent des termes définitifs tels que « doit », « toujours » ou « jamais » pour guider les agents IA. Ce n'est pas accidentel ; c'est une stratégie délibérée pour éviter les actions involontaires et maintenir l'intégrité du code, une marque de fabrique des systèmes robustes.
Des exemples spécifiques soulignent cette précision. Le dépôt Next.js de Vercel, par exemple, interdit explicitement les pieds de page « généré avec Claude code » dans les commits. Ce niveau de détail garantit que les contributions de l'IA s'alignent parfaitement sur les normes du projet et les attentes humaines.
Le dépôt de Bun offre une autre illustration puissante avec son avertissement en majuscules : 'NEVER run bun test directly - it won't include your changes.' (NE JAMAIS exécuter bun test directement - cela n'inclura pas vos modifications). De telles interdictions directes lèvent toute ambiguïté, empêchant les agents d'exécuter des commandes préjudiciables qui pourraient compromettre l'environnement de construction ou de test.
Des limites explicites sont essentielles car les agents IA opèrent sans contexte humain ni intuition. Ils manquent de compréhension implicite de l'historique du projet, des normes d'équipe ou des effets secondaires potentiels. Par conséquent, vous devez leur dire précisément quels fichiers, fonctions ou modèles éviter méticuleusement, en agissant comme un garde-fou numérique. Cette approche proactive prévient les erreurs subtiles et protège la base de code.
De 33 à 14 000 mots : trouver la bonne taille pour votre fichier
La variabilité considérable de la longueur des fichiers AGENTS.md révèle une pratique exemplaire naissante. Considérez les extrêmes : le fichier entier de VS Code ne compte que 33 mots, agissant comme une simple redirection. Celui de Neovim, à peine plus long avec 35 mots, se concentre sur une règle de divulgation unique pour les commits générés par l'IA. Pendant ce temps, le dépôt OpenHands présente un ensemble d'instructions imposant de 14 000 mots. Ce large spectre souligne le défi que représente la définition d'un modèle optimal.
Les recherches de Coldtea offrent toutefois une étoile polaire pratique : une longueur médiane d'environ 1 200 mots. Ce chiffre suggère un juste milieu pragmatique pour la plupart des projets, équilibrant suffisamment de détails pour les contributeurs IA avec la clarté nécessaire à la supervision humaine et à une itération rapide. Il s'agit d'une référence réaliste pour établir des limites efficaces pour les agents sans tomber dans une verbosité excessive.
En fin de compte, la complexité de votre fichier AGENTS.md doit être directement alignée sur l'échelle de votre projet et sur les risques spécifiques que vous cherchez à atténuer grâce à l'assistance de l'IA. Un utilitaire plus petit et ciblé peut nécessiter des garde-fous minimaux, mais un système complexe à contributeurs multiples exige un règlement robuste. Pour des aperçus plus approfondis sur la façon dont les fichiers de contexte aident réellement les agents de codage, explorez des travaux comme Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
Cet article vous plaît ? Recevez-en un comme celui-ci chaque matin.
un e-mail par jour · désinscription en deux clics · aucun traqueur tiers
Votre liste de contrôle en 3 points pour un dépôt à l'épreuve des agents
Après avoir analysé les 1 000 principaux dépôts GitHub, les ingénieurs de Coldtea ont distillé l'essence des fichiers AGENTS.md efficaces en une liste de contrôle cruciale en trois points. Il ne s'agit pas de suggestions ; il s'agit de fournir des commandes précises à vos agents IA, transformant votre fichier en un règlement robuste.
Pour un dépôt à l'épreuve des agents, assurez-vous que votre AGENTS.md inclut :
- Au moins une règle explicite de type 'ne pas faire'. Cette directive critique, présente dans 86 % des fichiers efficaces, établit des limites claires pour le comportement de l'agent. Sans ces contraintes négatives, les agents se basent souvent sur des suppositions, introduisant potentiellement des changements indésirables ou des pieds de page "générés", comme observé avec Next.js de Vercel. Cela inclut de définir clairement ce que l'agent n'est jamais autorisé à toucher.
- Précisez méticuleusement comment les commits et les pull requests doivent être formatés. Présente dans 79 % des fichiers réussis, cette règle garantit que l'historique et les normes du projet restent cohérents, qu'un humain ou un agent IA soumette le code. Un formatage prescriptif empêche le chaos dans le système de contrôle de version.
- Exactement comment exécuter les tests et le lint du code. Environ les trois quarts (75 %) des fichiers efficaces fournissent ces instructions précises. Ce ne sont pas des étapes optionnelles ; ce sont des commandes directes que l'agent doit exécuter, garantissant que chaque contribution respecte les portes de qualité avant l'intégration.
Foire aux questions
Quelle est l'erreur principale que font les projets avec les fichiers AGENTS.md ?
L'erreur la plus courante consiste à traiter AGENTS.md comme un manuel opérationnel (listant des commandes) plutôt que comme un règlement strict qui indique à un agent IA ce qu'il doit faire et, plus important encore, ce qu'il ne doit pas faire.
Quels sont les éléments clés d'un bon fichier AGENTS.md ?
Un fichier efficace inclut des contraintes négatives explicites (règles de type 'ne pas faire'), des instructions claires pour le formatage des commits et des PR, ainsi que des directives précises sur la façon d'exécuter les tests et le lint du code.
Les grands projets ont-ils besoin de fichiers AGENTS.md différents des petits ?
Oui. Les recherches montrent que les projets plus vastes et complexes ont des fichiers AGENTS.md beaucoup plus stricts, consacrant presque deux fois plus d'espace aux contraintes négatives (règles de type 'ne pas faire') pour protéger la base de code.
Quelle est la fréquence des fichiers AGENTS.md dans les principaux dépôts GitHub ?
Ils sont encore relativement rares. Une étude des 1 000 principaux dépôts GitHub a révélé que seuls 27 % possédaient un fichier AGENTS.md, ce qui indique une opportunité majeure d'amélioration dans l'orientation des agents IA.