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

(vercel.com)

15 points par GN⁺ 2026-01-31 | 4 commentaires | Partager sur WhatsApp

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

4 commentaires

channprj 2026-01-31

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.

En utilisant Context7, ce problème semble être résolu dans une certaine mesure.

https://context7.com

slowandsnow 2026-02-04

C’est parce que context7 est inefficace qu’on utilise les deux méthodes ci-dessus...

channprj 2026-02-05

Je comprends ce que vous voulez dire, mais cela dit, plutôt que de devoir à chaque fois recenser et ajouter un par un dans AGENTS.md ou Skills les liens vers la documentation la plus récente de tous les frameworks/bibliothèques actuellement utilisés, j’ai l’impression qu’utiliser context7 en complément n’est pas un si mauvais choix.

Par ailleurs, ni l’article de GeekNews ni celui de Vercel ne mentionnent context7. Il me semble que vous avez interprété le contenu avec un demi-pas d’avance, donc je me permets de vous répondre.

(Pour information, le fait qu’un Skills ou un AGENTS.md bien rédigé permette d’économiser des tokens est déjà largement connu, et je le sais moi aussi.)

GN⁺ 2026-01-31

Commentaires sur Hacker News

Le modèle n’est pas une AGI. C’est simplement un générateur de texte, entraîné à produire des effets comme l’édition de fichiers ou l’appel d’outils
Le modèle n’utilise pas des compétences parce qu’il les « comprend », mais parce qu’il génère ce texte grâce à l’apprentissage par renforcement (RL) fondé sur des exemples conçus par des humains et des journaux d’utilisation
S’il n’utilise pas toujours les compétences, c’est simplement parce qu’il n’a pas encore assez appris à partir de ce type de cas. Le forcer via le RL pourrait au contraire le rendre plus bête
En ce moment, nous accumulons des journaux d’usage des compétences afin que les futurs modèles apprennent mieux quand il faut les utiliser
AGENTS.md n’est qu’un contexte. Le modèle est entraîné depuis le début à suivre le contexte
- La différence entre AGENTS.md et les compétences relève finalement de la façon dont elles sont injectées dans le contexte
  Le frontmatter des compétences finit lui aussi dans le contexte, donc si AGENTS.md fonctionne mieux, c’est à cause de différences dans la manière d’extraire et d’injecter les informations des compétences
  Certains agents peuvent même utiliser un petit modèle (ex. Haiku) pour décider quelles informations de compétences transmettre à un grand modèle (ex. Sonnet, Opus)
  Au fond, tout se joue sur les informations qui entrent dans le « prompt brut »
- Ce n’est pas de l’AGI. On est en pratique au niveau d’un autocomplétion améliorée
  C’est utile, mais pas parfait. La technologie GPT elle-même semble déjà être entrée dans une phase de stagnation des performances
  Les prochaines améliorations viendront probablement de systèmes auxiliaires comme les compétences. Mais la fonctionnalité de compétences telle qu’elle est implémentée aujourd’hui est moins bonne qu’écrire directement dans AGENTS.md
- J’ai moi aussi fait des expériences similaires. Je teste un système où le prompt système précharge les compétences pertinentes, tandis que le prompt utilisateur les fait appeler quand c’est nécessaire
- Quelqu’un a demandé ce qu’était le RL
- Il y avait aussi un commentaire humoristique comparant « le modèle n’est pas une AGI » à la controverse sur l’appellation GNU/Linux
L’évaluation a montré que dans 56 % des cas, les compétences n’étaient jamais appelées. Autrement dit, la documentation existait mais n’était pas utilisée. D’où la blague : « au moins, il a réussi le test de Turing… »
- Réponse amusante : « l’IA aussi fait du RTFM (ne lit pas le manuel) »
- Ça m’a fait rire aussi, mais plus sérieusement, les humains ne sont pas toujours très fiables non plus
  La différence, c’est que l’IA accepte les corrections sans ego
  On n’est pas encore au niveau d’un développeur senior, mais elle suit mieux les consignes qu’un junior
La découverte clé, c’est que la compression des pointeurs vers la documentation est efficace
C’est difficile à lire pour un humain, mais pour un LLM c’est une structure de référence directe et efficace
À l’avenir, au lieu d’heuristiques comme agents.md/claude.md/skills.md, on pourrait voir se standardiser un format d’index compressé chargé en permanence
Des suites de tests d’API pourraient aussi être réutilisées pour valider les performances de code des LLM
Plus l’adoption des LLM progressera, plus les bibliothèques et les API devront elles aussi évoluer dans ce sens
- Autre leçon : explorer d’abord le projet puis appeler une compétence fonctionne mieux que « utilisez toujours les compétences »
  Dans Antigravity (= basé sur GEMINI.md), on avait demandé de suivre les règles de AGENTS.md, mais elles étaient ignorées
  En revanche, le prompt « vérifie si le projet contient un AGENTS.md » fonctionnait à tous les coups
  C’est un phénomène intriguant, un peu comme à l’époque où « let’s think step by step » déclenchait une chaîne de pensée
