Tech Teardown 046 | modern-web-guidance : le manuel des agents IA

Contexte : La publication de la version 1.0.0 a été suivie par 3 000 étoiles et une discussion approfondie

Le 10 novembre 2026, le dépôt GitHub GoogleChrome/modern-web-guidance a publié la version 1.0.0 sous licence Apache-2.0. Au 11-11, plus de 3 000 étoiles (3 109) avaient été attribuées. Le même jour, le projet a été mis en avant sur Show HN avec 209 points et 58 commentaires.

Ce qui attire le plus l’attention dans ce projet n’est pas le nombre d’étoiles, mais la signature : le README est maintenu conjointement par les équipes de Google Chrome, Microsoft Edge, Mozilla Firefox et MDN, ainsi que par la communauté du développement web. Il est rare dans l’histoire des normes Web que quatre grandes entreprises de navigateurs approuvent un même « manuel d’agent ».

Le problème que ce projet cherche à résoudre peut être exprimé en une phrase : les données d’entraînement des LLM sont remplies de code obsolète, et les agents génèrent par défaut du JavaScript trop complexe, alors que les tâches peuvent souvent être réalisées avec des solutions natives performantes. Même si le modèle connaît l’existence des API, il manque de densité dans les modes de réalisation à large échelle. Paulirish de l’équipe Chrome a donné un exemple sur Show HN : les navigateurs peuvent déjà gérer des tâches qui nécessitaient auparavant 50 lignes de JavaScript ou une dépendance, CSS.highlights permet la mise en évidence des textes, dialog ajoute showModal() avec un arrière-plan et la gestion du focus, et field-sizing fait augmenter automatiquement la taille du champ de texte en fonction des entrées. Le modèle connaît les noms de ces API, mais ne les utilise pas par défaut.

La solution consiste à packager les connaissances spécialisées sur les plateformes web, les meilleures pratiques et les données de compatibilité avec les navigateurs en « compétences » qui sont intégrées directement dans le flux de travail de l’agent de codage. Les signaux de catégories sont cachés dans la liste d’installation : Vercel Skills CLI, gh skill install, les marchés de plugins des différents agents. Un seul README rassemble huit canaux de distribution, indiquant que « fournir aux agents des connaissances supplémentaires » est en train de devenir une infrastructure, et les fabricants de navigateurs sont pour la première fois collectivement des fournisseurs de contenu. Il faut également noter la division du travail dans le dépôt : ce dépôt sert de lieu de distribution et de packaging, les sources du contenu se trouvent dans GoogleChrome/modern-web-guidance-src. Dans une simple clonage, il n’y a qu’une seule contribution pour la version Release v1.0.0, tandis que toute l’histoire de développement du projet se trouve dans -src.

Architecture et principes : Le document est le produit, la recherche est la pipeline

Statistiques locales (sans .git) : 265 fichiers, dont 236 en markdown. Il n’y a pas de code source au sens traditionnel ; c’est essentiellement un répertoire où les documents sont considérés comme des produits. Le noyau contient 209 guides sous le dossier skills/modern-web-guidance, divisés en 17 domaines : css, js, html, forms, accessibility, performance, security, privacy, pwa, wasm, webmcp, built-in-ai, ui-components, ui-atoms, ui-behaviors, visual-design, user-experience, etc. Il y a également le deuxième paquet de compétences chrome-extensions (Manifest V3, worker en arrière-plan, API d’extension et publication sur Chrome Web Store). Le README couvre 250 caractéristiques modernes du Web, toutes liées aux pages des caractéristiques du projet Baseline (web-platform-dx), avec une compatibilité alignée sur les quatre navigateurs.

La pipeline de travail se déroule en trois étapes : l’agent déclenche la compétence en fonction de la tâche ; une recherche est effectuée localement, et le README utilise un modèle d’encodage hors ligne sans dépendance et la recherche BM25, sans envoyer de requêtes internet ni utiliser une clé API ; après l’échec, retrieve injecte le contenu intégral du guide dans le contexte. Deux détails importants des projets méritent attention : premièrement, l’ordre de recherche exige obligatoirement le paramètre —skill-version 2026_11_09-5bcc021b, assurant que le contenu du guide est lié à la version de la compétence pour éviter les variations ; deuxièmement, les API d’essai Origin et les « caractéristiques volatiles » (un seul moteur, publiées dans les 3 mois suivants ou encore en cours de stabilisation) sont visibles dans la recherche, mais sont bloqués par retrieve. Les développeurs doivent explicitement exécuter set-allow-origin-trials ou set-allow-volatile-features pour les débloquer, l’agent ne peut pas utiliser de manière indépendante des API instables.

