雖然「現代化網站指南」的目標是讓您的開發作業朝「預設正確」的方向邁進，但您有時可能會遇到代理程式啟動、實作準確度或功能探索方面的問題。本節提供診斷步驟，協助您解決常見問題，例如確保提示能正確觸發 Modern Web 技能，或驗證程式碼備援是否符合專案的既定基準狀態。如果遇到持續性的技術障礙或發現過時的指引，建議您提出問題，協助我們確保這些資源準確有效。
診斷代理程式未擷取新式網站技能
安裝技能擴充功能後，只要在提示中加入「現代網路指南」，就能啟動擴充功能。但如果使用的代理程式遇到困難，可以直接呼叫擴充功能，如下所示：
/modern-web-guidance <your prompt>
這適用於接受 npx skills add <skill-extension> 的 AI 輔助 IDE。
診斷「幻覺」程式碼或猜測的實作方式
LLM 模型通常會填補知識缺口，且不會發出警告。 為避免代理程式編造資訊，我們發現將下列指令附加至提示非常實用
Bring up knowledge gaps and don't attempt to guess implementation. List them as open questions."
診斷無法觸發特定指引的問題
如果您鎖定特定功能的使用情境，但代理程式未發現該情境，請確認提示包含特定關鍵字和錨點需求，確保代理程式能正確發現。這有助於代理程式找出相關的指引軌 (例如「檢視轉場效果」、「LCP 最佳化」)。
/modern-web-guidance Execute LCP optimization against my Progressive Web App.
追蹤代理程式的思考過程：
- 如果發現「現代化網頁指南」技能 (例如
modern-web/SKILL.md)，請按照指示操作。 - 找到搜尋呼叫 (例如
node modern-web.mjs search "scroll snap")，並確認關鍵字和產生的指南是否符合預期。搜尋結果中排名最前面的指南，就是系統為提示套用的指南。
/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`.
- 自行執行相關指南的搜尋指令：
# Search for relevant guides
npx modern-web-guidance@latest search "scroll snap"
診斷特定網頁瀏覽器功能是否缺少備援
這取決於您在專案中設定的基準狀態。如果 API 是最近才發布，代理程式可能沒有可依賴的同等備援，或者該功能已「廣泛支援基準」一段時間，因此可能不需要備援或 Polyfill。
診斷過時訓練資料的資料偏誤
如果代理程式建議使用舊版程式庫，而非新式瀏覽器 API，可能是因為代理程式依據的是基礎訓練資料，或是您的基準狀態設定為尚未支援該功能，因此實作了備援。
如要再次確認，您可以透過 CLI 明確搜尋指引程式庫，強制優先使用該技能：
# Search for a specific feature
npx modern-web-guidance search "<feature>"
診斷過時的指引
我們非常重視資訊的即時性，因此如果發現指南中實作的程式碼過時，請向存放區回報問題。這麼做時，請收集證據，證明代理程式向您推薦的內容來自 modern-web 技能和指南，而非 AI 輔助 IDE 可能使用的 LLM 模型基本訓練資料。
在代理程式視窗或終端機中，您或許可以追蹤代理程式的思考過程，但也可以要求代理程式說明程式碼變更結論的由來。確認是技能所致後，請將意見回饋和證據提供給我們。
意見回饋
如果您對這些新功能有任何其他問題或意見，請先瞭解如何為新版網頁指南貢獻心力，再於我們的 GitHub 存放區中提出問題。建立問題時，請提供初始代理程式提示、代理程式思考過程的螢幕截圖和記錄，以及根據該代理程式思考過程建議的最終程式碼變更。