Tech Teardown 046 | modern-web-guidance: Handbuch für Coding-Agents

Hintergrund: Veröffentlichung von v1.0.0 – 3.000 Sternen und ein Diskurs über Lösungen

Am 10. November 2026 wurde das GitHub-Repository GoogleChrome/modern-web-guidance mit v1.0.0 veröffentlicht, unter der Apache-2.0-Lizenz. Bis zum 11. November waren bereits über 3.000★ (3.109) Sternen erzielt worden. Am selben Tag wurde das Projekt auf Show HN veröffentlicht, mit 209 Punkten und 58 Kommentaren.

Was dieses Projekt am meisten hervorhebt, sind nicht die Sternen, sondern die Autoren: Die README-Datei wird von den Teams Google Chrome, Microsoft Edge, Mozilla Firefox und MDN sowie der Web-Entwicklungsgemeinschaft gemeinsam gepflegt. Es ist ungewöhnlich in der Geschichte der Webstandards, dass vier große Browserhersteller ein und dasselbe „Agent-Beschreibungsbuch“ unterstützen.

Das Problem, das das Projekt lösen will, lässt sich mit einem Satz zusammenfassen: Die Trainingsdaten von LLMs sind voll von veralteten Code. Agenten generieren standardmäßig umfangreichen JS-Code, obwohl für Aufgaben oft bereits native Hochleistungslösungen existieren. Selbst wenn das Modell weiß, dass API’s vorhanden sind, fehlt es an der Dichte von Produktionsniveau-Implementierungen. Paulirish vom Chrome-Team gab in Show HN ein Beispiel: Browsers können bereits Aufgaben, die früher 50 Zeilen JS oder eine Abhängigkeit erforderten, bearbeiten. CSS.highlights sorgt für Text-Highlighting, dialog() fügt einen Backdrop und Fokuspolitik hinzu, und field-sizing sorgt dafür, dass textarea automatisch hochskaliert wird, wenn etwas eingegeben wird. Das Modell kennt die Namen dieser API’s, aber es verwendet sie nicht standardmäßig.

Die Lösung besteht darin, Fachwissen über die Webplattform, Best Practices und Browserkompatibilitätsdaten in „Skills“ zu packen und diese direkt in den Arbeitsprozess des Coding-Agents einzubetten. Die Kategorien werden in der Installationsliste versteckt: Vercel Skills CLI, gh skill install, die Plugin-Märkte verschiedener Agenten – eine README-Datei bietet acht Verteilungskanäle. Dies zeigt, dass „die Installation von Wissen für Agenten“ zu einer Infrastruktur wird, und es ist das erste Mal, dass Browserhersteller gemeinsam als Inhaltslieferanten auftreten. Auch die Aufgabenverteilung im Repository muss beachtet werden: Dieser Repository dient zur Verteilung und Verpackung von Inhalten. Die Quellcode-Dateien befinden sich in GoogleChrome/modern-web-guidance-src. In der oberflächlichen Kopie gibt es nur einen Commit zu Release v1.0.0; die gesamte Projektdarstellung befindet sich auf -src.

Architektur und Prinzipien: Dokumentation ist das Produkt, Suche ist die Pipeline

Lokale Statistiken (ohne .git): 265 Dateien, davon 236 als Markdown-Dateien. Es gibt keine traditionellen Quellcode-Dateien; es handelt sich im Grunde um einen „Dokumenten-bzw.-Produkt“-Repository. Der Hauptinhalt besteht aus 209 Guides unter dem Ordner skills/modern-web-guidance, die in 17 Bereiche gegliedert sind: css, js, html, forms, accessibility, performance, security, privacy, pwa, wasm, webmcp, built-in-ai, ui-components, ui-atoms, ui-behaviors, visual-design, user-experience usw. Zusätzlich gibt es den zweiten Skill-Paket chrome-extensions (Manifest V3, Hintergrundworker, Extension-API und Chrome Web Store-Veröffentlichung). Das README beschreibt 250 moderne Web-Funktionen, die alle auf den Funktionseinträgen des Baseline-Projekts (web-platform-dx) verlinkt sind. Die Kompatibilität wird durch vier Browser unterstützt.

