【2026 最新】Modern Web Guidance 教學：Claude Code 改完怎麼驗收？Baseline、三引擎與 fallback 五步走

你請 Claude Code 把舊網站改成新寫法，它刪掉一串 JavaScript，畫面在自己的電腦看起來也正常。可是，換到另一個瀏覽器、用鍵盤操作，或遇到比較舊的手機時，留言框還能順利使用嗎？Modern Web Guidance 教學要回答的，就是「改得新」之後，怎麼知道真的可用。

Google Chrome 團隊在 2026 年 11 月 10 日發布 Modern Web Guidance 1.0，把網頁平台指引與相容性資料交給寫程式的 Agent。本篇專為第一次接觸前端驗收的讀者寫：先用白話建立觀念，再用一個留言框走完對照、掃描、漸進增強與三引擎測試。程式段落可交給 Agent 建立，但驗收條件由你先決定。

以下交付的是可照做的評估方法與最小練習程式，不預填 Claude Code 有／無 Skill 的勝負，也不把三引擎測試描述成已完成的成績。官方繁中 Codelab 已有入門材料；這裡把重點放在改造之後的驗收與撤回。

先說結論：可交付改造＝新指引＋相容目標＋行為驗收

Skill 像是交給裝修師傅的施工手冊，Baseline 是房子的適用條件，測試則是逐扇門實際開關。手冊可以改善選材，卻不能替你的房子完成驗收。你要保留三份證據：改了什麼、哪些使用者在支援範圍內、同一個操作是否仍能完成。

先選一個低風險元件，例如留言框。讓支援新 CSS 的瀏覽器自動長高；其餘環境仍保留固定高度、捲動與手動調整。這就是「漸進增強」：先交付基本功能，再疊上有條件的便利。

一、Modern Web Guidance 教學：先認清三個零件

①「查手冊」：Skill、模型、瀏覽器各做不同工作

Modern Web Guidance 是讓編碼 Agent 查找網頁實作指引的一組技能。模型負責讀程式、提出改法；瀏覽器負責執行；測試負責檢查你要求的行為。它不會因為被安裝，就把既有網站自動變成跨瀏覽器合格作品。想先理解 Skill 的檔案與載入方式，可讀 Agent Skill 與 SKILL.md 入門。

②「看適用範圍」：Baseline 不是所有人的瀏覽器

Baseline 官方定義的 Newly available，代表功能已在核心瀏覽器集合互通；Widely available 則是從互通起經過 30 個月。核心集合包含桌面與 Android 的 Chrome、Firefox，以及 Edge、macOS 與 iOS 的 Safari。它提供功能採用的共同語言；你的舊裝置、嵌入式 WebView 與無障礙使用情境，仍應列成自己的支援條件。

把「能不能用」問到功能層級。例如 MDN 的 field-sizing 頁面在 2026 年 11 月 12 日查閱時標為 Baseline 2026／Newly available。這和某個更早日期的 Firefox 討論，可以同時各自正確。不要用一段舊留言推論今天整個瀏覽器都不支援，也不要用最新引擎的成功代表所有舊版本。

③「現場開門」：三引擎與實際產品還要分開

Playwright 可跑 Chromium、Firefox、WebKit。引擎是顯示與執行網頁的核心，瀏覽器產品還包含自己的版本、系統整合與設定。尤其 Playwright 的 WebKit 來自 WebKit 主線，可能早於 Safari 正式版；它的 Firefox 也使用測試所需的修補版本。三引擎通過，是這三個指定建置的證據；正式 Safari、手機實機與你承諾支援的舊版本，另留驗收列。

二、Modern Web Guidance 教學實作：五步改一個留言框

第 1 步：「兩組真的一樣嗎？」先保存起點

拿自己有權測試的小型前端，另建練習資料夾或 Git 分支。保留原始 commit、套件鎖定檔與一份固定提示，建立 A、B 兩份相同副本。A 不載入這個 Skill；B 才加入它。不要讓 B 讀過 A 的建議後再說是獨立比較；兩組開新工作階段，MCP、其他技能與專案指令也要逐項對齊。

先執行 claude --version 與 node --version 保存工具版本。在 Claude Code 用 /model 選擇同一可用模型，並記下實際模型識別與 effort 設定；官方模型設定文件說明了別名與完整模型名稱的差別。別把會移動的預設別名當作永久版本鎖。若過程發生模型切換，該輪另記，不與原輪混算。

把需求寫成兩組共同的考卷：「只改留言框；保留標籤、鍵盤焦點與全部輸入；短文字與長文字都能編輯；不新增套件；保留基本可用路徑；先提出計畫再改檔。」這些是本次練習的限制，不是工具對所有專案的保證。

第 2 步：「要服務誰？」固定 Baseline 與版本

