Embora o objetivo do Modern Web Guidance seja direcionar seu desenvolvimento para uma abordagem "correta por padrão", às vezes você pode encontrar problemas com a ativação do agente, a precisão da implementação ou a descoberta de recursos. Esta seção fornece etapas de diagnóstico para ajudar você a resolver desafios comuns, como garantir que a habilidade da Web moderna seja acionada corretamente pelos seus comandos ou verificar se os substitutos de código estão alinhados com o status de referência estabelecido do seu projeto. Se você encontrar problemas técnicos persistentes ou identificar orientações desatualizadas, registre um problema para nos ajudar a manter esses recursos precisos e eficazes.
Diagnosticar por que Modern Web Guidance não está sendo usado pelo agente
Quando o Modern Web Guidance é instalado, os agentes são instruídos a usá-lo para qualquer tarefa de desenvolvimento web. No entanto, às vezes os agentes ignoram essas instruções.
Você pode instruir explicitamente o agente a usar Modern Web Guidance adicionando uma frase como "use modern-web-guidance" ao final do comando.
Alguns agentes também aceitam a 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 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 prévio. Para evitar que o agente invente informações, descobrimos que anexar a seguinte instrução 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 ele não estiver sendo descoberto pelo agente, verifique se os comandos incluem palavras-chave específicas e requisitos de âncora para uma facilidade de 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 raciocínio do agente:
- Verifique a saída para ver 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, 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 final de código recomendada com base nesse pensamento.