雖然 Modern Web Guidance 的目標是讓開發作業朝向「預設正確」的方向發展，但您有時可能會遇到代理啟用、實作準確度或功能探索方面的問題。本節提供診斷步驟，協助您解決常見問題，例如確保提示正確觸發 Modern Web 技能，或確認程式碼備用方案符合專案既定的基準狀態。如果遇到持續發生的技術問題，或發現指南內容過時，歡迎回報問題，協助我們確保這些資源準確有效。
診斷代理未使用的Modern Web Guidance
安裝 Modern Web Guidance 後，代理會收到指示，使用該工具執行任何網頁程式開發人員工作。不過，代理有時會忽略這些指示。
您可以在提示詞結尾加上「使用 modern-web-guidance」等詞組，明確指示代理使用 Modern Web Guidance。
部分代理也支援使用特定語法直接叫用技能，例如 /modern-web-guidance 或 $modern-web-guidance，具體取決於代理。
請參閱代理程式的說明文件，或詢問代理程式如何直接叫用 modern-web-guidance 技能 (如果不確定)。
診斷「幻覺」程式碼或猜測的實作方式
這是常見的情況，LLM 會在沒有警告的情況下填補知識落差。為避免代理捏造資訊，我們發現將下列指令附加至提示非常實用：
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions.
診斷無法觸發特定指引的問題
如果您指定特定功能用途，但代理未偵測到該用途，請確保提示包含特定關鍵字和錨定需求，以便正確偵測。這有助於代理找出相關的指南軌跡 (例如「檢視轉換」、「LCP 最佳化」)。
追蹤代理的思考過程：
- 查看輸出內容，確認是否叫用
modern-web-guidance技能。 - 找出搜尋呼叫 (例如
npx -y modern-web-guidance@latest search "carousel scroll snap")，並確認關鍵字和產生的指南是否符合預期。 - 確認擷取呼叫要求了相關指南，例如：
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));
}
- 您也可以在終端機中自行執行搜尋指令，查看哪些指南符合搜尋查詢。
# Search for relevant guides
npx modern-web-guidance@latest search "carousel scroll snap"
意見回饋
如果您對這些新功能有任何其他問題或意見，請先瞭解如何為 Modern Web Guidance 做出貢獻，然後再前往 GitHub 存放區回報問題。建立問題時，請提供初始代理提示、代理思考過程的螢幕截圖和記錄，以及根據該思考過程建議的最終程式碼變更。