虽然现代 Web 指南旨在引导您采用“默认正确”的开发方法，但您有时可能会遇到代理激活、实现准确性或功能发现方面的问题。本部分提供了一些诊断步骤，可帮助您解决常见问题，例如确保 Modern Web 技能能够通过提示正确触发，或验证代码回退是否与项目的既定基准状态保持一致。如果您遇到持续的技术障碍或发现过时的指南，建议您提交问题，帮助我们保持这些资源的准确性和有效性。
诊断代理未识别现代 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.
跟踪智能体的思考过程：
- 如果发现了“现代 Web 指南”技能（例如
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"
诊断某些 Web 浏览器功能缺少后备方案的问题
这取决于您在项目中设置的基准状态。如果 API 是最近发布的，代理可能没有可依赖的等效回退，或者该功能已“广泛基准化”足够长的时间，因此可能不需要回退或填充。
诊断过时的训练数据偏见
如果代理建议使用旧版库而不是现代浏览器 API，则可能是因为代理依赖于其基本训练数据，或者您的Baseline 状态配置为尚不支持该功能，因此实现了回退。
如需仔细检查，您可以使用 CLI 显式搜索指导库，强制使技能优先：
# Search for a specific feature
npx modern-web-guidance search "<feature>"
诊断过时的指南
确保我们的信息是最新的至关重要，因此，如果您发现根据指南实现的代码已过时，请向代码库提交问题。在执行此操作时，请收集证据，证明智能体向您推荐的内容来自 modern-web 技能及其指南，而不是 AI 赋能的 IDE 可能使用的 LLM 模型中的基本训练数据。
在代理窗口或终端中，您或许可以跟踪其思考过程，但也可以要求代理告知您它是如何得出代码更改结论的。如果您最终确定该反馈确实来自技能，请将该反馈和证据传递给我们。
反馈
如果您对这些新功能有任何其他问题或反馈，请先了解如何为“现代 Web 指南”做出贡献，然后再在我们的 GitHub 代码库中提交问题。创建问题时，请提供初始代理提示、代理思考过程的屏幕截图和日志，以及根据代理思考过程推荐的最终代码更改。