Sebbene la Guida web moderna miri a spostare lo sviluppo verso un approccio "corretto per impostazione predefinita", potresti occasionalmente riscontrare problemi con l'attivazione dell'agente, l'accuratezza dell'implementazione o l'individuazione delle funzionalità. Questa sezione fornisce passaggi di diagnostica per aiutarti a risolvere le sfide comuni, ad esempio assicurarti che la skill web moderna venga attivata correttamente dai prompt o verificare che i fallback del codice siano in linea con lo stato di base stabilito del tuo progetto. Se riscontri ostacoli tecnici persistenti o identifichi linee guida obsolete, ti invitiamo a segnalare un problema per aiutarci a mantenere queste risorse accurate ed efficaci.
Diagnosticare la skill web moderna non rilevata dall'agente
Qualsiasi prompt che abbia installato l'estensione della skill dovrebbe essere in grado di attivarla includendo in qualche modo "guida web moderna", ma se per qualche motivo l'agente che stai utilizzando ha difficoltà, puoi chiamarla direttamente come segue:
/modern-web-guidance <your prompt>
Questo è applicabile agli IDE basati su AI che accettano npx skills add <skill-extension>.
Diagnosticare codice "allucinato" o implementazioni ipotizzate
Si tratta di un evento comune in cui il modello LLM colma le lacune di conoscenza senza preavviso. Per impedire all'agente di inventare informazioni, abbiamo scoperto che aggiungere la seguente istruzione ai prompt è molto utile
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Diagnosticare l'impossibilità di attivare una guida specifica
Se stai prendendo di mira un caso d'uso di funzionalità specifico e non vedi che viene rilevato dall'agente, assicurati che i prompt includano parole chiave specifiche e requisiti di ancoraggio per una corretta rilevabilità. Aiuta l'agente a identificare il percorso della guida pertinente (ad esempio: "transizioni di visualizzazione", "ottimizzazione LCP").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Tieni traccia del processo di pensiero dell'agente:
- Segui se ha rilevato la skill della Guida web moderna (ad esempio,
modern-web/SKILL.md). - Individua la chiamata di ricerca, ad esempio
node modern-web.mjs search "scroll snap", e verifica se le parole chiave e le guide risultanti sono quelle che ti aspettavi. La guida più importante nei risultati di ricerca è quella scelta per essere applicata al prompt.
/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`.
- Esegui tu stesso il comando di ricerca per le guide pertinenti:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Diagnosticare i fallback mancanti per determinate funzionalità del browser web
Si basa sullo stato di base che hai impostato nel tuo progetto. Se l'API è stata rilasciata di recente, l'agente potrebbe non avere un fallback equivalente su cui fare affidamento oppure è una funzionalità che è stata "Base ampiamente" disponibile per un periodo di tempo sufficientemente lungo da non richiedere fallback o polyfill.
Diagnosticare il bias dei dati di addestramento obsoleti
Se l'agente suggerisce una libreria precedente anziché un'API del browser moderna, è probabile che si basi sui dati di addestramento di base o che lo stato di base sia configurato in modo da non supportare ancora la funzionalità e che sia stato implementato il fallback.
Per ricontrollare, puoi forzare la skill a dare la precedenza cercando esplicitamente la libreria di guide utilizzando la CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Diagnosticare le guide obsolete
È di fondamentale importanza che le nostre informazioni siano aggiornate, pertanto ti chiediamo gentilmente di segnalare un problema nel repository se trovi codice implementato da una guida non aggiornata. In questo caso, raccogli le prove che l'agente ti sta consigliando provengano dalla skill modern-web e dalle relative guide anziché dai dati di addestramento di base del modello LLM che l'IDE basato su AI potrebbe utilizzare.
Nella finestra o nel terminale dell'agente, potresti essere in grado di monitorare il suo ragionamento, ma puoi anche chiedergli di informarti su come è arrivato alla conclusione della modifica del codice. Una volta giunto alla conclusione che si tratta effettivamente della skill, inviaci il feedback e le prove.
Feedback
Se hai ulteriori domande o feedback su queste nuove funzionalità, prima leggi come contribuire alla Guida web moderna prima di segnalare un problema nel nostro repository GitHub. Durante la creazione del problema, fornisci i prompt iniziali dell'agente, gli screenshot e i log del processo di pensiero dell'agente e la modifica del codice finale consigliata in base a questo ragionamento.