Modern Web Guidance 實測:讓 coding agent 跟上網頁新寫法
Modern Web Guidance 1.0.1 實測:安裝 agent skill,用 legacy-scan 掃出舊網頁寫法,交給 Claude Code 和 Codex 依指南修改,再用 Chrome 比對改前改後,並說明更新方式與 CLI 版本的限制。
Modern Web Guidance 的 SKILL.md 開頭寫,模型訓練資料裡有過時的寫法(training weights contain obsolete patterns)。像是用 JavaScript 量 scrollHeight 讓輸入框長高,或自己判斷點擊位置來關掉對話框,現在都有瀏覽器內建的寫法。
Modern Web Guidance 是一套給 coding agent 用的 skill 和命令列工具。依 GitHub README,它由 Google Chrome、Microsoft Edge、Mozilla Firefox 和 MDN 團隊與社群共同維護。
agent 寫網頁前先用它查指南。指南會告訴 agent 現在該用哪個 HTML、CSS 或 JavaScript 功能、瀏覽器支援到哪裡、不支援時改用什麼寫法。它另外有一個 legacy-scan 指令,可以掃出現有專案裡該換掉的舊寫法。
這篇我寫了一個留言板範例頁,先用 legacy-scan 掃,再交給 Claude Code 依指南修改,最後用瀏覽器比對改前改後。之後換一台電腦、換一個範例,交給 Codex 再跑一次。
依據 Modern Web Guidance 文件、1.0 發布文章(2026-11-10 發布)、Modernization workflow,以及 npm 套件 1.0.1 裡的 README、SKILL.md 與 CLI 原始碼。讀取日期是 2026-11-19,2026-11-20 改版時再核對一次。
實測在 2026-11-19(台北時間),環境是 macOS、Node.js 25.2.1、npm 11.6.2。agent 是 Claude Code 2.1.328,模型
claude-opus-5-5。modern-web-guidance 用 1.0.1,這是當天 npm 上標為 latest 的版本。安裝時被帶進來的skills是 1.9.0。文中的終端機截圖是把錄下的輸出排成圖片,只拿掉了顏色控制碼、spinner 動畫的中間影格,以及我錄製時自己加的結束碼標記。改版時我在第二台電腦用同樣的指令重跑。
search、retrieve、skills-lock.json和兩次legacy-scan的輸出都和第一次相同,圖片用的是重跑的輸出。install那張因為偵測到的 agent 名稱不同,保留第一次的輸出。
它怎麼運作
Modern Web Guidance 分成兩部分:
- skill 是一份 SKILL.md,加上
guides/資料夾裡的指南。我裝進專案後數了一下,guides/底下有 210 份 Markdown。 - CLI 是 npm 套件
modern-web-guidance,負責查指南和掃描舊寫法。
SKILL.md 裡寫給 agent 的指令是這兩行:
1
2
npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_11_10-47b4c80e
npx -y modern-web-guidance@latest retrieve "<id>"
agent 先用 search 找出相關指南的 ID,再用 retrieve 把整份指南讀進上下文。依 README 的 How It Works,search 用的是本機的嵌入模型和 BM25 比對,不呼叫外部 API,也不需要 API key。不過 CLI 預設會在背景送出使用紀錄,下一節說明內容和關法:
sequenceDiagram
participant A as agent
participant C as CLI
participant G as play.googleapis.com
A->>C: search 查詢字詞
C->>C: 本機嵌入模型與 BM25
C->>A: 指南 id 與 description
A->>C: retrieve 指南 id
C->>A: 整份指南
opt 沒設 DISABLE_TELEMETRY=1
C-)G: 背景送出使用紀錄
end
agent 什麼時候會用它,要看 SKILL.md 的 description。description 怎麼影響觸發,我在〈自己寫 Agent Skill〉寫過。
這份 description 寫明所有 HTML、CSS 與前端 JavaScript 工作都要先執行它(MANDATORY: Execute FIRST)。後面還列了一長串觸發主題,例如對話框、表格、深色模式、表單驗證、Core Web Vitals。
legacy-scan 只負責找,修改交給 agent。依 Modernization workflow 文件,它在本機用固定規則掃描專案,不呼叫任何模型,也沒有 --fix 參數。
它只涵蓋能用靜態規則判斷的指南,我這次的掃描結果寫的是 38 份,約占全部指南的 20%。掃出來的結果還要由 agent 依每條規則附的保留條件(Keep when)與排除條件(Drop when),判斷是不是誤判。
官方公布的效果是這樣:文件首頁寫,公開評測中有指南時的通過率是 91%,沒有指南的前沿模型約 51%。README 另有一張逐次結果表,其中 11 月 8 日的 claude_code (opus-5-5) 一列是 57% → 88%。這些數字都來自官方頁面(2026-11-19 讀取)。
準備:關掉使用紀錄、先看套件內容
CLI 需要 Node.js 22 以上(package.json 的 engines)。開始前,我先在 shell 設了一個環境變數,關掉使用紀錄:
1
export DISABLE_TELEMETRY=1
搜尋本身雖然在本機比對,搜尋字詞預設還是會送出去。我讀了 CLI 的原始碼:search、retrieve、legacy-scan、install 這些指令執行時,都會在背景開一個獨立的子行程。這個子行程把使用紀錄送到 play.googleapis.com。
依 README 的 Telemetry & Privacy 段落,收集的內容包含:
- 安裝次數
- 呼叫它的 agent 名稱
- 取回的指南 ID
- agent 產生的搜尋字詞
使用者原本的提示不在收集範圍內。
安裝前,我先把套件下載下來看,作法和〈Claude Code plugin 安全安裝〉一樣:
1
npm pack modern-web-guidance@1.0.1
1.0.1 的 package.json 沒有 scripts,所以安裝時不會跑安裝腳本。套件共 281 個檔案,解開後 17 MB,其中最大的三樣是:
- 搜尋用的向量資料,約 8.8 MB
- 打包成單一檔案的
legacy-scan.mjs,約 4.9 MB - 指南,約 1.9 MB
install 子指令只執行下面這行:
1
npx -y skills add GoogleChrome/modern-web-guidance --skill modern-web-guidance
skills 是 Vercel 的 skill 安裝工具。這裡沒有指定版本,所以會抓當下 npm 上的最新版,我那次是 1.9.0。它會從 GitHub 上的 GoogleChrome/modern-web-guidance 抓 skill,不是從我剛用 npm pack 下載的套件裡複製。
步驟一:先不安裝,試 search 和 retrieve
不安裝也能直接用 CLI。官方文件的範例是 @latest,我改成固定 @1.0.1,讓輸出可以重現:
1
2
npx -y modern-web-guidance@1.0.1 search "submit on enter key"
npx -y modern-web-guidance@1.0.1 retrieve ime-safe-enter-submit | head -n 12
search 回傳 JSON,retrieve 印出指南全文,這裡只截前 12 行(實際輸出)
search 回傳 10 筆結果,每筆有 id 和 description。第一筆 ime-safe-enter-submit 就是我要找的。
SKILL.md 對 agent 的搜尋寫法有這些規定:
- 描述使用者看得到的功能,例如
"light dismiss dialog"。 - 不要加 React、Tailwind 這類框架名稱,也不要加專案裡的元件或檔案名稱。
- 一次只查一個功能。
retrieve 印出的是整份指南。這份是 115 行的 Markdown,裡面有問題說明、建議寫法、無障礙注意事項和瀏覽器支援資料。
指南寫到,中文、日文、韓文使用者用輸入法打字時,按 Enter 是在確認候選字。如果程式在 keydown 看到 Enter 就送出,使用者還沒選完字,訊息就送出去了。
指南建議的寫法是先檢查 event.isComposing。Safari 在確認候選字的那次 Enter 會把 isComposing 回報成 false,所以還要加上 event.keyCode === 229。
步驟二:安裝到專案
官方文件的安裝方式是在專案資料夾執行:
1
npx modern-web-guidance@latest install
我同樣固定版本,並加了兩個參數:
1
npx -y modern-web-guidance@1.0.1 install --agent claude-code -y
--agent 和 -y 是 skills add 的參數,install 會把多出來的參數原樣轉給它。--agent claude-code 只裝給 Claude Code,-y 跳過確認。
我在 Claude Code 裡執行,所以輸出第一行是偵測到 claude agent(實際輸出)
因為我是在 Claude Code 裡執行,skills 偵測到 agent 環境,直接以非互動方式安裝。在一般終端機執行時,它可能會問你要裝給哪些 agent、裝在專案還是全域。
輸出的最後一行提醒使用前先檢查 skill,原文是「Review skills before use; they run with full agent permissions.」。所以我裝完先看了裝進來的檔案,專案裡多了兩樣東西:
.claude/skills/modern-web-guidance/:只有SKILL.md和guides/,沒有 CLI 本體。裝好後打開.claude/skills/modern-web-guidance/SKILL.md讀一遍。skills-lock.json:記錄這份 skill 來自 GitHub 的哪個 commit(64a6d70)和內容雜湊值。這個檔案要和 skill 一起 commit。
lock 檔鎖不住 agent 實際用的 CLI,也鎖不住 agent 查到的指南:
flowchart LR
subgraph P [專案裡]
L[skills-lock.json]
S["SKILL.md 與 guides/"]
end
subgraph N [npm 上的最新版]
C["CLI @latest"]
I[CLI 自附的索引與指南]
end
L -.->|鎖住| S
S -->|叫 agent 執行| C
C -->|search、retrieve 讀取| I
SKILL.md 叫 agent 執行的是 modern-web-guidance@latest。所以就算你安裝時寫了 @1.0.1,agent 每次查詢時跑的還是 npm 上當下的最新版。我讀了 1.0.1 的原始碼,search 和 retrieve 讀的是 CLI 套件自己附的索引和指南,不是專案裡的 guides/ 資料夾。
我比對過,這天裝進來的 SKILL.md 和指南,跟 npm 1.0.1 套件裡的內容完全相同。
更新與移除
SKILL.md 裡的 search 指令帶了 --skill-version 2026_11_10-47b4c80e,CLI 拿它和自己附的版本日期比對。依原始碼,比對後的行為是這樣:
flowchart TD
A["search 帶上 --skill-version"] --> B{CLI 附的版本較新?}
B -->|否| N[不提醒]
B -->|是| C{SKILL.md 版本距今}
C -->|5 天內| N
C -->|5 至 60 天| R[輸出提醒更新的訊息]
C -->|超過 60 天| S[要 agent 堅持請使用者更新]
官方 Get started 文件說,用 CLI 安裝可以「enable automatic updates」。就 modern-web-guidance 1.0.1 的原始碼來看,CLI 本身做的是比對版本後提醒。
看到更新提醒時,在專案資料夾執行:
1
npx modern-web-guidance@latest update
要移除時執行:
1
npx modern-web-guidance@latest uninstall
依原始碼,update 會轉給 skills update,uninstall 會轉給 skills remove。
其他安裝方式
依官方文件,也可以直接用 skills 安裝:
1
npx skills add GoogleChrome/modern-web-guidance
Claude Code 使用者還可以用 plugin 的方式安裝,依序執行這兩行:
1
2
claude plugin marketplace add GoogleChrome/modern-web-guidance
claude plugin install modern-web-guidance@googlechrome
README 另外提醒,以前從 claude-plugins-official 裝的版本,自 10 月 12 日起停在 v0.0.194。要移除後,改從 googlechrome marketplace 重新安裝。
Get started 文件也列了 GitHub CLI、Gemini CLI、Codex、Copilot CLI 等其他 agent 的安裝方式。
Baseline 目標與實驗功能
指南會依 Baseline 判斷一個功能能不能直接用。依 Get started 文件,沒有指定時預設目標是 Baseline Widely available。要改的話,在 AGENTS.md 或 CLAUDE.md 寫一句這樣的說明:
1
This project's Baseline target is Baseline 2024.
這次用的是預設值。
另外有兩類指南預設不會提供給 agent:
- volatile features:只在一個瀏覽器引擎實作、之後可能改動的功能。
- 還在 origin trial 的功能。
要開啟的話,在專案根目錄執行對應的指令:
1
2
3
4
# volatile features
npx modern-web-guidance@latest set-allow-volatile-features
# origin trial
npx modern-web-guidance@latest set-allow-origin-trials
依 1.0.1 的原始碼,這兩個指令偵測到 agent 環境或非互動終端機時會拒絕執行,要你自己在終端機裡跑。
步驟三:準備一個有舊寫法的留言板
這個範例頁是我照 legacy-scan 的規則清單寫的,裡面的舊寫法都是故意放的。它是一個留言板:按 Enter 送出留言,Shift+Enter 換行,「Clear all」按鈕會跳出確認對話框。
我放了五種舊寫法:
keydown看到 Enter 就送出,沒有檢查輸入法是否正在選字。- 用 JavaScript 量
scrollHeight,讓輸入框跟著內容長高。 - 用
textarea:invalid顯示錯誤樣式。 - 對話框靠
e.target === confirmDialog判斷有沒有點到背景,再自己關掉。 - 用
list.innerHTML = ''清空留言。
三個檔案放在 site/ 資料夾。要照著做的話,請原樣存檔,下一步掃描結果的行號才會和我的一樣:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Guestbook demo</title>
<link rel="stylesheet" href="style.css">
</head>
<body>
<main>
<h1>Guestbook</h1>
<p class="hint">Press Enter to post, Shift+Enter for a new line.</p>
<form id="form">
<label for="msg">Message</label>
<textarea id="msg" rows="1" required placeholder="Say hi..."></textarea>
<button type="submit">Post</button>
</form>
<ul id="list"></ul>
<button id="clear" type="button" class="secondary">Clear all</button>
</main>
<dialog id="confirm">
<p>Delete all messages?</p>
<form method="dialog">
<button value="cancel">Cancel</button>
<button value="ok" class="danger">Delete</button>
</form>
</dialog>
<script src="app.js"></script>
</body>
</html>
1
2
3
4
5
6
7
8
9
10
11
12
13
body { font-family: system-ui, sans-serif; background: #f1f5f9; margin: 0; }
main { max-width: 480px; margin: 48px auto; background: #fff; padding: 28px 32px; border-radius: 14px; }
h1 { margin: 0 0 4px; color: #1e3a8a; }
.hint { margin: 0 0 16px; color: #64748b; font-size: 14px; }
label { display: block; margin-bottom: 6px; font-weight: 600; }
textarea { width: 100%; box-sizing: border-box; padding: 10px; font: inherit; resize: none; overflow: hidden; border: 2px solid #cbd5e1; border-radius: 8px; }
textarea:invalid { border-color: #dc2626; background: #fef2f2; }
button { margin-top: 10px; padding: 8px 16px; font: inherit; border: 0; border-radius: 8px; background: #2563eb; color: #fff; }
button.secondary { background: #e2e8f0; color: #0f172a; }
button.danger { background: #dc2626; }
ul { padding-left: 20px; }
dialog { border: 0; border-radius: 12px; padding: 20px 24px; }
dialog::backdrop { background: rgb(15 23 42 / 0.5); }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
const form = document.getElementById('form');
const msg = document.getElementById('msg');
const list = document.getElementById('list');
const confirmDialog = document.getElementById('confirm');
function post() {
const text = msg.value.trim();
if (!text) return;
const li = document.createElement('li');
li.textContent = text;
list.appendChild(li);
msg.value = '';
autosize();
}
// Grow the textarea as the user types.
function autosize() {
msg.style.height = 'auto';
msg.style.height = msg.scrollHeight + 'px';
}
msg.addEventListener('input', autosize);
// Enter posts the message, Shift+Enter adds a new line.
msg.addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
post();
}
});
form.addEventListener('submit', (e) => {
e.preventDefault();
post();
});
document.getElementById('clear').addEventListener('click', () => {
confirmDialog.showModal();
});
// Close the dialog when the user clicks the backdrop.
confirmDialog.addEventListener('click', (e) => {
if (e.target === confirmDialog) confirmDialog.close();
});
confirmDialog.addEventListener('close', () => {
if (confirmDialog.returnValue === 'ok') list.innerHTML = '';
});
我把整個資料夾用 git commit 起來,之後才看得到 agent 改了什麼。
步驟四:用 legacy-scan 掃一次
在專案根目錄執行:
1
npx -y modern-web-guidance@1.0.1 legacy-scan .
結果是 5 份指南、6 個項目。自動長高那段被算了兩次:一次是第 19 行量 scrollHeight 的地方,一次是第 13 行在 post() 裡呼叫 autosize()。
每個項目都附上規則說明、Keep when 和 Drop when。輸出開頭也寫明,靜態分析的結果只是初步判斷,要用這些條件再確認一次。
這一步不會改任何檔案。輸出的最後一行提示,可以用 retrieve <guide-id> 讀對應的指南。
步驟五:交給 Claude Code 修改
我讓 Claude Code 以非互動模式(-p)執行,這樣整個過程可以錄成 JSON 事後檢查。提示用的是 1.0 發布文章裡的寫法,以斜線指令直接叫用這個 skill:
1
2
3
4
5
6
7
claude -p "/modern-web-guidance Modernize the code in this directory" \
--setting-sources project \
--permission-mode acceptEdits \
--allowedTools "Read" "Edit" \
"Bash(npx -y modern-web-guidance@latest *)" \
"Bash(pnpx modern-web-guidance@latest *)" \
--output-format stream-json --verbose --no-session-persistence > run.jsonl
幾個參數的用意:
--setting-sources project只讀專案的設定,不載入我自己的使用者設定和 plugin。執行紀錄的 init 事件顯示,載入的 skill 除了 Claude Code 內建的那些,只有 modern-web-guidance。--permission-mode acceptEdits讓它可以直接改檔。--allowedTools只放行讀檔、改檔,以及 SKILL.md 自己建議放行的 modern-web-guidance 指令。我的電腦有裝 pnpm,SKILL.md 說有 pnpm 時會優先用pnpx,所以pnpx也一起放行。
我在啟動 claude -p 的 shell 先設了 DISABLE_TELEMETRY=1,agent 執行的指令也會帶著這個環境變數。上面的指令省略了幾項只和我本機環境有關的設定。
agent 照 Modernization workflow 的流程走,這次的結果標在圖上:
flowchart LR
A["legacy-scan site --json"] -->|6 個項目| B{"對照 Keep when、Drop when"}
B -->|誤判| X[排除]
B -->|"保留:6 個"| C[retrieve 指南]
C --> D[改寫三個檔案]
D --> E["重跑 legacy-scan --json"]
E --> F["totalFindings 是 0"]
retrieve 取回的指南如下:
- 先一次取回四份:
dialog、form-fields-automatically-fit-contents、ime-safe-enter-submit、validate-input-after-interaction。 - 接著再取回
validate-input-after-interaction和js。
Enter 送出的部分改成這樣:
1
2
3
4
5
6
7
8
9
10
// Enter posts the message, Shift+Enter adds a new line.
msg.addEventListener('keydown', (e) => {
if (e.key === 'Enter' && !e.shiftKey) {
e.preventDefault();
// Enter also confirms IME composition (Japanese, Chinese, Korean); don't submit then.
// keyCode 229 covers Safari, which reports isComposing as false on that keystroke.
if (e.isComposing || e.keyCode === 229) return;
form.requestSubmit(); // Runs native validation, unlike calling post() directly.
}
});
其他幾處:
- 自動長高的 JavaScript 刪掉,改用 CSS
field-sizing: content,並用max-block-size: 12lh限制最高 12 行。不支援field-sizing的瀏覽器裡,輸入框會停在一行高、內容多了就捲動。agent 在回報裡說明,指南建議接受這個結果,不另外寫更複雜的替代方案。 - 輸入框是空的時候按 Enter,現在會跳出瀏覽器內建的必填提示,和按 Post 一樣。改前的版本是什麼都不做。
textarea:invalid改成textarea:user-invalid,多了一段錯誤訊息,並同步aria-invalid。- 對話框加上
closedby="any"。Safari 不支援這個屬性,所以保留一段 fallback:只在不支援時才掛上,改用游標座標判斷有沒有點在對話框外面。 list.innerHTML = ''改成list.replaceChildren()。
SKILL.md 要求 agent 用到指南時,在回報最後加一段 ### Modern Web Guidance,逐項列出用了哪份指南、引用了指南裡的哪句話。這次的回報裡有這一段,對照 diff 時很好用。
最後我自己在專案根目錄重跑一次掃描:
1
npx -y modern-web-guidance@1.0.1 legacy-scan .
輸出同時提醒,legacy-scan 只涵蓋 38 份指南。0 個項目只表示這 38 份指南的規則沒有再找到問題,其他指南涵蓋的寫法它不會檢查。
改用 command 屬性時,留意 polyfill
像「Clear all」這種開對話框的按鈕,有一份指南建議改用 HTML 的 commandfor 與 command 屬性。這份指南是 declarative-dialog-popover-control,照它改時要留意它給的 polyfill 寫法。
不支援 command 的瀏覽器要另外載 polyfill,有 bundler 或 import map 的專案用 npm 安裝:
1
npm install invokers-polyfill
其他情況從 CDN 載入,範例是這段:
1
2
3
if (!('commandForElement' in HTMLButtonElement.prototype)) {
import('https://esm.run/invokers-polyfill');
}
這個網址沒有指定版本。照抄的話,不支援 command 的瀏覽器會在執行時載入 invokers-polyfill 當下的最新版。如果你的專案不允許在執行時從 CDN 載入程式碼,就要在 CLAUDE.md 或 AGENTS.md 寫清楚,寫法可以參考〈AGENTS.md 怎麼寫〉。
不用斜線指令的寫法
這次我用斜線指令直接叫用 skill。不用斜線指令也會觸發掃描,前提是請求的範圍夠大。SKILL.md 寫明,只有沒指定功能或元件的大範圍現代化請求才跑 legacy-scan。
依 Modernization workflow 文件,請 agent 檢查整個專案或資料夾的「legacy patterns」,或要它「modernize」,都會觸發掃描。只點名單一元件時,agent 會改走一般的 search、retrieve 查指南。
文件裡另一個範例提示,要 agent 先提出現代化計畫,確認後才改檔:
1
Modernize this repository using Modern Web Guidance. Scan our frontend files for legacy patterns, verify the findings, and propose a modernization plan before making any code edits.
在既有專案上第一次用時,我會選這種寫法,先看過 agent 判斷保留哪些項目,再讓它動手。
步驟六:在瀏覽器裡比對
legacy-scan 只看程式碼,所以我另外用瀏覽器確認頁面行為。我寫了一個不需要安裝套件的 Node.js 小腳本,透過 Chrome DevTools Protocol 操作 headless Chrome 157。腳本只開本機的檔案,Chrome profile 也是用完就丟的。
改前和改後的頁面各做同樣的操作,再截圖比對。第一組是剛打開頁面的樣子:
改前的輸入框有 required,內容是空的,所以一載入就符合 :invalid,使用者還沒打字就看到紅框。改成 :user-invalid 之後,要等使用者操作過或按了送出,才會顯示錯誤樣式。我在改後的頁面直接按 Post,紅框和錯誤訊息就出現了:
第二組是輸入法。我用 DevTools Protocol 模擬中文輸入法正在選字的狀態,讓輸入框裡有一段還沒確認的「你好」,再送出一次 Enter。下面是腳本裡的這兩步,後面放開 Enter 和確認文字的事件這裡省略:
1
2
await send('Input.imeSetComposition', { text: '你好', selectionStart: 2, selectionEnd: 2 });
await send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 229, nativeVirtualKeyCode: 229 });
我另外在輸入框掛了一個只記錄、不攔截的 keydown 監聽。兩個版本收到的事件都是 key: "Enter"、keyCode: 229、isComposing: true。
左:改前,選字用的 Enter 把「你好」送出了。右:改後,沒有送出。
改前的版本把還在選字的「你好」當成留言送出。改後的版本看到 isComposing 是 true 就不送出,留言列表是空的。
換一台電腦、換一個範例再跑一次
上面的留言板是我照 legacy-scan 的規則清單寫的,掃得到並不意外。所以我在 2026-11-20(台北時間)換到另一台電腦,重新下載 1.0.1,自己寫了一個不同主題的頁面再跑一次:
- 電腦:Linux(Debian 13)、Node.js 24.22.1、npm 11.21.1、Chrome 156。
- agent:Codex CLI 0.171.0,模型是
gpt-6.1-sol,透過我自己架的 LiteLLM 呼叫。 - Codex 的沙箱模式是
workspace-write,並開放網路。
先說和前面一致的部分:
- 同樣的
search "submit on enter key"回傳同樣 10 筆。 skills-lock.json的 commit 和computedHash相同,裝進來的也是 210 份指南。- 我把上面留言板的三個檔案原樣存檔再掃,一樣是 5 份指南、6 個項目,行號也相同。
露營區範例的掃描結果
新的範例是一個露營區訂位頁,三個檔案放在 web/。legacy-scan 找到 5 份指南、5 個項目:
下表是我放進去的舊寫法,以及掃描有沒有找到:
| 我放進去的舊寫法 | legacy-scan 的結果 |
|---|---|
搜尋框用 e.keyCode === 13 判斷 Enter 後搜尋 | 沒找到 |
四個必填欄位用 input:invalid 顯示錯誤樣式 | validate-input-after-interaction,style.css:6 |
確認視窗是自己用 div 做的,靠 e.target === overlay 判斷點到外面再關掉,沒有用 <dialog> | 沒找到 |
| 勾選「租帳篷」時,用 JavaScript 幫外層加 class 改底色 | 沒找到 |
FAQ 展開用 max-height: 9999px | animate-to-intrinsic-sizes,style.css:11 |
從 jsDelivr 載入 dayjs,沒有 integrity | secure-external-subresources,index.html:8 |
兩段重複的 @media (prefers-color-scheme: dark) | dark-mode,style.css:18 |
用 results.innerHTML = '' 清空搜尋結果 | js,app.js:9 |
div 做的確認視窗沒被掃到,是因為 dialog 規則看的是掛在 <dialog> 上的 click 監聽,自己用 div 做的視窗不在範圍內。
keyCode === 13 則不算漏掉。ime-safe-enter-submit 指南寫到,輸入法選字時按 Enter,瀏覽器回報的 keyCode 是 229 而不是 13。所以舊的 keyCode === 13 寫法,本來就不會在選字時觸發。會出問題的,是把它改成 e.key === 'Enter' 卻沒有加上檢查。
交給 Codex 修改
我用和前面一樣的提示交給 Codex,$ 是 Codex 指定 skill 的寫法:
1
$modern-web-guidance Modernize the code in this directory
過程如下:
- 它用一次
retrieve取回 5 份指南。內容有 84.4 KB,CLI 沒有直接印出,而是存成/tmp/mwg-guide-….md,要 agent 再分段讀檔。 - 5 個項目全部修改,重掃是 0。我自己在專案根目錄用 1.0.1 重掃也是 0。
- 它另外把搜尋框改成
e.key === 'Enter' && !e.isComposing。這段不在掃描結果裡,它也沒有取回 ime-safe-enter-submit 指南。照指南的說法,這樣改少了e.keyCode === 229,在 Safari 確認候選字的那次 Enter 可能會送出。 - 為了自己檢查,它用 npm 把 jsdom 裝到
/tmp跑 DOM 測試,也用 curl 下載 CDN 上的檔案比對雜湊值。開放網路時,agent 會做這類額外下載。 - 整輪 119 秒。執行紀錄裡的 token 用量是輸入 525,856(其中 434,990 命中快取)、輸出 4,418。
所以 agent 也會改到掃描範圍以外的地方,而且不一定照指南改完整。看 diff 時,要特別注意掃描結果以外的修改。
用瀏覽器比對三個版本
我同樣用 DevTools Protocol 操作 headless Chrome 156,模擬輸入法正在選「溪邊」時按 Enter。除了改前(A)和 Codex 改後(B),我另外做了一個對照組(C),只把 A 的條件改成 e.key === 'Enter':
A:原本的 keyCode === 13。B:Codex 改後。C:對照組,只改成 e.key === ‘Enter’。
三個版本收到的事件都是 key: "Enter"、keyCode: 229、isComposing: true。結果如下:
| 版本 | 選字中按 Enter | 剛載入時的四個必填欄位 |
|---|---|---|
A:原本的 keyCode === 13 | 沒有搜尋 | 紅框 |
| B:Codex 改後 | 沒有搜尋 | 一般樣式 |
C:對照組 e.key === 'Enter' | 選字時就搜尋了 | 紅框 |
在 B 直接按 Book,欄位才變成紅框並出現錯誤訊息,aria-invalid 也變成 true。
放在 demo/ 的程式碼會被跳過
legacy-scan 預設會跳過看起來像文件、範例或測試的資料夾,例如 docs/、examples/、demo/、test/。
我把同一個範例放在 demo/ 底下掃,結果是 0,最後一行寫著 Skipped 3 docs and test files。加上 --include-docs-and-tests 才掃到 5 個項目。
照著做時如果把範例放在 demo/,記得加這個參數,或換一個資料夾名稱。
使用紀錄實際送出什麼
使用紀錄確實會帶上搜尋字詞。我在不能連網的環境裡,不設 DISABLE_TELEMETRY 跑一次 search "booking date picker"。送出用的 fetch 我換成只記錄、不送出。
背景子行程準備 POST 到 play.googleapis.com 的內容,包含這句搜尋字詞,以及找到的指南 ID 和相似度分數。設了 DISABLE_TELEMETRY=1 再跑,就沒有這個請求。
搭配瀏覽器檢查
依 1.0 發布文章,官方建議搭配 Chrome DevTools for agents。Modern Web Guidance 讓 agent 一開始就照現在的寫法寫,DevTools for agents 讓 agent 看得到頁面在瀏覽器裡實際執行的狀況。
文章舉了幾個搭配的例子:
- 在模擬的低階 CPU 上錄效能追蹤,再依指南拆開長任務,直到主執行緒不會被卡住超過 50 毫秒。
- 錄下對話框、popover 的動畫,檢查效果是否符合網站風格,並確認使用者開啟
prefers-reduced-motion時有照設定減少動畫。 - 把畫面快取在記憶體裡時,用記憶體工具確認記憶體用量不會一直增加。
這次我用的是自己寫的 DevTools Protocol 小腳本。如果要讓 agent 自己打開頁面檢查,可以參考我寫的〈agent-browser 入門:讓 AI 自己打開瀏覽器檢查成果〉。合併前先確認能用的流程,我在〈pstack 系列(3):寫完程式之後,先證明它能用再合併〉寫過。
結論
想試的話,我建議先不安裝,用步驟四的 legacy-scan 指令掃自己的專案,看它找到什麼。第一次交給 agent 時,請它先提出現代化計畫。改完後看 diff,再到瀏覽器實際操作一次。
延伸閱讀
- Modern Web Guidance 官方文件:安裝方式、範例提示和 Baseline 目標的設定。
- Get started:各 agent 的安裝方式、Baseline 目標,以及 volatile features、origin trial 指南的開啟方式。
- Modernization workflow:
legacy-scan搭配 agent 修改的四步流程。 - 〈自己寫 Agent Skill:從 SKILL.md 結構到觸發測試與維護〉:SKILL.md 的 description 怎麼影響觸發。
- 〈Claude Code plugin 安全安裝:裝之前先看哪些檔案〉:安裝 skill 或 plugin 前要看哪些檔案。