Il y a également un mécanisme d’auto-réduction dans le contenu. Le README indique que les guides sont conçus pour économiser des tokens, et le processus d’évaluation est considéré deux fois : opportunity (100 % moins la probabilité de réussite sans guidance) et uplift (la différence entre la probabilité de réussite avec et sans guidance). Les contenus que le modèle peut correctement générer sans les guides sont directement coupés, tandis que les points difficiles pour l’agent sont enrichis. Le fichier SKILL.md contient environ 205 tokens, et le paquet chrome-extensions environ 175 tokens ; lors de l’installation, on peut utiliser —choose pour sélectionner uniquement les paquets nécessaires. La couverture des domaines montre également l’ambition : le dossier webmcp apprend à l’agent à utiliser WebMCP pour exposer les formulaires web et les fonctions JS client en outils AI, tandis que le dossier built-in-ai explique les API natifs permettant au navigateur de traduire, résumer et détecter les langues localement, toutes des capacités encore récentes.

Lecture détaillée des mécanismes clés : « déclencher » est écrit comme une condition obligatoire

SKILL.md ne contient que 90 lignes, ce qui indique un design assez radical : la description précise « MANDEABLE : Exécuter EN PREMIERMENT pour toutes les tâches HTML/CSS et JS clients. NE SAUTER PAS », car les API web évoluent rapidement et les poids d’entraînement contiennent de nombreux modèles obsolètes. Ensuite, une longue liste de scénarios de déclenchement est listée (modal, popover, container queries, transitions de vue, animations dépendant du scroll, auto-fill, passkeys, CWV, AI intégré, WASM, etc.), ainsi que des scénarios interdits : SQL/ORM back-end, CI/CD, Docker, Python/Go, outils de construction, tests. Les limites sont clairement définies plus que celles des normes de la plupart des équipes humaines.

Le flux de travail en quatre étapes est également très précis. La recherche exige des requêtes orientées action avec 2 à 5 mots, en examinant une seule capacité à la fois, sans utiliser les noms de frameworks ou des noms d’applications. Lorsqu’il est demandé de « supprimer avant confirmation », cela doit être traduit en « confirmation modal dialog » avant de rechercher ; en cas d’absence de résultat, il faut utiliser un nom spécifique, puis réduire la liste. Le « retrieve » prend plusieurs entrées séparées par des virgules, et produit automatiquement des fichiers temporaires de plus de 9,5 KB pour éviter les interrupions, et exige que l’agent utilise des outils de lecture de fichiers plutôt que cat/head. La troisième étape consiste à vérifier la mise en œuvre selon les directives, en précisant clairement que le « legacy-scan » n’est pas utilisé dans cette étape. La quatrième étape inclut une section « ### Modern Web Guidance » où sont détaillées les applications de chaque ID et les mesures prises pour éviter les erreurs, avec un résumé du texte des directives originales, et il est interdit de créer des citations à partir de souvenirs.

La qualité du guide peut être vue dans l’article « navigation-drawer » : le « drawer » est mis en œuvre avec des éléments « top-layer » (mode modal ou popover), la manipulation de la souris est confiée à un conteneur de glissement horizontal avec deux points de fixation, et les processus de momentum, vitesse et interruption sont gérés par le navigateur native, sans code JS pointer-event ; la transparence du « backdrop » est liée à la position de scroll via une animation dépendant du scroll ; un IntersectionObserver est également utilisé pour déterminer l’état d’ouverture et de fermeture. C’est là la densité complète de la combinaison des API, où le « modèle connaît les noms des API mais ne sait pas les combiner de cette manière ».

Le « legacy-scan » est une entrée indépendante : il scanne le code existant pour trouver des modèles obsolètes, mais ne couvre que environ 20 % du sous-ensemble du guide (la partie avec des règles définies), et les résultats obtenus doivent être vérifiés manuellement selon les règles « keepWhen »/« dropWhen » pour éliminer les faux positifs.

Les obstacles de l’environnement d’exécution ont également été prévus à l’avance. SKILL.md exige une liste blanche de droits précise pour npx -y modern-web-guidance@latest *, interdisant strictement l’autorisation de npx nu * ; dans les environnements sandbox ou avec autorisation (Codex, Claude Code), il est nécessaire de demander activement une autorisation d’accès à Internet avant la première exécution pour éviter les temps d’attente ; lorsque ~/.npm est en mode read-only, NPM_CONFIG_CACHE est défini sur /tmp ; en cas de coupure d’Internet, retourne à npx —offline pour réessayer ; si pnpm est disponible, utilise plutôt pnpx. Il y a aussi une règle fondamentale dans les directives : recherchez toujours en premier, il est interdit de créer des contenus basés sur la mémoire ; les directives sont le standard local préféré pour les projets utilisateurs.

Distribution et évaluation : un ensemble de contenu pour huit écosystèmes d’agents