- Certains ont réagi en disant qu’il ne s’agissait pas vraiment de « compression », mais plutôt de minify
- D’autres ont estimé que des retours à la ligne auraient été plus lisibles que des pipes
Si on inclut directement AGENTS.md dans le prompt système, il est toujours présent dans le contexte
Mais inclure toutes les compétences à chaque fois serait du gaspillage. Il faut donc une approche qui ne les charge qu’au moment voulu, comme l’advanced tool use d’Anthropic
Au final, c’est une question d’équilibre entre contexte et coût. Si on a de la marge, les compresser dans AGENTS.md peut être efficace
- Les compétences aussi sont en fin de compte déclarées dans le contexte. Les compresser directement dans AGENTS.md semble simplement mieux fonctionner
- Vercel semble avoir confondu compétences et configuration de contexte. Les deux n’ont pas du tout le même objectif, donc il faut utiliser les deux ensemble
- C’est aussi pour cela que l’approche RLM fonctionne bien : elle met uniquement les informations nécessaires dans le contexte et laisse le reste dans l’environnement
  Ce type d’agent à auto-gestion du contexte devrait beaucoup progresser cette année
- En réalité, il faut les deux. Une partie doit être imposée dans le contexte (index/sparknotes), et une autre doit être ajoutée dynamiquement via exploration et recherche
- Un particulier peut se contenter de modifier le prompt système, mais à l’échelle d’une équipe, il faut des compétences pour imposer des standards comme le style de code
  Le taux de respect des compétences par Claude est faible
Je travaille moi aussi dans une zone proche. J’essaie d’évaluer quel impact la structure de scaffolding du projet a sur les résultats de Claude Code / Opencode
Mais la méthode de test de Vercel n’est pas assez claire, ce qui rend les comparaisons difficiles
AGENTS.md n’est pas totalement différent des compétences, c’est plutôt une forme simplifiée de compétence
L’essentiel est la qualité de conception des compétences, c’est-à-dire réduire au minimum le nombre d’étapes que l’IA doit franchir pour trouver la bonne information
Moins il y a d’étapes, moins les erreurs s’accumulent
- Moi aussi, je gère ça en deux catégories
  1. ce qui est injecté de force dans le prompt système via des règles
  2. ce que l’agent explore lorsqu’il en a besoin
    Et pour éviter le gaspillage de tokens, les gros fichiers ne sont ajoutés qu’une seule fois dans le prompt système
Chaque fois qu’un blog compare des techniques de prompt engineering, je me demande toujours si le test a été exécuté une seule fois ou répété plusieurs fois
Les LLM ne produisent pas des résultats stables, même avec la même entrée
- C’est frustrant de voir présenter ces résultats non déterministes comme s’il s’agissait de science
  La plupart du temps, on a l’impression de voir des données anecdotiques emballées comme de la science
- De mon côté, je fais toujours plusieurs exécutions pour calculer des intervalles de confiance
  Mais quand on benchmarke sérieusement, on obtient peu de vues ; quand on fait ça à la va-vite, le trafic du blog est multiplié par 9
  Le problème, c’est une structure d’incitations biaisée
Il existe peut-être une meilleure méthode que AGENTS.md
Créer un dossier .context et y placer, via des liens symboliques, la documentation du projet (README, docs des dépendances, etc.), afin qu’elle soit toujours chargée dans le contexte
Ainsi, le LLM disposerait dès le départ de toutes les informations nécessaires, ce qui permettrait d’améliorer les performances tout en réduisant les coûts
- Mais la documentation des dépendances ne change pas grand-chose. Il est bien plus utile de mettre le code source lui-même dans un dossier _vendor
  Le LLM peut alors analyser directement le code pour comprendre son fonctionnement
- Charger tous les documents à chaque fois reste inefficace. Certains pensent qu’il vaut mieux simplement indiquer leur emplacement dans Claude.md ou Agents.md, puis les lire au besoin
- Il ne faut pas gonfler inutilement le contexte. À la place, n’y mettre qu’un index de documentation compressé est plus efficace
- Ajouter de gros fichiers à chaque fois, c’est du gaspillage de tokens. Le blog de Claude Code mettait en garde contre le même problème
Voici ce que j’ai appris en créant mon agent personnalisé
1. je me suis inspiré des consignes d’extraction de Claude Code
2. je charge automatiquement AGENTS.md pour la table des matières et les résumés (sparknotes)
3. je gère des fichiers Markdown par sujet comme des compétences
4. MCP et les compétences sont conceptuellement proches, donc l’essentiel est de construire de bons outils
5. je continue d’expérimenter, de m’amuser et d’améliorer le système
  Quand j’ai mis read/write_file dans l’état et que je l’ai affiché dans le prompt système, ça a beaucoup mieux marché
  J’essaie maintenant de le démontrer avec des évaluations quantitatives (evals). Empiriquement, les performances semblent très bonnes