Im Rahmen der Modern Web Guidance soll Ihre Entwicklung in Richtung eines „richtig-per-Standard“-Ansatzes gelenkt werden. Gelegentlich können jedoch Probleme mit der Agentenaktivierung, der Implementierungsgenauigkeit oder der Funktionserkennung auftreten. In diesem Abschnitt finden Sie Diagnoseschritte, mit denen Sie häufige Probleme beheben können. Sie erfahren beispielsweise, wie Sie dafür sorgen, dass die Modern Web-Funktion ordnungsgemäß durch Ihre Prompts ausgelöst wird, oder wie Sie überprüfen, ob Code-Fallbacks mit dem festgelegten Baseline-Status Ihres Projekts übereinstimmen. Wenn Sie auf anhaltende technische Schwierigkeiten stoßen oder veraltete Anleitungen finden, empfehlen wir Ihnen, ein Problem zu melden, damit wir diese Ressourcen auf dem neuesten Stand halten und effektiv gestalten können.
Diagnose: Modern Web-Funktion wird nicht vom Agenten erkannt
Jeder Prompt, für den die Funktionserweiterung installiert wurde, sollte sie aktivieren können, indem er „Modern Web Guidance“ auf irgendeine Weise verwendet. Wenn der von Ihnen verwendete Agent jedoch aus irgendeinem Grund Schwierigkeiten hat, können Sie ihn direkt aufrufen:
/modern-web-guidance <your prompt>
Dies gilt für KI-gestützte IDEs, die npx skills add <skill-extension> akzeptieren.
Diagnose: „Halluzinierter“ Code oder vermutete Implementierungen
Dies ist ein häufiges Problem, bei dem das LLM-Modell Wissenslücken ohne Vorwarnung füllt. Damit der Agent keine Informationen erfindet, hat es sich als sehr hilfreich erwiesen, Ihren Prompts die folgende Anweisung hinzuzufügen:
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Diagnose: Bestimmte Anleitungen werden nicht ausgelöst
Wenn Sie einen bestimmten Anwendungsfall für eine Funktion im Blick haben und diese nicht vom Agenten erkannt wird, müssen Ihre Prompts spezifische Keywords und Ankeranforderungen enthalten, damit sie richtig erkannt werden können. So kann der Agent den relevanten Leitfaden identifizieren (z. B. „Übergänge ansehen“ oder „LCP-Optimierung“).
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Den Denkprozess des Agenten nachvollziehen:
- Folgen Sie dem Agenten, wenn er die Modern Web Guidance-Funktion erkannt hat (z. B.
modern-web/SKILL.md). - Suchen Sie den Suchaufruf, z. B.
node modern-web.mjs search "scroll snap", und prüfen Sie, ob die Keywords und die resultierenden Anleitungen Ihren Erwartungen entsprechen. Die oberste Anleitung aus den Suchergebnissen wird für Ihren Prompt ausgewählt.
/modern-web-guidance Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(node --experimental-strip-types serving/bin/modern-web.ts search "carousel scroll-snap")
⎿ [{"id":"carousel-item-effects","description":"Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.","category":"user-experience","featuresUsed":["Scroll-driven animations","Scroll snap"]},
{"id":"light-dismiss-content-overlay","description":"Create swipeable layered navigation menus using native overlays and scroll gestures.","category":"user-experience","featuresUsed":["Popover","Scroll snap","inert"]},
{"id":"scroll-target-on-load","description":"Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.","category":"user-experience","featuresUsed":["scroll-initial-target","scrollIntoView()"]},
{"id":"parallax-scroll-effects","description":"Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense
of depth as the user scrolls.","category":"user-experience","featuresUsed":["Scroll-driven animations"]},
{"id":"pull-to-reveal","description":"Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.", "category":"user-experience","featuresUsed":["scroll-initial-target","Scroll snap"]}]
...
▾ Thought for 1s
Ah, let's look at the actual folder names under `guides/user-experience/` that we listed earlier to find the exact ID mapping.
Let's see the folders we found earlier:
- `carousel-slide-effects`
- `carousel-snap-highlights`
- `scroll-snap-realtime-feedback`
- `scroll-snap-state-sync`
Ah! The ID in the filesystem is `carousel-slide-effects`, while the search index returns `carousel-item-effects`.
- Führen Sie den Suchbefehl für relevante Anleitungen selbst aus:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnose: Fehlende Fallbacks für bestimmte Webbrowserfunktionen
Dies hängt vom Baseline-Status ab, den Sie in Ihrem Projekt festgelegt haben. Wenn die API erst vor Kurzem veröffentlicht wurde, hat der Agent möglicherweise kein entsprechendes Fallback oder es handelt sich um eine Funktion, die schon lange genug als „Baseline Widely“ verfügbar ist, sodass Fallbacks oder Polyfills möglicherweise nicht erforderlich sind.
Diagnose: Veralteter Bias in den Trainingsdaten
Wenn der Agent eine ältere Bibliothek anstelle einer modernen Browser-API vorschlägt, liegt das wahrscheinlich daran, dass er entweder auf seinen grundlegenden Trainingsdaten basiert oder Ihr Baseline-Status so konfiguriert ist, dass diese Funktion noch nicht unterstützt wird und das Fallback implementiert wurde.
Zur Überprüfung können Sie die Funktion erzwingen, Vorrang zu haben, indem Sie die Anleitungsbibliothek explizit über die Befehlszeile durchsuchen:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnose: Veraltete Anleitung
Es ist äußerst wichtig, dass unsere Informationen auf dem neuesten Stand sind. Melden Sie daher bitte ein Problem im Repository, wenn Sie Code finden, der aus einer veralteten Anleitung implementiert wurde. Erheben Sie dabei Beweise dafür, dass die Empfehlung des Agenten von der modern-web-Funktion und ihren Anleitungen stammt und nicht von den grundlegenden Trainingsdaten des LLM-Modells, das Ihre KI-gestützte IDE möglicherweise verwendet.
Im Agentenfenster oder Terminal können Sie möglicherweise den Denkprozess des Agenten nachvollziehen. Sie können ihn aber auch fragen, wie er zu der Schlussfolgerung gekommen ist, dass eine Codeänderung erforderlich ist. Wenn Sie zu dem Schluss kommen, dass die Empfehlung tatsächlich von der Funktion stammt, geben Sie uns Feedback und Beweise.
Feedback
Wenn Sie weitere Fragen oder Feedback zu diesen neuen Funktionen haben, lesen Sie zuerst den Beitrag zu Modern Web Guidance, bevor Sie ein Problem in unserem GitHub-Repository melden. Geben Sie beim Erstellen des Problems die ursprünglichen Agenten-Prompts, Screenshots und Logs des Denkprozesses des Agenten sowie die endgültige Codeänderung an, die auf diesem Denkprozess basiert.