Memecahkan Masalah Panduan Web Modern

Meskipun Panduan Web Modern bertujuan untuk mengarahkan pengembangan Anda ke pendekatan "benar secara default", Anda mungkin sesekali mengalami masalah terkait aktivasi agen, akurasi penerapan, atau penemuan fitur. Bagian ini memberikan langkah-langkah diagnostik untuk membantu Anda mengatasi tantangan umum, seperti memastikan skill Web Modern dipicu dengan benar oleh perintah Anda atau memverifikasi bahwa penggantian kode sesuai dengan status Dasar yang ditetapkan project Anda. Jika Anda mengalami kendala teknis yang terus-menerus atau menemukan panduan yang sudah tidak berlaku, sebaiknya laporkan masalah untuk membantu kami menjaga akurasi dan efektivitas referensi ini.

Mendiagnosis Panduan Web Modern yang tidak digunakan oleh agen Anda

Saat Panduan Web Modern diinstal, agen akan diinstruksikan untuk menggunakannya dalam tugas pengembangan web apa pun. Namun, terkadang agen mengabaikan petunjuk ini.

Anda dapat secara eksplisit menginstruksikan agen untuk menggunakan Panduan Web Modern dengan menambahkan frasa seperti "gunakan panduan web modern" di akhir perintah Anda.

Beberapa agen juga mendukung pemanggilan langsung skill menggunakan sintaksis tertentu, seperti /modern-web-guidance atau $modern-web-guidance, bergantung pada agennya.

Lihat dokumentasi agen Anda, atau tanyakan kepada agen Anda cara memanggil skill modern-web-guidance secara langsung jika tidak yakin.

Mendiagnosis kode yang "berhalusinasi" atau penerapan yang ditebak

Hal ini sering terjadi ketika LLM mengisi kesenjangan pengetahuan tanpa peringatan. Untuk mencegah agen mengarang informasi, kami mendapati 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 untuk memicu panduan tertentu

Jika Anda menargetkan kasus penggunaan fitur tertentu dan Anda tidak melihatnya ditemukan oleh agen, pastikan perintah Anda menyertakan kata kunci dan persyaratan penanda tertentu agar dapat ditemukan dengan benar. Hal ini membantu agen mengidentifikasi jalur panduan yang relevan (misalnya: "transisi tampilan", "pengoptimalan LCP").

Melacak proses berpikir agen:

  • Periksa output untuk melihat apakah keterampilan modern-web-guidance dipanggil.
  • Temukan panggilan penelusuran—misalnya, npx -y modern-web-guidance@latest search "carousel scroll snap"—dan identifikasi apakah kata kunci dan panduan yang dihasilkan adalah yang Anda harapkan.
  • Pastikan panggilan pengambilan meminta panduan yang relevan, misalnya: 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));
      }
  • Anda juga dapat menjalankan perintah penelusuran sendiri di terminal untuk melihat panduan yang cocok dengan kueri penelusuran Anda.
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"

Masukan

Jika ada pertanyaan atau masukan tambahan tentang fitur baru ini, baca cara berkontribusi pada Panduan Web Modern terlebih dahulu 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 tersebut.