Si bien la Guía de la Web moderna tiene como objetivo orientar tu desarrollo hacia un enfoque "correcto de forma predeterminada", es posible que, en ocasiones, encuentres problemas con la activación del agente, la precisión de la implementación o el descubrimiento de funciones. En esta sección, se proporcionan pasos de diagnóstico para ayudarte a resolver desafíos habituales, como asegurarte de que la habilidad de la Web moderna se active correctamente con tus instrucciones o verificar que las alternativas de código se alineen con el estado de referencia establecido de tu proyecto. Si encuentras obstáculos técnicos persistentes o identificas orientación desactualizada, te recomendamos que registres un problema para ayudarnos a mantener estos recursos precisos y eficaces.
Diagnostica si el agente no detecta la habilidad de la Web moderna
Cualquier instrucción que tenga instalada la extensión de habilidad debería poder activarla incluyendo "modern web guidance" de alguna manera, pero si, por algún motivo, el agente que usas tiene dificultades, puedes llamarlo directamente de la siguiente manera:
/modern-web-guidance <your prompt>
Esto se aplica a los IDE potenciados por IA que aceptan npx skills add <skill-extension>.
Diagnostica el código "alucinado" o las implementaciones supuestas
Esta es una situación común en la que el modelo LLM completa las brechas de conocimiento sin previo aviso. Para evitar que el agente invente información, descubrimos que agregar la siguiente instrucción a tus instrucciones es muy útil
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Diagnostica la falla para activar una orientación específica
Si segmentas un caso de uso de función específico y no ves que el agente lo descubra, asegúrate de que tus instrucciones incluyan palabras clave específicas y requisitos de anclaje para que se pueda descubrir correctamente. Esto ayuda al agente a identificar la ruta de orientación pertinente (por ejemplo, "transiciones de vista" o "optimización de LCP").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Haz un seguimiento del proceso de pensamiento del agente:
- Sigue si descubrió la habilidad de la Guía de la Web moderna (por ejemplo,
modern-web/SKILL.md). - Ubica la llamada de búsqueda (por ejemplo,
node modern-web.mjs search "scroll snap") y determina si las palabras clave y las guías resultantes eran las que esperabas. La guía principal de los resultados de la búsqueda es la que se elige para aplicarla a tu instrucción.
/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`.
- Ejecuta el comando de búsqueda para obtener guías pertinentes:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnostica las alternativas faltantes para ciertas funciones del navegador web
Esto depende del estado de referencia que hayas establecido en tu proyecto. Si la API se lanzó recientemente, es posible que el agente no tenga una alternativa equivalente en la que basarse, o bien es una función que ha estado disponible de forma generalizada durante el tiempo suficiente como para que no sean necesarias alternativas ni polyfills.
Diagnostica el sesgo de datos de entrenamiento desactualizados
Si el agente sugiere una biblioteca más antigua en lugar de una API de navegador moderna, es probable que se base en sus datos de entrenamiento básicos o que tu estado de Baseline esté configurado para que aún no admita esa función y se haya implementado la alternativa.
Para volver a verificar, puedes forzar la prioridad de la habilidad buscando explícitamente la biblioteca de orientación con la CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnostica la orientación desactualizada
Es de suma importancia que nuestra información esté actualizada, por lo que te pedimos que registres un problema en el repositorio si encuentras código que se implementó a partir de una guía desactualizada. Cuando lo hagas, recopila pruebas de que el agente te recomienda la habilidad modern-web y sus guías en lugar de los datos de entrenamiento básicos del modelo LLM que podría usar tu IDE potenciado por IA.
En la ventana o terminal del agente, es posible que puedas hacer un seguimiento de su pensamiento, pero también puedes pedirle que te informe cómo llegó a la conclusión del cambio de código. Una vez que llegues a la conclusión de que, en efecto, proviene de la habilidad, envíanos esos comentarios y pruebas.
Comentarios
Si tienes preguntas o comentarios adicionales sobre estas funciones nuevas, primero lee cómo contribuir a la Guía de la Web moderna antes de registrar un problema en nuestro repositorio de GitHub. Mientras creas el problema, proporciona las instrucciones iniciales del agente, las capturas de pantalla y los registros del proceso de pensamiento del agente, y el cambio de código final recomendado en función de ese pensamiento.