La distribution est divisée en trois niveaux. Niveau CLI : npx modern-web-guidance@latest avec 7 commandes supplémentaires (install/search/retrieve/legacy-scan/update/set-allow-origin-trials/set-allow-volatile-features), à partir de Node 22. Niveau d’installation : README fournit huit moyens d’installation, y compris le guide interactif, Claude Code Skills CLI (npx skills add), gh skill install, Google Antigravity, GitHub Copilot CLI, Claude Code plugin, Grok Build CLI, Kimi Code, OpenAI Codex, chacune avec une commande spécifique. Niveau de listing : les répertoires contiennent trois fichiers de manifeste : plugin.json (agent-plugins.org schema 1.0.0), gemini-extension.json, kimi-plugin.json, et ces mêmes compétences sont emballées séparément pour les agents généraux, Gemini et Kimi. Il y a aussi policies/modern-web-guidance.toml, qui définit modern-web en mode plan comme ask_user.

Les chiffres relatifs aux résultats sont tous tirés du README : le 8 novembre, la ronde d’évaluation a donné à antigravity_cli (gemini-4-argon) un score de 58% à 94% (+36 points), à claude_code (opus-5-5) de 57% à 88% (+31 points), et à codex_cli (gpt-6.1-sol) de 54% à 82% (+28 points). Il y avait environ 215 tâches et environ 1800 affirmations. La manière de poser les questions lors de l’évaluation est intéressante : des prompts simulant des développeurs réels ont été définis pour deux applications de référence complètes (daily-grind, devtools-times), par exemple « Fais en sorte que mes images s’chargent plus rapidement ». Aucun API n’a été spécifié, ce qui teste la capacité de l’agent à découvrir et à utiliser naturellement les guides. Le système de notation utilise les solutions optimales des agents Claude/Codex/AGY pour évaluer 100% des tâches cibles, puis il y a une application de référence non modifiée (0% de réussite). Le tableau de résultats du README est mis à jour tous les deux jours à partir du 2 novembre, avec un détail par guide pour chacun des trois agents affiché sur le dashboard d’évaluation public. Ce sont les informations officielles, non vérifiées par des tiers, mais l’approche de « signaler également la référence non guidée » est plus honnête que de ne signaler uniquement les scores élevés.

Les données collectées sont déclarées fidèlement : un nombre d’installations, le nom de l’agent appelé, l’id du guide et les mots de recherche sont collectés de manière anonyme, sans fournir les prompts originaux. La localisation des codes est indiquée dans le README. Certaines personnes sur HN ont fourni des preuves indirectes : elles avaient installé l’application quelques mois auparavant, et Claude Doctor ne l’a jamais supprimée, ce qui indique qu’elle fonctionne toujours.

Controverses et risques : qui a le droit de définir « moderne »

La section des critiques chaudes sur HN présente des points de vue contradictoires. Sur le côté des demandeurs, la résonance est directe : certains disent qu’il fallait en avoir besoin depuis longtemps, car il y a trop de PR qui sont « transformables en deux lignes de caractéristiques modernes mais écrits en un brouillard », et certains ont même écrit des outils inachevés. Les critiques portent sur trois points. Premièrement, « les meilleures pratiques sont mortes à l’ère de l’IA, et personne ne lira le code généré par l’IA » ; paulirish répond que la maintenabilité est la prochaine tendance, un schéma CSS simple est mieux que 60 lignes de code business avecResizeObserver et setTimeout ; un autre ajoute que les meilleures pratiques pour améliorer l’expérience utilisateur ne sont pas mortes, mais le focus s’est déplacé de l’efficacité des développeurs. Deuxièmement, « les langages modernes web » ne sont pas nécessairement les meilleures pratiques, les différences d’implémentation entre navigateurs prennent dix ans à se resolver, et les tests manuels entre différents appareils et navigateurs sont inévitables ; certains considèrent l’agent comme une machine aléatoire, pensant qu’il est inutile de lui faire suivre des guides et de prendre la moyenne. Troisièmement, la gouvernance. Chrome a déjà trop de pouvoir dans le monde standard, et permettre à tous les LLM de suivre les directives du groupe Chrome mène à « veuillez utiliser ce navigateur pour accéder à notre site » ; les répondants soulignent que Firefox et Edge sont également des contributeurs, et recommandent uniquement des pratiques supportées par quatre navigateurs Baseline, d’autres commentaires suggèrent de publier les opinions dans un repository neutre. Cette préoccupation a une longue histoire : en mai 2026, les premières versions du projet ont été critiquées par Adrian Roselli dans un article « Maybe Don’t Rely on Google’s Modern Web Guidance », la version 1.0 a été maintenue conjointement par trois navigateurs, alignée sur Baseline, ce qui peut être interprété comme une réponse à cette critique. Cependant, l’importance réelle de Mozilla/Edge comme contributeur n’a pas été vérifiée indépendamment cette fois-ci.

