Le document AGENTS.md de Vercel enseigne aux assistants IA 70 meilleures pratiques React
Un aperçu pratique de l’agent Vercel react-best-practices, montrant comment il intègre 70 règles React éprouvées en production directement dans le code généré par l’IA.
vercel-labs/agent-skills, plus précisément à la compétence react-best-practices. On s’attendait à un autre article type « conseils de performance pour React » réédité sous un angle adapté à l’ère de l’IA. Ce n’était pas le cas. Il s’agit plutôt d’un recueil de 70 règles réparties en 8 catégories, que Vercel décrit comme le fruit de plus d’une décennie d’observation des applications React et Next.js en production, qui tombent systématiquement dans des pannes similaires. Essentiellement, il est conçu pour être utilisé en premier par un assistant de codage basé sur l’IA, et uniquement ensuite par un développeur humain.
Cette structure constitue véritablement l’essentiel de ce qui rend cet élément notable, et il convient de s’y attarder avant d’aborder le contenu réel des règles.
Qu’y a-t-il vraiment dans le dépôt ?
L’installation de cette compétence ne nécessite qu’une seule commande :
npx skills add vercel-labs/agent-skills
En arrière-plan, cela se compile en un fichier AGENTS.md — une convention qui gagne en popularité pour fournir un contexte de projet structuré aux agents de codage (des outils tels que Claude Code, Cursor, Codex et OpenCode recherchent tous ce fichier). Une fois en place, votre agent dispose d’un manuel de règles qu’il peut consulter lors de l’écriture ou de la révision de code, au lieu de se fier uniquement aux divers tutoriels React qui ont été extraits de ses données d’entraînement.
Les 70 règles sont réparties en huit catégories, chacune portant une étiquette de priorité allant de CRITICAL à LOW. Les deux catégories marquées CRITICAL sont, comme on pouvait s’y attendre, celles que l’équipe de Vercel identifie comme les principales causes de problèmes en environnement réel : les opérations asynchrones séquentielles qui créent des effets en cascade, ainsi que l’augmentation non contrôlée de la taille des bundles. Une règle typique de la catégorie des effets en cascade exprime cette idée de la manière suivante :
// Flagged: sequential awaits create a waterfall
async function getThreadPage(threadId) {
const thread = await getThread(threadId)
const author = await getAuthor(thread.authorId)
const replies = await getReplies(threadId)
return { thread, author, replies }
}
// Preferred: parallelize independent fetches
async function getThreadPage(threadId) {
const [thread, replies] = await Promise.all([
getThread(threadId),
getReplies(threadId),
])
const author = await getAuthor(thread.authorId)
return { thread, author, replies }
}
Rien de tout cela n’est révolutionnaire si vous avez déjà passé du temps à développer avec React. Ce qui est vraiment intéressant, ce n’est pas le contenu de la règle elle-même — c’est le fait que cette règle existe désormais sous une forme que des machines peuvent parser et appliquer de manière uniforme dans l’ensemble d’un codebase, même à 2 heures du matin, sur une demande de fusion que personne n’a examinée attentivement, sans la fatigue ni les raccourcis qui apparaissent lorsque la date limite approche.
Pourquoi c’est différent d’un linter
La réaction immédiate est de se demander s’il ne s’agit pas simplement d’ESLint sous une autre apparence. D’une certaine manière, oui — mais c’est le mécanisme qui le distingue. Un linter signale un problème une fois que le code existe déjà. Cette approche vise à influencer le code pendant qu’il est encore généré, en détectant les erreurs avant même qu’elles ne soient tapées. Si un assistant IA est responsable de 30 à 60 pour cent du diff d’une demande de fusion donnée (et les estimations varient beaucoup en fonction de la personne interrogée au sein de l’équipe), intégrer les règles directement dans le processus de génération représente un type d’influence fondamentalement différent par rapport à la détection des erreurs a posteriori.
Il existe également une catégorie de directives que les outils de vérification ne sont tout simplement pas adaptés à exprimer : les jugements architecturaux. Une règle comme « éviter de créer une architecture en cascade » est au moins partiellement quelque chose que ces outils pourraient approximer avec une configuration personnalisée suffisante et une tolérance aux faux positifs. Mais des indications telles que « ce composant devrait probablement devenir un composant serveur, car il ne présente aucun comportement interactif et les limites définies autour de lui semblent arbitraires » exigent une réflexion réelle sur l’intention et la structure — précisément le type de décision pour laquelle on souhaiterait que quelqu’un intervienne, plutôt que quelque chose imposé par une simple correspondance de motifs.
Où le scepticisme s’insinue
Vaut la peine de mentionner directement les aspects gênants. Un ensemble de règles élaboré par la même entreprise qui développe le framework, et dont la plateforme d’hébergement récompense par hasard certains schémas de performance, n’est pas par défaut un document neutre. Certaines des directives de niveau CRITICAL concernant la taille des bundles coïncident un peu trop parfaitement avec les schémas qui permettent également aux tableaux de bord analytiques et à la configuration de cache edge de Vercel d’afficher de bons résultats. Cette superposition ne rend pas automatiquement ces conseils mauvais. Éviter les cascades asynchrones constitue une bonne pratique d’ingénierie, quel que soit l’hébergeur de votre application. Néanmoins, il est juste de garder à l’esprit que les « meilleures pratiques » sélectionnées par le fournisseur ne sont jamais purement techniques — il y a toujours une légère touche marketing intégrée aux côtés des conseils techniques.
La deuxième préoccupation est plus structurelle : que se passe-t-il lorsque 70 règles deviennent 200, ou lorsque des compétences provenant de fournisseurs concurrents commencent à figurer dans le même fichier AGENTS.md et à s’contraster les unes avec les autres ? Pour l’instant, avec un seul répertoire et un concept entièrement nouveau, tout semble ordonné et facile à comprendre. Cependant, dix-huit mois plus tard, il est aisé d’imaginer que chaque framework, chaque fournisseur d’hébergement et chaque système de conception voudra avoir ses propres compétences installées. À ce stade, votre agent pourrait devoir gérer une pile de manuels de règles contenant des directives contradictoires, sans moyen évident de déterminer laquelle doit prévaloir.
L’essai sur une base de code réelle
Par curiosité plutôt que par attente, cette compétence a été testée sur un tableau de bord interne de taille moyenne pour voir ce qu’elle révélerait réellement. Les constats de type CRITICAL et HIGH se sont avérés plutôt banals : quelques appels séquentiels à await qui auraient pu être exécutés en parallèle, un couple de composants clients qui n’avaient aucune raison réelle d’en être, ainsi qu’un cas légèrement embarrassant où toute une bibliothèque de gestion des dates avait été intégrée simplement pour formater une seule valeur. Rien de tout cela ne surprendrait quelqu’un qui a déjà effectué un audit approfondi des performances dans une base de code React. Ce qui a vraiment marqué, c’était la vitesse : l’agent a nécessité environ quatre minutes pour localiser et signaler tout cela, comparé au temps qu’un auditeur humain mettrait pour repérer les mêmes problèmes disséminés dans une grande demande de fusion.
Cette différence de vitesse constitue véritablement l’argument principal ici. Les règles elles-mêmes ne sont pas révolutionnaires — la plupart des ingénieurs expérimentés possèdent déjà cette connaissance de manière instinctive. Ce qui change, c’est que ces règles sont désormais appliquées avec une cohérence et une rapidité qu’un examinateur humain, surtout s’il est déjà en train de sa troisième vérification de la journée, ne peut tout simplement pas maintenir.
Un avantage sous-estimé : enseigner, pas seulement imposer
Ce qui a vraiment changé les choses dans le calcul des performances, ce n’étaient pas les vérifications elles-mêmes — c’était d’observer comment un nouveau membre de l’équipe utilisait l’outil. Cette personne n’était dans l’équipe que depuis quelques mois et s’efforçait encore de se familiariser avec le codebase. Avant d’ouvrir une demande de fusion, elle a demandé à son agent de la relire en premier. L’agent a repéré un schéma en cascade et, au lieu de se contenter de le signaler, a expliqué en termes simples — en se référant directement à la règle spécifique — pourquoi exécuter ces appels en parallèle était effectivement important dans ce contexte particulier. C’est une expérience nettement différente de celle offerte par un outil de détection d’erreurs qui ne fournit qu’un ID de règle et un message bref que l’on doit ensuite rechercher séparément. Cela ressemblait davantage à un ingénieur senior laissant un commentaire d’évaluation vraiment utile, sauf que les retours arrivaient avant même que la demande de fusion ne quitte le stade de brouillon.
Ce pourrait être le cas d’usage le plus convaincant ici, plutôt que « l’IA écrit du code plus propre ». Cela ressemble davantage à « l’IA enseigne de meilleures habitudes », de manière continue et sans nécessiter que quelqu’un consacre du temps à l’accompagnement ou à la rédaction de documents d’intégration qui deviennent obsolètes en six mois. La question reste ouverte de savoir si cet avantage persistera lorsque l’équipe disposera de cinquante fichiers de compétences superposés — chacun avec ses propres opinions, certaines inévitablement en conflit avec les autres. Mais pour une petite équipe composée d’un ingénieur expérimenté et de quelques personnes qui sont encore en train de se familiariser avec le travail, cela semble déjà être un véritable multiplicateur d’efficacité.
Où cela nous mène
Cette compétence a fini par être intégrée dans la configuration commune de l’équipe, principalement parce que les inconvénients sont minimes et que les avantages — un agent capable d’éviter l’écriture de code en cascade — constituent un échange raisonnable. Il n’est pas encore clair si ce modèle deviendra la méthode par défaut pour que les frameworks transmettent leurs directives aux agents d’IA, ou s’il ne restera qu’un autre fichier de configuration qui finira par se détériorer silencieusement une fois la nouveauté passée et que personne ne prendra la peine de le mettre à jour. C’est une question qui mérite d’être réexaminée dans six mois plutôt que d’y répondre maintenant.
Lectures complémentaires
- Inside TypeScript 7’s Go Rewrite: Speed Gains Without Code Changes — Découvrez comment le compilateur basé sur Go de TypeScript 7 permet des builds 8 à 12 fois plus rapides, pourquoi ce changement d’architecture fonctionne, et comment mettre à niveau en toute sécurité les projets existants.