Embora o Modern Web Guidance tenha como objetivo mover seu desenvolvimento para uma abordagem "correta por padrão", ocasionalmente você pode encontrar problemas com a ativação do agente, a acurácia 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 "Web moderna" seja acionada corretamente pelos comandos ou verificar se os substitutos de código estão alinhados ao status de base estabelecido do seu projeto. Se você encontrar obstáculos técnicos persistentes ou identificar orientações desatualizadas, envie um problema para nos ajudar a manter esses recursos precisos e eficazes.
Diagnosticar se a habilidade Modern Web não está sendo detectada pelo agente
Qualquer comando que tenha instalado a extensão de habilidade pode ativá-la usando "orientação da Web moderna" de alguma forma. No entanto, se o agente que você está usando tiver dificuldades, é possível chamar a extensão diretamente assim:
/modern-web-guidance <your prompt>
Isso se aplica a ambientes de desenvolvimento integrado com tecnologia de IA que aceitam npx skills add <skill-extension>.
Diagnosticar código "alucinado" ou implementações presumidas
Isso é comum quando o modelo de LLM preenche as lacunas de conhecimento sem aviso prévio. Para evitar que o agente invente informações, descobrimos que adicionar 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 falhas ao acionar orientações específicas
Se você estiver segmentando um caso de uso de recurso específico e não estiver vendo o agente descobrir esse recurso, verifique se seus comandos incluem palavras-chave específicas e requisitos de ancoragem para uma 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").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Acompanhe o processo de raciocínio do agente:
- Siga se ele descobriu a habilidade de orientação da Web moderna (por exemplo,
modern-web/SKILL.md). - Localize a chamada de pesquisa, por exemplo,
node modern-web.mjs search "scroll snap", e identifique se as palavras-chave e os guias resultantes eram os esperados. O guia mais relevante dos resultados da pesquisa é o escolhido para ser aplicado ao seu comando.
/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`.
- Execute o comando de pesquisa para guias relevantes:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnosticar substituições ausentes para determinados recursos do navegador da Web
Isso depende do status de linha de base definido no projeto. Se a API foi lançada recentemente, o agente talvez não tenha um substituto equivalente para usar. Ou talvez seja um recurso que está "amplamente disponível" há tempo suficiente para que substitutos ou polyfills não sejam necessários.
Diagnosticar o viés nos dados de treinamento desatualizados
Se o agente sugerir uma biblioteca mais antiga em vez de uma API de navegador moderna, é provável que ele esteja usando os dados de treinamento básicos ou que seu status de linha de base esteja configurado para ainda não oferecer suporte a esse recurso e o fallback tenha sido implementado.
Para verificar novamente, force a habilidade a ter precedência pesquisando explicitamente a biblioteca de orientação usando a CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnosticar orientações desatualizadas
É muito importante que nossas informações estejam atualizadas. Por isso, pedimos que você registre um problema no repositório se encontrar um código implementado de um guia que esteja desatualizado. Ao fazer isso, reúna evidências de que a recomendação do agente é da habilidade modern-web e dos guias dela, em vez dos dados de treinamento básicos do modelo de LLM que seu IDE com tecnologia de IA pode estar usando.
Na janela ou no terminal do agente, é possível acompanhar o raciocínio dele, mas também pedir que ele informe como chegou à conclusão da mudança no código. Depois de concluir que o problema é da skill, envie o feedback e as evidências para nós.
Feedback
Se você tiver outras dúvidas ou feedback sobre esses novos recursos, primeiro leia sobre como contribuir com as orientações da Web moderna 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, além da mudança de código final recomendada com base nesse pensamento.