在練習專案的指令檔寫下 This project targets Baseline Widely available. Newer features require feature detection and a usable fallback.，並把具體最低瀏覽器版本另列出來。Modern Web Guidance 的預設指引以 Widely available 為安全起點；超出目標的功能，按對應 guide 處理 fallback。這個句子是本篇示範政策，應由你的使用者分布決定是否調整。

依 官方安裝方式，在 B 的專案目錄執行 npx modern-web-guidance@latest install，確認選的是此練習範圍。做版本對照時，同時記錄 npm 套件版本與安裝後的 Skill／guide 版本；安裝流程帶有更新機制，單記「裝過 1.0」不足以固定後續內容。Claude Code 也有官方列出的外掛安裝路徑；選一種即可，避免把全域安裝意外帶進 A。

依 Claude Code 的 Skill 載入規則確認技能來源。檢查個人、專案與外掛範圍，A 的隔離紀錄也要保存。只在提示寫「不要用 Skill」，卻讓兩組讀到不同的個人指令，會讓比較多出難以解釋的變因。

第 3 步：「掃描看到什麼？」先報告，再挑一項

在 B 先要求「掃描這個前端資料夾的 legacy patterns，依上下文確認，列出計畫，暫不改檔」。要直接取得機器可讀結果，可執行 npx modern-web-guidance@1.0.0 legacy-scan ./src --json > legacy-scan.json；把 ./src 換成練習前端的實際目錄。這條固定套件版的命令用於可重做的掃描，並不等於把整個 Agent 的後續查詢一起凍結。

1.0 的 modernization workflow會先找已知模式，再用 keepWhen／dropWhen 檢查上下文。掃描範圍是精選規則，不能把零項發現當成整站合格。若 scrollHeight 是捲動清單的必要計算，便不能只憑字面出現就刪掉；既有 fallback 也可能是刻意保留的。

本次選留言框的自動增高，接著用 npx modern-web-guidance@1.0.0 retrieve form-fields-automatically-fit-contents 讀完整指引。若原專案沒有這類模式，就直接查這份 guide 做練習，別為了湊掃描成果硬改其他元件。A 則從同一份原始碼，依共同需求提出自己的方案。

第 4 步：「新功能失效時呢？」先讓底層能用

下列最小頁面可存成 index.html。基本層保留四行留言框、捲動與調整尺寸；只有支援 field-sizing: content 的環境才加上自動高度。@supports 像門口驗票，檢查這個 CSS 宣告是否被理解；視覺行為仍由下一步驗收。

<!doctype html>
<html lang="zh-Hant">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>留言框練習</title>
<style>
  textarea {
    font: 1rem/1.5 system-ui;
    box-sizing: border-box;
    inline-size: 100%;
    min-block-size: 6rem;
    max-block-size: 18rem;
    overflow: auto;
    resize: vertical;
  }
  @supports (field-sizing: content) {
    html:not(.baseline) textarea {
      field-sizing: content;
      block-size: auto;
    }
  }
</style>
<script>
  if (new URLSearchParams(location.search).has('baseline')) {
    document.documentElement.classList.add('baseline');
  }
</script>
<label for="message">留言</label>
<textarea id="message" rows="4"></textarea>
<button type="button">下一步</button>
</html>

在這個刻意縮小的練習裡，?baseline=1 是關掉增強樣式的測試開關，並非冒充一個真正的舊瀏覽器。範例沒有提交到伺服器，按鈕用來測焦點順序。若產品規格要求舊版本也必須自動長高，就保留受測的 JavaScript fallback；本篇的「能輸入與捲動」退路，不能替代那項規格。

這份 CSS 的 min-block-size／max-block-size 是高度上下限，避免空白時太小、長文時無限撐長；固定橫向寬度則讓換行較穩定。官方留言框指引也要求留意全域高度、Grid／Flex 拉伸與上限。你要查的是專案裡真正生效的樣式，而非只看新加的那幾行。

第 5 步：「換引擎還能用嗎？」讓同一份考卷跑三次

在獨立練習專案用 npm init playwright@latest 建立測試，保留其產生的 Chromium、Firefox、WebKit 三個 projects，並保存鎖定檔。需要相符瀏覽器建置時執行 npx playwright install chromium firefox webkit；安裝後記錄 npx playwright --version、作業系統與實際 browser version。日後重做先用鎖定檔還原套件，再使用對應瀏覽器。

在另一個終端機、於 index.html 所在目錄執行 python3 -m http.server 4173 --bind 127.0.0.1。將下面檔案存為 tests/message.spec.ts，再執行 npx playwright test tests/message.spec.ts --trace on。兩種模式共用同一個測例；A、B 也各自執行同一份測例，避免只替 B 寫比較好過的考題。

