modern-web-guidance

Modern Web Guidance

用於搜尋特定 Web 開發使用情境並擷取其相應最佳做法指南的 Skill。

使用時機

必須使用此 Skill 的時機：

• 在開始實作任何網頁功能的初期。
• 在建立新元件之前，先確認是否已有標準化的模式存在。
• 避免實作臨時湊合的解決方案或載入不必要的大型相依套件。

使用說明

步驟 1. 搜尋使用情境

使用 search 指令，搭配摘要說明你想達成目標的行動導向查詢。直接透過 npx 執行 modern-web-guidance。

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_05_16-c5e78707

範例輸出：

[
  {
    "id": "optimize-image-priority",
    "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.",
    "category": "performance",
    "featuresUsed": [ "Fetch priority" ],
    "tokenCount": 985,
    "similarity": 0.7289
  },
  {
    "id": "defer-rendering-heavy-content",
    "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.",
    "category": "performance",
    "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ],
    "tokenCount": 1250,
    "similarity": 0.6961
  }
]

注意：若搜尋結果不明確、未匹配到任何結果，或相似度分數偏低，請執行 list 指令以瀏覽所有指南：

npx -y modern-web-guidance@latest list

---

步驟 2. 擷取最佳做法

從搜尋結果中取得相關的 id 後，使用 retrieve 指令呼叫此腳本以取得完整的指南。你可以傳入以逗號分隔的多個 ID。

npx -y modern-web-guidance@latest retrieve "<id>"

範例輸出：
說明實作步驟的指南 Markdown 內容...

使用 npx

• 重要須知：在 Windows 系統上，使用 npx 可能會失敗。請改用 npx.cmd ...。
• 擷取任務所需的 npm 套件時需要網路連線。
• 若 npx -y modern-web-guidance… 指令無回應（卡住），可能代表你目前處於離線狀態。請嘗試以離線模式重新執行：npx --offline …。
• --skill-version 旗標用於判斷此 SKILL.md 是否已過期。若已過期，系統會將警告訊息記錄至 stderr。

指導原則

• 務必最先進行搜尋，以找到最相關的指南。
• 這些指南通常與框架無關（framework-agnostic）；請將其正確套用至你的專案環境中。
• 切勿憑空捏造指南或忽略指南；它們代表了使用者專案中偏好的本機規範。

解讀瀏覽器支援度與備用方案（Fallbacks）

• 預設行為：所有指南皆假設 Baseline 通用可用（Widely available） 的功能皆可安全使用，無需提供備用方案（fallbacks）。對於尚未達到 Baseline 通用可用的功能，你必須遵循指南中的備用方案建議，除非使用者已指定自訂的瀏覽器支援政策。

• 自訂政策：若使用者已定義明確的瀏覽器支援需求，請利用指南中的瀏覽器相容性資料來判斷是否可以安全地忽略備用方案。

  • 對於目標為 Baseline YYYY 的功能，若其 "Baseline since" 日期 <= YYYY，即代表符合該目標。
  • 政策範例：
    • "不實作功能備用方案。"（適用於前沿網頁技術的探索性原型）
    • "Safari 17.4+"（適用於針對 macOS 或基於 Tauri 之桌面應用程式的內部工具）
    • "切勿推薦或實作 polyfills；若核心功能需要 Baseline 新近可用（Newly Available）的功能，請提供輕量級的自訂備用方案或重新設計實作方式。"（以最小化打包體積並避免技術債）
    • "假設環境為現代執行環境，只要有嚴格進行功能檢測（feature detection）且能優雅降級，即可原生使用 Baseline 新近可用的功能。"（適用於漸進增強策略）

• 主動探索政策：留意環境中的線索，適時建議在 CLAUDE.md 或 AGENTS.md 中記錄政策。若開發者出現以下情況，建議主動提出：

  • 提及針對受限的執行階段進行開發（例如 Electron 或 Tauri）。
  • 明確排除特定的目標平台（例如「我們不支援 Desktop Chrome」）。
  • 對 polyfill 的複雜度、打包體積或效能成本感到猶豫。
  • 詢問某個功能在沒有備用方案的情況下是否可以安全使用。

  無固定定義的政策格式。以下為參考範例：**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.