Meskipun Panduan Web Modern bertujuan untuk mengarahkan pengembangan Anda ke pendekatan "benar secara default", Anda mungkin sesekali mengalami masalah dengan aktivasi agen, akurasi penerapan, atau penemuan fitur. Bagian ini memberikan langkah-langkah diagnostik untuk membantu Anda mengatasi tantangan umum, seperti memastikan kemampuan Web Modern dipicu dengan benar oleh perintah Anda atau memverifikasi bahwa penggantian kode selaras dengan status Dasar yang ditetapkan project Anda. Jika Anda mengalami kendala teknis yang terus-menerus atau mengidentifikasi panduan yang sudah tidak berlaku, sebaiknya ajukan masalah untuk membantu kami menjaga akurasi dan efektivitas referensi ini.
Mendiagnosis Kemampuan Web Modern yang tidak diambil oleh agen
Setiap perintah yang telah menginstal ekstensi kemampuan harus dapat mengaktifkannya dengan menyertakan "panduan web modern" dengan cara tertentu, tetapi jika karena alasan tertentu agen yang Anda gunakan mengalami kesulitan, Anda dapat langsung memanggilnya seperti berikut:
/modern-web-guidance <your prompt>
Hal ini berlaku untuk IDE yang didukung AI yang menerima npx skills add <skill-extension>.
Mendiagnosis kode "halusinasi" atau penerapan yang ditebak
Hal ini sering terjadi ketika model LLM mengisi kesenjangan pengetahuan tanpa peringatan. Untuk mencegah agen mengarang informasi, kami menemukan bahwa menambahkan petunjuk berikut ke perintah Anda sangat membantu
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
Mendiagnosis kegagalan memicu panduan tertentu
Jika Anda menargetkan kasus penggunaan fitur tertentu dan Anda tidak melihatnya ditemukan oleh agen, pastikan perintah Anda menyertakan kata kunci tertentu dan persyaratan utama untuk keterdeteksian yang tepat. Hal ini membantu agen mengidentifikasi jalur panduan yang relevan (misalnya: "transisi tampilan", "pengoptimalan LCP").
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
Lacak proses pemikiran agen:
- Ikuti jika agen menemukan kemampuan Panduan Web Modern (misalnya,
modern-web/SKILL.md). - Temukan panggilan penelusuran—misalnya,
node modern-web.mjs search "scroll snap"—dan identifikasi apakah kata kunci dan panduan yang dihasilkan adalah yang Anda harapkan. Panduan teratas dari hasil penelusuran adalah panduan yang dipilih untuk diterapkan pada perintah Anda.
/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`.
- Jalankan perintah penelusuran untuk panduan yang relevan sendiri:
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
Mendiagnosis penggantian yang tidak ada untuk fitur browser web tertentu
Hal ini bergantung pada status Dasar yang telah Anda tetapkan dalam project Anda. Jika API baru saja dirilis, agen mungkin tidak memiliki penggantian yang setara untuk diandalkan, atau API tersebut adalah fitur yang telah tersedia "Dasar Luas" untuk waktu yang cukup lama sehingga penggantian atau polyfill mungkin tidak diperlukan.
Mendiagnosis bias data pelatihan yang sudah tidak berlaku
Jika agen menyarankan library yang lebih lama, bukan API browser modern, kemungkinan agen mengandalkan data pelatihan dasarnya atau status Dasar Anda dikonfigurasi untuk belum mendukung fitur tersebut dan penggantiannya telah diterapkan.
Untuk memeriksa ulang, Anda dapat memaksa kemampuan untuk diprioritaskan dengan menelusuri library panduan secara eksplisit menggunakan CLI:
# Search for a specific feature
npx modern-web-guidance search "<feature>"
Mendiagnosis panduan yang sudah tidak berlaku
Sangat penting bagi kami untuk memastikan informasi kami selalu terbaru. Oleh karena itu, sebaiknya ajukan masalah ke repositori jika Anda menemukan kode yang diterapkan dari panduan sudah tidak berlaku. Saat melakukannya, kumpulkan bukti bahwa agen merekomendasikan kepada Anda dari kemampuan modern-web dan panduannya, bukan data pelatihan dasar dari model LLM yang mungkin digunakan oleh IDE yang didukung AI Anda.
Di jendela atau terminal agen, Anda mungkin dapat melacak pemikirannya, tetapi Anda juga dapat memintanya untuk memberi tahu Anda bagaimana ia sampai pada kesimpulan perubahan kode. Setelah Anda menyimpulkan bahwa perubahan kode tersebut memang berasal dari kemampuan, berikan masukan dan bukti tersebut kepada kami.
Masukan
Jika Anda memiliki pertanyaan atau masukan tambahan tentang fitur baru ini, pertama-tama baca tentang cara berkontribusi ke Panduan Web Modern sebelum mengajukan masalah di repositori GitHub kami. Saat membuat masalah, berikan perintah agen awal, screenshot dan log proses pemikiran agen, serta perubahan kode akhir yang direkomendasikan berdasarkan pemikiran agen tersebut.