雖然「新式網站指南」旨在引導您採用「預設正確」的開發方式，但您有時可能會遇到代理程式啟動、實作準確度或功能探索方面的問題。本節提供診斷步驟，協助您解決常見問題，例如確保提示能正確觸發 Modern Web 技能，或驗證程式碼備援是否符合專案的既定基準狀態。如果遇到持續性的技術障礙或發現過時的指引，建議您提出問題，協助我們確保這些資源準確有效。
診斷代理程式未使用 Modern Web Guidance 的問題
安裝 Modern Web Guidance 後，代理程式就會收到指令，在執行任何網頁開發工作時使用這項工具。不過，有時服務專員會忽略這些指示。
如要明確指示代理程式使用新版網頁指南，請在提示結尾加上「use 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 存放區中提出問題。建立問題時，請提供初始代理提示、代理思考過程的螢幕截圖和記錄，以及根據該思考過程建議的最終程式碼變更。