Bien que Modern Web Guidance vise à orienter votre développement vers une approche "correcte par défaut", vous pouvez parfois rencontrer des problèmes d'activation de l'agent, de précision de l'implémentation ou de découverte des fonctionnalités. Cette section fournit des étapes de diagnostic pour vous aider à résoudre les problèmes courants, par exemple pour vous assurer que la compétence Modern Web est correctement déclenchée par vos requêtes ou pour vérifier que les solutions de remplacement du code sont conformes à l'état de référence établi de votre projet. Si vous rencontrez des problèmes techniques persistants ou si vous identifiez des conseils obsolètes, nous vous encourageons à signaler un problème pour nous aider à maintenir l'exactitude et l'efficacité de ces ressources.
Diagnostiquer pourquoi Modern Web Guidance n'est pas utilisé par votre agent
Lorsque Modern Web Guidance est installé, les agents sont invités à l'utiliser pour toutes les tâches de développement Web. Cependant, il arrive que les agents ignorent ces instructions.
Vous pouvez explicitement demander à l'agent d'utiliser Modern Web Guidance en ajoutant une phrase telle que "use modern-web-guidance" à la fin de votre prompt.
Certains agents permettent également d'appeler directement une compétence à l'aide d'une syntaxe spécifique, telle que /modern-web-guidance ou $modern-web-guidance, selon l'agent.
Consultez la documentation de votre agent ou demandez-lui comment appeler directement la compétence modern-web-guidance si vous n'êtes pas sûr.
Diagnostiquer le code "halluciné" ou les implémentations devinées
Il s'agit d'un phénomène courant où le LLM comble les lacunes de connaissances sans avertissement. Pour éviter que l'agent n'invente des informations, nous avons constaté qu'il est très utile d'ajouter l'instruction suivante à vos requêtes :
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
Diagnostiquer l'échec du déclenchement de conseils spécifiques
Si vous ciblez un cas d'utilisation de fonctionnalité spécifique et que vous ne le voyez pas découvert par l'agent, assurez-vous que vos requêtes incluent des mots clés spécifiques et des exigences d'ancrage pour une visibilité appropriée. Il aide l'agent à identifier le parcours d'aide approprié (par exemple, "transitions d'affichage", "optimisation du LCP").
Suivez le processus de réflexion de l'agent :
- Vérifiez le résultat pour voir si la compétence
modern-web-guidancea été appelée. - Localisez l'appel de recherche (par exemple,
npx -y modern-web-guidance@latest search "carousel scroll snap") et vérifiez si les mots clés et les guides obtenus correspondent à ce que vous attendiez. - Vérifiez que l'appel de récupération a demandé le guide approprié, par exemple :
npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync".
Create a new folder and create a carousel web app for me that implements scroll-snap.
...
● Bash(npx -y modern-web-guidance@latest search "carousel scroll snap" --skill-version 2026_05_16-c5e7870)
⎿ [{"id":"carousel-snap-highlights","description":"Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden
content.","category":"user-experience","featuresUsed":["Container scroll-state queries"],"tokenCount":1442,"similarity":0.7783},
{"id":"carousel-slide-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"],"tokenCount":2105,"similarity":0.6625},
{"id":"scroll-snap-state-sync","description":"Synchronize navigation indicators, linked content panels, and analytics tracking with the actively snapped item in a scrollable container.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1053,"similarity":0.6166},
{"id":"scroll-snap-realtime-feedback","description":"Provide real-time visual feedback in linked UI elements while a user scrolls through snap-aligned content, before the scroll gesture completes.","category":"user-experience","featuresUsed":["Scroll snap events","Scroll
snap"],"tokenCount":1886,"similarity":0.5664},
{"id":"navigation-drawer","description":"Create a navigation drawer component that, when triggered from a menu button, slides in from the side overlayed on top of existing page content, and slides out when dismissed (by swiping away, tapping outside, or pressing
escape).","category":"user-experience","featuresUsed":["inert","Intersection observer","Popover","Registered custom properties","Scroll-driven animations","scroll-initial-target","Scroll snap"],"tokenCount":4317,"similarity":0.5099}]
● Bash(npx -y modern-web-guidance@latest retrieve "carousel-snap-highlights,carousel-slide-effects,scroll-snap-state-sync")
⎿ <output +158 lines>
}, undefined);
if (topEntry) setSelectedParagraph(topEntry.id);
},
{ root: main, threshold: 0.9 // Adjust based on your use case },
);
// Observe all snap targets (e.g., section headers)
document.querySelectorAll('h2').forEach(header => observer.observe(header));
}
- Vous pouvez également exécuter vous-même les commandes de recherche dans le terminal pour voir quels guides correspondent à votre requête de recherche.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
Commentaires
Si vous avez d'autres questions ou des commentaires sur ces nouvelles fonctionnalités, découvrez d'abord comment contribuer à Modern Web Guidance avant de signaler un problème dans notre dépôt GitHub. Lorsque vous créez le problème, fournissez les prompts initiaux de l'agent, des captures d'écran et des journaux du processus de réflexion de l'agent, ainsi que la modification de code finale recommandée en fonction de cette réflexion.