Bien que les consignes pour le Web moderne visent à orienter votre développement vers une approche "correcte par défaut", vous pouvez parfois rencontrer des problèmes liés à l'activation de l'agent, à la précision de l'implémentation ou à la découverte de fonctionnalités. Cette section fournit des étapes de diagnostic pour vous aider à résoudre les problèmes courants, par exemple en vous assurant que la compétence Web moderne est correctement déclenchée par vos invites ou en vérifiant que les solutions de secours du code correspondent à l'état de référence établi de votre projet. Si vous rencontrez des difficultés techniques persistantes ou si vous identifiez des consignes obsolètes, nous vous encourageons à signaler un problème pour nous aider à maintenir l'exactitude et l'efficacité de ces ressources.
Diagnostiquer le problème lié à la compétence Web moderne qui n'est pas détectée par l'agent
Toute invite ayant installé l'extension de compétence doit pouvoir l'activer en incluant d'une manière ou d'une autre l'expression "consignes pour le Web moderne". Toutefois, si l'agent que vous utilisez rencontre des difficultés, vous pouvez l'appeler directement comme suit :
/modern-web-guidance <your prompt>
Cela s'applique aux IDE basés sur l'IA qui acceptent npx skills add <skill-extension>.
Diagnostiquer le code "halluciné" ou les implémentations devinées
Il s'agit d'un cas courant où le modèle LLM comble les lacunes de connaissances sans avertissement. Pour empêcher l'agent d'inventer des informations, nous avons constaté qu'il était très utile d'ajouter l'instruction suivante à vos invites :
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Diagnostiquer l'échec du déclenchement de consignes spécifiques
Si vous ciblez un cas d'utilisation spécifique et que l'agent ne le détecte pas, assurez-vous que vos invites incluent des mots clés spécifiques et des exigences d'ancrage pour une bonne détectabilité. Cela aide l'agent à identifier la piste de consignes pertinente (par exemple, "transitions de vue", "optimisation LCP").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Suivez le processus de réflexion de l'agent :
- Suivez-le s'il a découvert la compétence Consignes pour le Web moderne (par exemple,
modern-web/SKILL.md). - Recherchez l'appel de recherche (par exemple,
node modern-web.mjs search "scroll snap") et vérifiez si les mots clés et les guides résultants sont ceux que vous attendiez. Le guide le plus pertinent des résultats de recherche est celui qui est choisi pour être appliqué à votre invite.
/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`.
- Exécutez vous-même la commande de recherche pour les guides pertinents :
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnostiquer les solutions de secours manquantes pour certaines fonctionnalités de navigateur Web
Cela dépend de l'état de référence que vous avez défini dans votre projet. Si l'API a été publiée très récemment, l'agent peut ne pas disposer d'une solution de secours équivalente sur laquelle s'appuyer. Il peut également s'agir d'une fonctionnalité disponible depuis suffisamment longtemps pour que les solutions de secours ou les polyfills ne soient pas nécessaires.
Diagnostiquer le biais des données d'entraînement obsolètes
Si l'agent suggère une ancienne bibliothèque au lieu d'une API de navigateur moderne, il est probable qu'il s'appuie sur ses données d'entraînement de base ou que votre Baseline soit configuré pour ne pas encore prendre en charge cette fonctionnalité et que la solution de secours ait été implémentée.
Pour vérifier, vous pouvez forcer la compétence à prendre le dessus en recherchant explicitement la bibliothèque de consignes à l'aide de l'interface de ligne de commande :
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnostiquer les consignes obsolètes
Il est essentiel que nos informations soient à jour. Nous vous prions donc de signaler un problème dans le dépôt si vous trouvez du code implémenté à partir d'un guide obsolète. Pour ce faire, rassemblez des preuves que l'agent vous recommande la compétence modern-web et ses guides plutôt que les données d'entraînement de base du modèle LLM que votre IDE basé sur l'IA peut utiliser.
Dans la fenêtre ou le terminal de votre agent, vous pouvez peut-être suivre son raisonnement, mais vous pouvez également lui demander de vous expliquer comment il est parvenu à la conclusion de la modification du code. Une fois que vous avez conclu qu'il s'agit bien de la compétence, envoyez-nous vos commentaires et vos preuves.
Commentaires
Si vous avez d'autres questions ou commentaires sur ces nouvelles fonctionnalités, lisez d'abord comment contribuer aux consignes pour le Web moderne avant de signaler un problème dans notre dépôt GitHub. Lorsque vous créez le problème, fournissez les invites initiales de l'agent, des captures d'écran et des journaux du processus de réflexion de l'agent, ainsi que la modification finale du code recommandée en fonction de ce raisonnement.