Embora o Modern Web Guidance tenha como objetivo direcionar seu desenvolvimento para uma abordagem "correta por padrão", você pode encontrar problemas ocasionais com a ativação do agente, a precisão da implementação ou a descoberta de recursos. Esta seção oferece etapas de diagnóstico para ajudar você a resolver desafios comuns, como garantir que a habilidade do Modern Web seja acionada corretamente pelos comandos ou verificar se os fallbacks de código estão alinhados ao status de linha de base estabelecido do seu projeto. Se você encontrar obstáculos técnicos persistentes ou identificar orientações desatualizadas, recomendamos que registre um problema para nos ajudar a manter esses recursos precisos e eficazes.
Diagnosticar o Modern Web Guidance que não está sendo usado pelo seu agente
Quando o Modern Web Guidance está instalado, os agentes recebem instruções para usá-lo em todas as tarefas de desenvolvimento da Web. No entanto, às vezes, os agentes ignoram essas instruções.
Você pode instruir explicitamente o agente a usar o Modern Web Guidance anexando uma frase como "use modern-web-guidance" ao final do comando.
Alguns agentes também oferecem suporte à invocação direta de uma habilidade usando uma sintaxe específica, como /modern-web-guidance ou $modern-web-guidance, dependendo do agente.
Consulte a documentação do agente ou pergunte a ele como invocar diretamente a habilidade modern-web-guidance se não tiver certeza.
Diagnosticar código "alucinado" ou implementações adivinhadas
Essa é uma ocorrência comum em que o LLM preenche lacunas de conhecimento sem aviso. Para evitar que o agente invente informações, descobrimos que anexar a instrução a seguir aos comandos é muito útil:
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
Diagnosticar falha ao acionar orientações específicas
Se você estiver segmentando um caso de uso de recurso específico e não estiver vendo ele ser descoberto pelo agente, verifique se os comandos incluem palavras-chave específicas e requisitos de âncora para a descoberta adequada. Isso ajuda o agente a identificar a faixa de orientação relevante (por exemplo, "transições de visualização", "otimização de LCP").
Acompanhe o processo de pensamento do agente:
- Verifique a saída para saber se ela invocou a habilidade
modern-web-guidance. - Localize a chamada de pesquisa, por exemplo,
npx -y modern-web-guidance@latest search "carousel scroll snap", e identifique se as palavras-chave e os guias resultantes eram os esperados. - Verifique se a chamada de recuperação solicitou o guia relevante, por exemplo:
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));
}
- Você também pode executar os comandos de pesquisa no terminal para ver quais guias correspondem à sua consulta de pesquisa.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
Feedback
Se você tiver outras dúvidas ou feedback sobre esses novos recursos, primeiro leia sobre como contribuir com o Modern Web Guidance antes de registrar um problema no nosso repositório do GitHub. Ao criar o problema, forneça os comandos iniciais do agente, capturas de tela e registros do processo de pensamento do agente e a mudança de código final recomendada com base nesse pensamento.