Modern Web Guidance は、開発を「デフォルトで正しい」アプローチに移行することを目的としていますが、エージェントの有効化、実装の精度、機能の検出に関する問題が発生することがあります。このセクションでは、プロンプトによって Modern Web スキルが適切にトリガーされるようにする、コード フォールバックがプロジェクトの確立されたベースライン ステータスと一致していることを確認するなど、一般的な課題を解決するための診断手順について説明します。技術的な問題が解決しない場合や、古いガイダンスが見つかった場合は、これらのリソースの精度と有効性を維持するため、問題を報告していただくようお願いいたします。
エージェントが Modern Web Skill を取得しない問題を診断する
スキル拡張機能をインストールしたプロンプトは、なんらかの方法で「最新のウェブ ガイダンス」を含めることで、スキル拡張機能を有効にできるはずです。ただし、使用しているエージェントで問題が発生している場合は、次のように直接呼び出すことができます。
/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 Guidance スキル（
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 が最近リリースされたばかりの場合、エージェントが依存できる同等のフォールバックがない可能性があります。また、フォールバックやポリフィルが不要になるほど長い間「Baseline Widely」で利用可能になっている機能である可能性もあります。
古いトレーニング データのデータバイアスを診断する
エージェントが最新のブラウザ API ではなく古いライブラリを提案する場合、エージェントがベースのトレーニング データに依存しているか、ベースライン ステータスがその機能をまだサポートしないように構成されており、フォールバックが実装されている可能性があります。
念のため、CLI を使用してガイダンス ライブラリを明示的に検索し、スキルを優先するように強制できます。
# Search for a specific feature
npx modern-web-guidance search "<feature>"
古いガイダンスを診断する
Google の情報は最新の状態に保つことが非常に重要です。ガイドに沿って実装されたコードが古い場合は、リポジトリで問題を報告していただきますようお願いいたします。その際は、エージェントが推奨する内容が、AI 搭載 IDE が使用している可能性のある LLM モデルの基本トレーニング データではなく、modern-web スキルとそのガイドから得られたものであることを示す証拠を収集します。
エージェント ウィンドウまたはターミナルで、エージェントの思考を追跡できる場合がありますが、コード変更の結論に至った経緯を説明するように求めることもできます。スキルからのフィードバックであると判断した場合は、そのフィードバックと証拠を Google に送信してください。
フィードバック
これらの新機能についてご質問やフィードバックがある場合は、まず Modern Web Guidance への投稿方法をお読みになってから、Github リポジトリで問題を報告してください。問題を作成する際に、エージェントの最初のプロンプト、エージェントの思考プロセスのスクリーンショットとログ、エージェントの思考に基づいて推奨される最終的なコード変更を提供します。