Sebbene Modern Web Guidance miri a spostare lo sviluppo verso un approccio "corretto per impostazione predefinita", a volte potresti riscontrare problemi con l'attivazione dell'agente, l'accuratezza dell'implementazione o l'individuazione delle funzionalità. Questa sezione fornisce passaggi diagnostici per aiutarti a risolvere le sfide comuni, ad esempio assicurarti che la competenza Modern Web venga attivata correttamente dai prompt o verificare che i fallback del codice siano in linea con lo stato di base 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.
Diagnosticare l'utilizzo di Modern Web Guidance da parte dell'agente
Quando Modern Web Guidance è installato, agli agenti viene chiesto di utilizzarlo per tutte le attività di sviluppo web. Tuttavia, a volte gli agenti ignorano queste istruzioni.
Puoi chiedere esplicitamente all'agente di utilizzare Modern Web Guidance aggiungendo una frase come "use modern-web-guidance" alla fine del prompt.
Alcuni agenti supportano anche la chiamata diretta di una competenza utilizzando una sintassi specifica, ad esempio /modern-web-guidance o $modern-web-guidance, a seconda dell'agente.
In caso di dubbi, consulta la documentazione dell'agente o chiedi all'agente come chiamare direttamente la competenza modern-web-guidance.
Diagnosticare codice "allucinato" o implementazioni ipotizzate
Si tratta di un evento comune in cui l'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 indicazioni specifiche
Se stai prendendo di mira un caso d'uso di funzionalità specifico e non vedi che l'agente lo rileva, assicurati che i prompt includano parole chiave specifiche e requisiti di ancoraggio per una corretta rilevabilità. Aiuta l'agente a identificare il percorso di indicazioni pertinente (ad esempio: "transizioni di visualizzazione", "ottimizzazione LCP").
Tieni traccia del processo di pensiero dell'agente:
- Controlla l'output per verificare se ha chiamato la competenza
modern-web-guidance. - Individua la chiamata di ricerca, ad esempio
npx -y modern-web-guidance@latest search "carousel scroll snap", e verifica se le parole chiave e le guide risultanti sono quelle che ti aspettavi. - 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à, prima leggi 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 del codice finale consigliata in base a questo pensiero.