AGENTS.md surpasse les skills dans les évaluations d’agents

• Dans une évaluation portant sur l’API de Next.js 16, l’index de documentation AGENTS.md inclus à la racine du projet a obtenu une précision supérieure à l’approche fondée sur les skills
• Les skills prennent la forme de packages de connaissances métier invoqués par l’agent en cas de besoin, mais comme leur appel est instable, le taux de réussite n’atteint que 53 % dans la configuration par défaut
• À l’inverse, l’index AGENTS.md compressé à 8 KB a atteint un taux de réussite de 100 % sur tous les tests (Build, Lint, Test)
• Cette méthode montre des résultats plus stables que l’invocation proactive grâce à la suppression des points de décision, à la disponibilité permanente et à l’élimination des problèmes d’ordre
• Les mainteneurs de frameworks peuvent inclure dans AGENTS.md un index de documentation aligné sur la version afin d’améliorer la précision de génération de code

---

Contexte du problème

• Les agents de codage IA ont une limite : leurs données d’entraînement reposent sur d’anciennes versions d’API, ce qui les empêche de gérer correctement les frameworks récents
  • Dans Next.js 16, 'use cache', connection(), forbidden() et d’autres éléments n’existent pas dans les données d’entraînement des modèles actuels
• À l’inverse, sur des projets basés sur d’anciennes versions, les modèles ont aussi tendance à proposer des API récentes qui n’existent pas
• Pour résoudre ce problème, une approche d’accès à une documentation alignée sur la version a été testée

Deux approches

• Skills : un package standard ouvert regroupant prompt, outils et documentation, que l’agent invoque et utilise si nécessaire
• AGENTS.md : un fichier de contexte persistant situé à la racine du projet, toujours consultable à chaque tour de conversation
• Les deux méthodes ont été comparées à partir de la même documentation Next.js

Limites de l’approche par skills

• Résultat de l’évaluation : dans 56 % des tests, le skill n’a pas été invoqué, et le taux de réussite par défaut est resté à 53 %, sans amélioration
• Sur certains points, les scores ont même été inférieurs à la baseline (par ex. test 58 % contre 63 %)
• Cela met en évidence la limite actuelle des modèles, qui n’utilisent pas les outils de manière suffisamment fiable

Expérience avec ajout d’instructions explicites

• Lorsqu’une instruction explicite a été ajoutée dans AGENTS.md — « invoquer le skill avant d’écrire du code » — le taux de réussite est monté à 79 %
• Cependant, de petites différences dans la formulation ont eu un fort impact sur les résultats
  • « Invoquer d’abord le skill » → fixation sur le schéma de la documentation, avec perte du contexte du projet
  • « Explorer le projet puis invoquer le skill » → meilleurs résultats
• En raison de cette fragilité linguistique, la fiabilité en usage réel reste faible

Construire une évaluation fiable

• Les premiers tests manquaient de fiabilité à cause de prompts ambigus et de problèmes de validation redondante
• Ils ont ensuite été renforcés avec une validation fondée sur le comportement et des tests centrés sur des API de Next.js 16 absentes des données d’entraînement
• Principales API testées : connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() entre autres

Expérience avec l’approche AGENTS.md

• Le processus de choix de l’agent a été supprimé, et l’index de documentation a été directement inséré dans AGENTS.md
• L’index ne contient pas la documentation complète, mais une liste des chemins de documentation par version
• Instruction supplémentaire :
  IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
  • Elle vise à amener le modèle à privilégier un raisonnement fondé sur la documentation plutôt que sur ses données d’entraînement existantes

Résultats de l’évaluation

• L’insertion de l’index dans AGENTS.md a permis d’atteindre 100 % de réussite
  • Build, Lint et Test ont tous donné des résultats parfaits
• Statistiques comparatives :
  • Baseline 53 %, Skill par défaut 53 %, Skill + instruction 79 %, AGENTS.md 100 %
• Pourquoi l’approche par contexte passif surpasse l’invocation active
  1. Aucun point de décision — l’information est toujours présente
  2. Disponibilité constante — incluse dans le prompt système à chaque tour
  3. Suppression des problèmes d’ordre — pas de dépendance à la séquence d’exploration de la documentation

Résoudre le problème de capacité de contexte

• L’index initial faisait 40 KB, mais il a été réduit à 8 KB grâce à une compression (baisse de 80 %)
• Une structure délimitée par des barres verticales (|) permet de stocker les chemins et noms de fichiers de documentation dans un espace minimal
• L’agent lit uniquement les fichiers nécessaires dans le répertoire .next-docs/ afin d’utiliser des informations précises correspondant à la bonne version

Comment l’appliquer

• La configuration peut se faire avec une seule commande

  npx @next/codemod@canary agents-md
  

• Cette commande :
  1. détecte la version de Next.js
  2. télécharge la documentation correspondante dans .next-docs/
  3. insère l’index compressé dans AGENTS.md
• Cela fonctionne de la même manière dans les agents qui reconnaissent AGENTS.md, comme Cursor

Ce que cela implique pour les développeurs de frameworks

• Les skills restent utiles, mais pour améliorer la précision générale de génération de code, l’approche AGENTS.md est plus efficace
• Les skills conviennent mieux à des workflows centrés sur des tâches spécifiques, comme une « mise à niveau de version » ou une « migration App Router »
• Recommandations :
  • ne pas attendre l’amélioration des skills et utiliser AGENTS.md dès maintenant
  • n’inclure que l’index de documentation afin de minimiser le contexte
  • valider avec des évaluations centrées sur des API absentes des données d’entraînement
  • concevoir la documentation avec une structure de recherche fine
• L’objectif est de passer d’un raisonnement centré sur le pré-entraînement à un raisonnement fondé sur la recherche, et AGENTS.md apparaît comme la méthode la plus stable pour y parvenir