Der Arbeitsprozess besteht aus drei Schritten: Der Agent startet den Skill aufgrund einer Aufgabe; eine lokale Suche wird durchgeführt. Das README nutzt eine offline, token-unabhängige Embedding-Modell-Kombination mit BM25 für die Suche, ohne Netzwerkanfragen oder API-Schlüssel zu senden. Nach Erfolg wird der gesamte Inhalt des Guides in den Kontext eingefügt. Zwei Detailaspekte sind besonders erwähnenswert: Erstens wird bei der Suchanfrage die Parameter —skill-version 2026_11_09-5bcc021b verlangt, damit der Inhalt des Guides fest mit der Skill-Version verbunden ist und eine Abweichung verhindert wird. Zweitens sind die experimentellen Origin Trial-API und die „änderlichen Funktionen“ (einzelne Engine, Veröffentlichung innerhalb von 3 Monaten oder noch Stabilisierung) in der Suche sichtbar, aber die Bereitstellung ist kontrolliert. Entwickler müssen explizit set-allow-origin-trials oder set-allow-volatile-features ausführen, um sie zu aktivieren. Der Agent darf keine instabile API verwenden.

Auf der Inhaltsseite gibt es auch ein Selbstkontrollmechanismus. Das README beschreibt, dass die Guides „um Token zu sparen“ entwickelt wurden. Der zugehörige Evaluationsprozess ist wichtig: opportunity (100% minus die Passgenauigkeit ohne Anleitung) und uplift (Differenz zwischen Passgenauigkeit mit und ohne Anleitung). Inhalte, die auch ohne Guides korrekt erstellt werden können, werden direkt entfernt. Bereiche, in denen der Agent Schwierigkeiten hat, werden intensiver bearbeitet. Der SKILL.md selbst enthält etwa 205 Tokens, der chrome-extensions-Paket etwa 175 Tokens. Bei Installation kann man mit —choose nur die benötigten Pakete auswählen. Die Bereichsabdeckung zeigt auch den Ehrgeiz: Der Ordner webmcp lehrt den Agent, WebMCP zu verwenden, um Webformulare und Client-JS-Funktionen als AI-Tools zur Verfügung zu stellen. Der Ordner built-in-ai beschreibt native API, die das Lokallaufen von Übersetzungen, Zusammenfassungen und Sprachprüfungen im Browser ermöglichen, und sind alle noch fortschrittliche Fähigkeiten.

Genaue Betrachtung der Schlüsselmechanismen: „Auslösen“ als obligatorische Klausel

SKILL.md hat nur 90 Zeilen, das Design ist ziemlich radikal: Die Beschreibung sagt „MANDATORY: Execute FIRST für alle HTML/CSS- und clientseitigen JS-Aufgaben. Überspringen Sie nicht“, mit der Begründung, dass die Web-API schnell evolviert und die Trainingswerte voller veralteter Muster sind. Anschließend werden eine lange Liste von Auslöser-Szenarien aufgeführt (Modal, popover, Container-Queries, View-Transitions, scroll-driven Animations, Autofill, Passkeys, CWV, integrierte AI, WASM usw.), sowie diejenigen Szenarien, die nicht ausgelöst werden sollen: Backend-SQL/ORM, CI/CD, Docker, Python/Go, Build-Tools, Test. Die Grenzen sind klarer definiert als bei den meisten humanen Teams.

Der vierstufige Arbeitsprozess ist ebenfalls konkret. Bei der Suche werden 2-5 Wörter verwendet, um auf eine Fähigkeit zu zielen. Nur ein Fähigkeitspunkt pro Mal, ohne Framework-Namen und Anwendungstermini. Wenn der Benutzer „Confirmation modal dialog“ sagen will, wird dies übersetzt und erneut gesucht. Wenn kein Ergebnis vorliegt, wird ein konkreter Begriff verwendet, um die Suche zu reduzieren. retrieve unterstützt das Abrufen mehrerer Einträge mit Komma, generiert automatisch temporäre Dateien, die mehr als 9.5KB groß sind, um zu verhindern, dass sie abgeschnitten werden, und fordert den Agenten auf, mit Datei-Read- Tools anstatt mit cat/head zu arbeiten. Im dritten Schritt sollte man sich selbst überprüfen, indem man die Richtlinien vergleicht – klar gesagt ist, dass legacy-scan in dieser Schicht nicht verwendet wird. Im vierten Schritt sollte „### Modern Web Guidance“ beigefügt werden, mit einer Liste aller ID-Nummern und der Vermeidung von Fehlern, sowie einem kurzen Zusammenhang zur Richtlinie. Es ist auch verboten, Zitate aus dem Gedächtnis zu erfassen.

