Sebbene Modern Web Guidance miri a orientare lo sviluppo verso un approccio "corretto per impostazione predefinita", occasionalmente potresti riscontrare problemi con l'attivazione dell'agente, l'accuratezza dell'implementazione o il rilevamento delle funzionalità. Questa sezione fornisce i passaggi diagnostici per aiutarti a risolvere i problemi più comuni, ad esempio assicurarti che la skill Modern Web venga attivata correttamente dai prompt o verificare che i fallback del codice siano in linea con lo stato Baseline stabilito del progetto. Se riscontri ostacoli tecnici persistenti o identifichi indicazioni obsolete, ti invitiamo a segnalare un problema per aiutarci a mantenere queste risorse accurate ed efficaci.
Diagnostica il mancato utilizzo di Modern Web Guidance da parte dell'agente
Quando Modern Web Guidance è installato, gli agenti sono istruiti a utilizzarlo per qualsiasi attività di sviluppo web. Tuttavia, a volte gli agenti ignorano queste istruzioni.
Puoi indicare esplicitamente all'agente di utilizzare Modern Web Guidance aggiungendo una frase come "utilizza modern-web-guidance" alla fine del prompt.
Alcuni agenti supportano anche l'attivazione diretta di una skill utilizzando una sintassi specifica, come /modern-web-guidance o $modern-web-guidance, a seconda dell'agente.
Consulta la documentazione dell'agente o chiedi all'agente come richiamare direttamente la skill modern-web-guidance se non hai la certezza di come fare.
Diagnostica il codice "allucinato" o le implementazioni indovinate
Si tratta di un evento comune in cui l'LLM colma le lacune di conoscenza senza preavviso. Per evitare che l'agente inventi informazioni, abbiamo scoperto che è molto utile aggiungere la seguente istruzione ai prompt:
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
Diagnostica l'errore di attivazione di indicazioni specifiche
Se hai scelto come target un caso d'uso specifico di una funzionalità 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 di guida pertinente (ad esempio: "transizioni di visualizzazione", "ottimizzazione LCP").
Monitora il processo di ragionamento dell'agente:
- Controlla l'output per vedere se ha richiamato la skill
modern-web-guidance. - Individua la chiamata di ricerca, ad esempio
npx -y modern-web-guidance@latest search "carousel scroll snap", e identifica se le parole chiave e le guide risultanti erano quelle previste. - Verifica che la chiamata di recupero abbia richiesto la guida pertinente, ad esempio:
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));
}
- Puoi anche eseguire i comandi di ricerca nel terminale per vedere quali guide corrispondono alla tua query di ricerca.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
Feedback
Se hai altre domande o feedback su queste nuove funzionalità, leggi prima come contribuire a Modern Web Guidance 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 finale del codice consigliata in base a questo pensiero.