L'analyse de 1 866 projets GitHub révèle des lacunes dans les instructions pour agents IA

Un projet GitHub populaire sur trois inclut désormais des fichiers d'instructions spécifiques pour les agents de codage IA, le format AGENTS.md s'imposant comme la norme. Une analyse récente de 1 866 dépôts actifs révèle que, bien que l'adoption soit répandue, notamment dans les projets TypeScript, la qualité et l'applicabilité de ces instructions varient considérablement.

Ce qui s'est passé

Des chercheurs ont analysé les dépôts les plus étoilés sur GitHub afin de comprendre comment les équipes encadrent leurs assistants IA. Ils ont examiné 1 866 projets ayant reçu des commits cette année, à la recherche de fichiers tels que AGENTS.md, CLAUDE.md et d'autres conçus pour orienter le comportement des agents. L'étude a constaté que 627 de ces projets, soit 34 %, intègrent au moins un fichier d'instructions de ce type.

Les données montrent une nette préférence pour AGENTS.md, présent dans 78 % des projets disposant d'instructions pour agents. CLAUDE.md est également courant, figurant dans 52 % de ces projets, mais il coexiste généralement avec AGENTS.md plutôt que de le remplacer. Les taux d'adoption diffèrent fortement selon le langage de programmation. Le TypeScript domine avec 73 % des projets incluant des fichiers pour agents, suivi par Go à 58 % et Rust à 52 %. En revanche, les projets Perl en incluent rarement, avec seulement 4 % d'adoption.

L'étude a également mis en évidence des problèmes liés à la longueur des fichiers et à la redondance. La moitié des principaux fichiers d'instructions dépassent 100 lignes, avec une longueur médiane de 106 lignes. Environ 30 projets maintiennent deux manuels de règles distincts, comme un AGENTS.md et un CLAUDE.md contenant des contenus différents, créant ainsi des conflits potentiels pour les agents utilisant différents outils.

Comment cela fonctionne

L'analyse combinait des scripts automatisés avec le jugement humain simulé par un relecteur IA. Un script a d'abord collecté des données sur l'existence des fichiers, leur longueur et leurs titres. Ensuite, un relecteur IA séparé a classifié des échantillons aléatoires de règles pour déterminer s'il s'agissait de véritables instructions et si elles pouvaient être appliquées par du code.

Les chercheurs ont découvert que trois règles sur cinq pouvaient être vérifiées, au moins partiellement, par un script, un linter ou un test. Cependant, moins d'une règle sur vingt nomme explicitement le contrôle qui l'applique. La plupart des règles reposent sur la simple mémorisation de l'instruction par l'agent, ce qui est moins fiable qu'une application automatisée. Par exemple, une règle peut indiquer « Ne pas utiliser de motifs de déstructuration vides », ce qu'un linter pourrait facilement détecter, mais le fichier ne précise pas quelle règle de linter s'applique.

L'étude a également examiné l'emplacement de ces fichiers. Bien que beaucoup se trouvent à la racine du dépôt, 30 % des projets conservent les fichiers d'instructions dans des sous-dossiers. Cela permet aux règles d'être spécifiques à certaines parties de la base de code, évitant aux agents de charger un contexte non pertinent lorsqu'ils travaillent dans d'autres zones.

Détails clés

• Taux d'adoption : 34 % des projets actifs populaires possèdent des fichiers d'instructions pour agents, ce chiffre montant à 73 % pour TypeScript.
• Longueur des fichiers : Le fichier principal médian compte 106 lignes, avec 52 % dépassant 100 lignes.
• Applicabilité : 61 % des règles pourraient être vérifiées partiellement ou totalement par un script, mais seuls 3,7 % nomment le contrôle spécifique.
• Redondance : Environ 30 projets maintiennent des fichiers AGENTS.md et CLAUDE.md distincts et non identiques.
• Obsolescence : Seuls 2 % des fichiers font référence à des chemins ou à des scripts qui n'existent plus.
• Contenu : Le style de code, le comportement de l'agent et la correction spécifique au projet sont les sujets les plus fréquents, tandis que la sécurité et les performances sont rares.

Pourquoi c'est important

Pour les équipes d'ingénierie, ces données mettent en évidence un fossé entre la rédaction des instructions et la garantie de leur respect. Des fichiers d'instructions longs augmentent les coûts en tokens et peuvent diluer la concentration de l'agent. L'étude de l'ETH Zurich citée dans l'article note que, bien que les fichiers rédigés par les développeurs apportent une aide marginale, ils peuvent ajouter jusqu'à 19 % aux coûts des agents. Garder les fichiers courts et renvoyer vers une documentation externe est plus efficace.

Plus important encore, compter sur la mémoire de l'agent pour les règles critiques est risqué. Lorsqu'une règle nomme son mécanisme d'application, tel qu'un linter spécifique ou un contrôle CI, elle crée un filet de sécurité. Si l'agent oublie, l'outil détecte l'erreur. Sans ce lien, les équipes dépendent de la cohérence de l'agent, laquelle se dégrade à mesure que les fenêtres de contexte se remplissent. La prévalence des règles non appliquées suggère que de nombreuses équipes traitent ces fichiers comme des listes de souhaits plutôt que comme des contraintes opérationnelles.

Ce que vous pouvez faire

• Auditer la longueur des fichiers : Gardez votre AGENTS.md principal sous 100 lignes en déplaçant les explications détaillées vers une documentation liée.
• Nommer vos contrôles : Pour chaque règle, spécifiez le linter, le test ou le script qui l'applique, par exemple « Appliqué par Sorbet/ForbidTMust ».
• Vérifier les chemins : Contrôlez régulièrement que toutes les commandes et tous les chemins de fichiers référencés dans vos instructions existent toujours.
• Consolider les fichiers : Si vous utilisez plusieurs fichiers d'instructions, assurez-vous que les fichiers secondaires pointent vers le fichier principal pour éviter les règles conflictuelles.
• Prioriser les règles applicables : Concentrez-vous sur les règles pouvant être automatisées et supprimez celles qui reposent uniquement sur la mémoire de l'agent, sauf si elles sont critiques.
• Utiliser des règles par sous-dossier : Placez des instructions spécifiques dans des sous-répertoires pour maintenir un contexte pertinent à la zone concernée.