Die Qualität des Leitfadens kann man anhand des Navigations-Drahtes sehen: Der Draht wird mit top-layer-Elementen (Modal Dialog oder Popover im Manual-Modus) implementiert. Die Scrollbewegungen werden einem horizontal scrollenden Container mit zwei Scroll-Snap-Punkten übergeben. Kraft, Geschwindigkeit und Unterbrechung werden vollständig vom Browser behandelt, ohne JS-Pointer-Event-Code. Die Transparenz des Hintergrunds wird mit scroll-driven Animations an die Scrollposition gebunden. Dann wird ein IntersectionObserver verwendet, um den Zustand des Öffnens und Schließens zu bestimmen. Das ist die Fülle von Informationen, die „das Modell die Namen der API kennt, aber nicht weiß, wie sie kombiniert werden sollten“.

Legacy-scan ist eine separate Eingangsstelle: Es sucht alte Code-Teile nach veralteten Mustern, doch es deckt nur etwa 20% der Leitfadensubsets ab (diejenigen mit definierten Regeln). Die gefundenen Ergebnisse müssen manuell überprüft werden, um versteckte KeepWhen/dropWhen-Regeln zu eliminieren.

Die Haken im Ausführungsumfeld wurden bereits vorab behoben. In SKILL.md wird die Liste der erlaubten Berechtigungen genau auf npx -y modern-web-guidance@latest * eingegrenzt, wobei das Ausweisen von npx ohne Berechtigungen streng verboten ist; in dem Sandbox- oder genehmigungspflichtigen Umfeld (Codex, Claude Code) muss vor der ersten Ausführung aktiv eine Autorisierung für Netzwerkzugriff beantragt werden, um Timeout zu vermeiden; wenn ~/.npm nur lesend ist, wird NPM_CONFIG_CACHE auf /tmp verwiesen; bei Stromausfall wird die Anwendung auf npx —offline zurückgesetzt und erneut versucht; bei Verfügbarkeit von pnpm sollte pnpx bevorzugt verwendet werden. In den Richtlinien steht außerdem: „Suchen Sie immer, es ist nicht erlaubt, die Inhalte der Richtlinien aus dem Gedächtnis abzuleiten. Die Richtlinien sind die vorrangige lokale Standards für Benutzungsprojekte.“

Verteilung und Bewertung: Ein Set von Inhalten, das an acht Agent-Ökosysteme verteilt wird

Die Verteilung ist in drei Schichten organisiert. CLI-Schicht: npx modern-web-guidance@latest mit 7 Subkommandos (install/search/retrieve/legacy-scan/update/set-allow-origin-trials/set-allow-volatile-features), ab Node 22. Installationsschicht: README bietet acht Möglichkeiten: interaktiver Wizard, Vercel Skills CLI (npx skills add), gh skill install, Google Antigravity, GitHub Copilot CLI, Claude Code-Plugin, Grok Build CLI, Kimi Code, OpenAI Codex – jeder mit einem eigenen Kommando. Listenschicht: Die Repositorys enthalten drei Manifeste: plugin.json (agent-plugins.org schema 1.0.0), gemini-extension.json, kimi-plugin.json, wobei dieselben Skills für die gemeinsamen Agenten, Gemini und Kimi verpackt werden. Außerdem gibt es policies/modern-web-guidance.toml, das modern-web-Kommando in Plan-Modus auf „ask_user“ setzt.