import { test, expect } from '@playwright/test';

for (const suffix of ['', '?baseline=1']) {
  test(`留言可編輯並保留焦點順序 ${suffix}`, async ({ page }) => {
    await page.goto(`http://127.0.0.1:4173/${suffix}`);
    const input = page.getByLabel('留言', { exact: true });
    const text = Array.from({ length: 60 }, (_, i) => `第 ${i + 1} 行`).join('\n');
    await page.keyboard.press('Tab');
    await expect(input).toBeFocused();
    await input.fill(text);
    await expect(input).toHaveValue(text);
    await expect(input).toBeEditable();
    await expect(input).toBeVisible();
    await page.keyboard.press('Tab');
    await expect(page.getByRole('button', { name: '下一步' })).toBeFocused();
    const box = await input.boundingBox();
    const viewport = page.viewportSize();
    expect(box).not.toBeNull();
    expect(viewport).not.toBeNull();
    expect(box!.x).toBeGreaterThanOrEqual(0);
    expect(box!.x + box!.width).toBeLessThanOrEqual(viewport!.width);
  });
}

這段只驗資料保留、可編輯、可見、焦點與橫向邊界；不等於自動增高、可捲到末行或整體無障礙都已通過。依 Playwright 的 assertion 說明，toBeVisible 也不是「內容全讀得到」的同義詞。再把視窗縮到手機寬度，人工輸入中文、換行、刪除、貼上長文，確認最後一行可捲到、焦點框清楚、手動拉伸可操作；增強組另比短文與長文的實際高度。

若某引擎失敗，保存輸出目錄與 trace；用 npx playwright show-trace 路徑/trace.zip 開啟 Trace Viewer，查看出錯前的頁面、動作與 DOM。把失敗步驟寫成「WebKit 某建置、某視窗、長文最後一行無法捲到」，比只寫「Safari 壞了」更容易修。完成引擎層，再到承諾支援的正式瀏覽器與實機重做人工項目。

三、怎麼判斷值得保留？看行為、依賴與撤回

A、B 各留一份 diff、套件鎖定檔差異、三引擎測試輸出與人工清單。先看必需功能是否通過，再記錄新增／移除的依賴、程式碼變動與維護難度。刪除的行數不是品質分數；若只把複雜度藏進另一個套件，也要算進成本。一次對照只是該模型、提示與版本下的一次觀察；要談穩定改善，就重跑獨立回合並保留失敗。

訂下採用規則：核心操作全過，支援範圍符合政策，退路可用，變更容易撤回，才合併這次改造。若失敗，保留原始 commit，撤回本次獨立變更後重跑原考卷；不要以清空工作目錄的方式回滾。這也延伸了 版本感知 Skill 的驗收觀念：版本號要和行為證據一起保存。

想加入執行期效能與頁面觀察，可接著讀 Chrome DevTools MCP 的前端證據工作流；若想把這些關卡接成可重跑系統，參考 建立 Agent Harness 的實作拆解。相容性清單是產品承諾，Agent 的任務是交出對得上這份承諾的改動與證據。

四、常見問題：八個先講答案的判斷

1. 安裝 1.0 就能保證 Chrome、Firefox、Safari 都正常？

不能由安裝這件事推出。指引、功能支援與你的整個應用行為，要各自查核。

2. Baseline Newly available 就等於所有舊手機可用？

不是。它表示核心集合的互通狀態；最低版本與實際裝置仍依你的支援政策驗收。

3. legacy-scan 沒有發現，就可以直接上線？

還不夠。它掃精選模式；功能、樣式組合與鍵盤操作仍有自己的測例。

4. 一定要刪掉全部 fallback 才算現代化？

不用。超出支援目標時，退路可能是保留核心功能的必要部分。先判斷它服務誰。

5. WebKit 通過可以填 Safari 正式版通過嗎？

不可以直接代填。要分開記錄測試引擎建置與 Safari 產品版本，再做對應驗收。

6. 這份範例會真的送出留言嗎？

不會。按鈕只用來驗收焦點順序。接後端時，另測提交、錯誤顯示與重試時的文字保留。

7. ?baseline=1 等於測過真正不支援的瀏覽器？

不是。它只主動關閉增強 CSS，驗證設計的基本路徑；舊版本的解析與行為仍需實機或對應環境。

8. 完全不寫程式的人，今天先做什麼？

先寫下三件必須完成的操作，請 Agent 逐項產生測試，再親自用鍵盤走一次。讀懂通過條件比先背 API 名稱更實用。

給新手的三個重點

第一，先說清楚要支援誰，再決定能用多新的功能。第二，一次只改一個元件，讓有／無 Skill 使用同一個起點與考卷。第三，保存失敗與退路；能撤回，下一次才敢繼續改。