Si bien Modern Web Guidance 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 garantizar que tus instrucciones activen correctamente la habilidad Modern Web 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 presentes un problema para ayudarnos a mantener estos recursos precisos y eficaces.
Diagnostica que tu agente no use Modern Web Guidance
Cuando se instala Modern Web Guidance, se les indica a los agentes que lo usen para cualquier tarea de desarrollo web. Sin embargo, a veces los agentes ignoran estas instrucciones.
Puedes indicarle explícitamente al agente que use Modern Web Guidance agregando una frase como "use modern-web-guidance" al final de tu instrucción.
Algunos agentes también admiten la invocación directa de una habilidad con una sintaxis específica, como /modern-web-guidance o $modern-web-guidance, según el agente.
Si no estás seguro, consulta la documentación de tu agente o pregúntale cómo invocar directamente la habilidad modern-web-guidance.
Diagnostica código "alucinado" o implementaciones adivinadas
Esta es una situación común en la que el 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 guía específica
Si te diriges a un caso de uso de una función específica y no ves que el agente la 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 guía pertinente (por ejemplo, "transiciones de vista" o "optimización de LCP").
Haz un seguimiento del proceso de pensamiento del agente:
- Verifica el resultado para ver si invocó la habilidad
modern-web-guidance. - Ubica la llamada de búsqueda (por ejemplo,
npx -y modern-web-guidance@latest search "carousel scroll snap") y determina si las palabras clave y las guías resultantes eran las que esperabas. - Verifica que la llamada de recuperación haya solicitado la guía pertinente, por ejemplo:
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));
}
- También puedes ejecutar los comandos de búsqueda en la terminal para ver qué guías coinciden con tu consulta de búsqueda.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
Comentarios
Si tienes preguntas o comentarios adicionales sobre estas funciones nuevas, primero lee cómo contribuir a Modern Web Guidance antes de presentar un problema en nuestro repositorio de GitHub. Mientras creas el problema, proporciona las instrucciones iniciales del agente, capturas de pantalla y registros del proceso de pensamiento del agente, y el cambio de código final recomendado en función de ese pensamiento.