Alle Ergebnisse werden in dem README-Text beschrieben: Am 8. November fand eine Evaluationsrunde statt, bei der antigravity_cli (gemini-4-argon) von 58% auf 94% (+36 Prozentpunkte) und claude_code (opus-5-5) von 57% auf 88% (+31 Prozentpunkte) erreichte. codex_cli (gpt-6.1-sol) lag bei 54% bis 82% (+28 Prozentpunkte). Es wurden etwa 215 Aufgaben und ca. 1800 Aussagen gemacht. Die Art der Evaluationsaufgaben ist bemerkenswert: Anhand von zwei vollständigen Benchmarks (daily-grind, devtools-times) wurden Prompts definiert, die echte Entwickler simulieren, zum Beispiel „Meine Bilder sollten schneller geladen werden“. Es wurde absichtlich keine API genannt, um zu testen, ob das Agentium natürlich Richtlinien finden und anwenden kann. Der Bewertungssystem verwendet die goldenen Lösungen der drei Agenten Claude, Codex und AGY (100% Erfolg), ergänzt durch ein unverändertes Basisspiel (0% Erfolg). Die Ergebnisse im README werden alle zwei Tage aktualisiert, seit dem 2. November. Für jeden Agent gibt es eine detaillierte Auflistung der Richtlinien auf dem öffentlichen Eval Dashboard. Dies sind die offiziellen Angaben, ohne Überprüfung durch Dritte, aber die Haltung „Auch ungeleitete Basisspiele werden angezeigt“ ist ehrlichkeiser als nur hohe Ergebnisse anzuzeigen.

Die Telemetrie-Informationen werden wahrheitsgemäß bereitgestellt: Anonyme Daten zur Installationzahl, den Namen der Agenten, die Richtlinien-ID und Suchbegriffe werden gesammelt, ohne die ursprünglichen Prompts. Die Sammlung der Codepositionen wird im README beschrieben. Ein Nutzer hat seit einigen Monaten installiert; Claude Doctor hat ihn bisher nicht entfernt, was bedeutet, dass er aktiv ist.

Kontroversen und Risiken: Wer hat das Recht, „Moderne“ zu definieren?

In HN’s Hot Reviews area, there are both positive and negative opinions. On the demand side, the feedback is straightforward: some say it was long overdue. Many reviews discuss PRs that “can be replaced with two lines of modern features but are written in a messy manner,” and some have even written half-finished tools. There are three main criticisms. First, “Best practices are dead in the AI era; soon no one will read AI-generated code.” Paulirish responded that maintainability is the next frontier—a one-line CSS solution is better than 60 lines of business code withResizeObserver and setTimeout. Another person added: Best practices that improve user experience are not dead; it’s just that the focus has shifted away from developer efficiency. Second, “Modern Web primitives” may not necessarily be best practices. Browser implementation differences require ten years of refinement, and manual testing across devices and browsers is inevitable. Some people treat agents as random machines, believing that having them go through a guide and take an average still doesn’t work. The third and most serious issue is governance. Chrome has too much power in the standard world, forcing all LLMs to follow the guidance of the Chrome team, leading to a situation where “please visit our site using this browser.” Responders pointed out that Firefox and Edge are also contributors, and only recommend practices supported by all four browsers in the Baseline. Other comments suggest that publishing opinions in a neutral repository would be better. This concern has a long history: In early 2026, Adrian Roselli criticized the project’s early form in his article “Maybe Don’t Rely on Google’s Modern Web Guidance.” The release of v1.0 with joint maintenance by three companies and alignment with Baseline can be seen as a response to this criticism. However, the actual contribution of Mozilla/Edge has not been independently verified this time.

There are also two risks. eval is a self-proposed assessment system by the official team. Although the terminology for opportunity/uplift is transparent, the task set tends to focus on scenarios with native solutions. It’s not surprising that uplift performs well; however, one should adjust one’s expectations when considering selection bias. Regarding distribution, simonw offered a simple suggestion on HN: Besides npm packages, use GitHub Pages to publish a markdown index page (currently showing 404), which links to pure md versions of all documents and is designed for grep searching. No additional software needs to be installed. The Chrome team responded by pointing to the guides page on developer.chrome.com. In other words, those who don’t want agents to run npx currently lack an official channel.