Il y a deux autres risques. L’évaluation est effectuée par l’équipe officielle elle-même, et bien que les termes opportunity/uplift soient transparents, la liste des tâches penche vers des scénarios avec des solutions natives, donc il n’est pas surprenant que uplift soit élevé, il faut relativiser le choix. En termes de distribution, simonw a donné une suggestion simple sur HN : en plus des packages npm, utiliser GitHub Pages pour publier une page d’index markdown (actuellement 404), liant toutes les versions purement md des documents, conçue pour la recherche avec grep, sans installer quoi que ce soit ; l’équipe Chrome a répondu en mentionnant la page guides sur developer.chrome.com. En d’autres termes, ceux qui ne veulent pas que l’agent fonctionne via npx manquent actuellement d’une porte officielle pour y accéder.

Conclusion et perspectives

La valeur de modern-web-guidance ne réside pas dans les 209 documents eux-mêmes, mais dans le modèle qu’elle a donné à la « fourniture de connaissances pour agents » : les connaissances ne sont pas stockées en tant que contenu, mais utilisées comme des extensions de recherche sur demande. Les informations sont stockées sous forme de pointeurs plutôt que de contenu réel, avec des versions fixées, des fonctionnalités expérimentales contrôlées et des exigences strictes concernant l’utilisation. Certains disent que c’est là la véritable forme du « Saint Graal » pour les agents : minimiser le contenu intégré, ajouter une recherche en temps réel et un cache, je suis d’accord avec cette direction. Trois points méritant attention : si les contributions de Mozilla/Edge sont basées sur des signatures ou sur des actions concrètes, cela peut être déterminé par la distribution des contributions dans le repository -src ; il se pourrait que des versions reproduites par des tiers apparaissent ; et si la page d’indexation en MD purement officielle ajoute des informations. Pour les développeurs, les projets frontaux peuvent être installés immédiatement, à un coût faible (une seule commande npx), et dans le pire des cas, l’agent consulte plusieurs fois les documents. Pour ceux qui travaillent sur l’infrastructure des agents, la manière de définir les conditions d’activation dans SKILL.md, la façon de réduire le contenu dans opportunity/uplift, et la protection contre la coupure des fichiers de 9,5 KB peuvent être directement intégrées dans leur propre système de compétences. Le fait que les fabricants d’outils de navigation rendent les « codes d’époque » exécutables par machine a peut-être une signification plus importante que 3000 likes.

Source d’information

• Repo : github.com/GoogleChrome/modern-web-guidance (Apache-2.0 ; plus de 3,000★ le 11-11, snapshot 3,109 ; v1.0.0 publié le 11-10, format git log ; le code source se trouve dans GoogleChrome/modern-web-guidance-src)
• Statistiques du clone local read-only le 11-11 (/tmp/mwg-1111) : 265 fichiers (pas incluant .git), 236 fichiers markdown ; 209 guides, 17 catégories de répertoires ; SKILL.md 90 lignes, README.md 636 lignes ; trois listes de distribution pour plugin.json/gemini-extension.json/kimi-plugin.json ; policies/modern-web-guidance.toml
• README.md (maintenu conjointement par quatre équipes pour l’autorisation officielle ; 250 fonctionnalités et liens vers Baseline ; embedding hors ligne + BM25, —skill-version 2026_11_09-5bcc021b, Origin Trial/contrôle des fonctionnalités variables, huit méthodes d’installation, 7 commandes CLI, Node≥22, toutes les données de télémétrie sont conformes au format README ; trois lignes de tableau eval le 8 novembre +36/+31/+28pp pour l’autorisation README, non vérifiées par des tiers ; nombre de tokens du paquet skill ~205/~175 pour l’autorisation)
• SKILL.md (contenu obligatoire des conditions de déclaration, flux de travail en quatre étapes, 9.5KB de taille, format de publication, legacy-scan couvre ~20%）；guides/ui-components/navigation-drawer.md (exemple de réalisation avec une boîte à outils)
• HN story 50443812 (209▲/58💬, recherche sur Algolia) : paulirish en haut de la page et réponses, halflife, phyzix5761, sublinear, advisedwang, philipwalton, 0o777, simonw et kinlan, nico, fumar, cyanydeez ; opinions positives et négatives, pas toutes des critiques positives
• adrianroselli.com 2026/05 « Maybe Don’t Rely on Google’s ‘Modern Web Guidance’ » (HN 12▲) ; la contribution réelle de Mozilla/Edge n’a pas été vérifiée indépendamment

Signé : Yongliang