Schlussfolgerungen und Aussichten

Der Wert von modern-web-guidance liegt nicht in den 209 Dokumenten selbst, sondern darin, dass es ein Vorbild für die „Agent-Knowledge-Supply“ geschaffen hat: Wissen wird nicht in Gewicht eingeteilt, sondern als externes Feature für nachträgliche Suche verwendet. Es werden Punkte auf Basis von Pointers gespeichert, nicht Inhalte; Versionen sind festgelegt, Experimente werden kontrolliert, und die Verwendung ist zwingend offenzulegen. Einige sagen, dass dies die wahre Form des Agent-Kristalls darstellt: Minimierung des eingebauten Wissens, ergänzt durch Echtzeit-Suche und Caching. Ich stimme dieser Richtung zu. Drei Aspekte verdienen Aufmerksamkeit: Ob die Beiträge von Mozilla/Edge signiert oder tatsächlich nützlich sind, kann man anhand der Verteilung der Commitments im -src-Repository erkennen; ob es zu Replikationen durch Dritte kommen wird; und ob die offizielle md-Indexseite weitere Informationen hinzufügt. Für Entwickler: Frontend-Projekte können jetzt einfach installiert werden, was kostengünstig ist (eine npx-Befehl). Im schlimmsten Fall wird der Agent ein paar Mal mehr Dokumente durchsuchen. Für diejenigen, die Agent-Infrastruktur betreiben: Die Schreibweise der Trigger-Klauseln in SKILL.md, die Methoden zur Reduzierung von Inhalten in opportunity/uplift, sowie die Sicherstellung, dass 9,5 KB nicht abgeschnitten werden, können direkt in das eigene Skill-System integriert werden. Die Bedeutung, die Browserhersteller dem „Verzicht auf schreibbaren Code“ geben, könnte größer sein als die 3000 Likes.

Quelle der Informationen

• Repository: github.com/GoogleChrome/modern-web-guidance (Apache-2.0; bis 11-11 über 3.000★, Snapshot 3.109; v1.0.0 veröffentlicht am 11-10, Git Log-Format; Quellcode im GoogleChrome/modern-web-guidance-src)
• Statistiken zur lokalen Clone am 11-11 (nur lesend) unter /tmp/mwg-1111: 265 Dateien (ohne .git), 236 Markdown-Dateien; 209 Guides, 17 Kategorienübersichten; SKILL.md mit 90 Zeilen, README.md mit 636 Zeilen; drei Verteilungslisten für plugin.json/gemini-extension.json/kimi-plugin.json; policies/modern-web-guidance.toml
• README.md (von vier Teams gemeinsam gepflegt als offizielle Anleitung; 250 Funktionen und Baseline-Links; Offline-Embedding+BM25, —skill-version 2026_11_09-5bcc021b, Origin Trial/veränderliche Funktionensteuerung, acht Installationsmethoden, 7 CLI-Befehle, Node≥22, Telemetriedaten alle im README-Format; Eval-Tabelle am 8. November drei Zeilen +36/+31/+28pp als README-Anleitung, ohne Überprüfung durch Dritte; Anzahl der Tokens in der Skill-Paket-Anleitung ~205/~175)
• SKILL.md (VERPFLICHTET Original-Script, vier-Schritt-Flow, 9.5KB Dateigröße, Formatierung für Offenlegungen, legacy-scan deckt ~20% ab); guides/ui-components/navigation-drawer.md (Beispiele für Faltenschaltflächen)
• HN Story 50443812 (209▲/58💬, Algolia-Suche): paulirish Topposts und Antworten, halflife, phyzix5761, sublinear, advisedwang, philipwalton, 0o777, simonw und kinlan, nico, fumar, cyanydeez; positive und negative Meinungen, nicht einheitlich positiv bewertet
• adrianroselli.com 2026/05 „Maybe Don’t Rely on Google’s ‘Modern Web Guidance’“ (HN 12▲); tiefe Beiträge von Mozilla/Edge wurden nicht unabhängig überprüft

Unterschrift: Yongliang