谷歌开源 Modern Web Guidance,专治 Agent 写旧代码

0 阅读7分钟

知识点总结

在谷歌自家评测里,不装指南的 Claude Code 只过了 57%。

摘要

Modern Web Guidance 是 Chrome、Edge、Firefox 和 MDN 团队共同维护的 Skill,用本地检索把 250 项现代 Web 特性的写法喂给编码 Agent。在项目自己的近期评测里,通过率提升 27 到 36 个百分点。

核心优势

让 Agent 写前端,常见的毛病是「会用,但用旧的」:弹窗手写一堆 JavaScript,悬浮提示依赖第三方库,明明浏览器已经原生支持。官方 README 给的原因很直接:大模型的训练数据里有海量旧代码。

Modern Web Guidance 的思路不是再训练模型,而是在 Agent 动手前,把对应的现代写法塞进它的上下文。项目 2026 年 3 月在 GoogleChrome 组织下创建,现在有 1.1 万多个 Star,2026-11-10 发布了 v1.0.0。

  • 覆盖面广:官方统计 250 项现代 Web 特性(CSS 与布局 140 项,HTML 与 DOM 36 项,JavaScript 与 API 74 项),对应 203 个真实开发场景,包括 View Transitions、Popover、Anchor Positioning、容器查询、:user-invalid、内置 AI API 等。
  • 内容精炼:指南按评测结果修剪,模型本来就会的内容直接删掉,只留它容易写错的地方。安装选项里,官方给这个技能包标的开销约 205 个 token,指的是 Agent 平时常驻的那段技能描述;具体指南用到时才取回,不会一直占着上下文。
  • 本地离线检索:用离线嵌入模型加 BM25 搜索匹配指南,不联网、不要 API Key,npm 包没有任何依赖。
  • 对兼容性有交代:指南附带 Baseline 状态和浏览器版本数据,不够成熟的特性要求写轻量回退(官方原则是少于 50 行,或按需加载 polyfill),而不是直接塞一个大库。
  • 多个 Agent 通用:Claude Code、Codex、GitHub Copilot CLI、Antigravity、Grok Build CLI、Kimi Code 等都有安装方式。

官方评测:通过率提升多少

项目自带一套评测:在真实的 Web 应用上给 Agent 布置任务,用 Playwright 检查结果,对比装与不装指南的通过率。README 里 11 月 8 日的三组数据(括号内为所用模型):

Agent任务数 / 断言数不装指南 → 装指南提升
Antigravity CLI(gemini-4-argon)214 / 167358% → 94%+36 个百分点
Claude Code(opus-5-5)215 / 180157% → 88%+31 个百分点
Codex CLI(gpt-6.1-sol)215 / 179554% → 82%+28 个百分点

往前几轮(11 月 2 日到 6 日)的快照,提升幅度在 27 到 36 个百分点之间。需要注意:这是项目方自己跑的评测,题目和评分器也是自己写的,README 里也没有给出第三方复现,数字适合当方向参考,不要当成你项目里的保证。

面向人群

  • 用 Claude Code、Codex 等 Agent 写前端,发现它总爱用老写法的人;
  • 想让 Agent 帮忙把旧项目现代化的人(有专门的扫描命令);
  • 想在团队里统一「浏览器支持策略」,并让 Agent 遵守的人。

后端、基础设施、脚本类任务不在范围内,Skill 的触发规则里明确排除了这些。

快速上手

第 1 步:先不装,试一下

要求 Node.js 22 或更高版本。下面三条命令不需要安装:

# 按需求搜索相关指南
npx modern-web-guidance@latest search "animate a dialog modal backdrop"

# 按 ID 取回一篇指南
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

# 扫描代码库里的旧写法
npx modern-web-guidance@latest legacy-scan .

第 2 步:安装

最简单的方式是运行交互式向导:

npx modern-web-guidance@latest install

也可以走各个 Agent 自己的插件通道:

# Claude Code
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/reload-plugins

# OpenAI Codex
codex plugin marketplace add GoogleChrome/modern-web-guidance
codex plugin add modern-web-guidance@googlechrome

# Vercel Skills CLI
npx skills add GoogleChrome/modern-web-guidance

# GitHub CLI
gh skill install GoogleChrome/modern-web-guidance

Antigravity、Grok Build CLI、Kimi Code 和 Copilot CLI 也各有命令,详见仓库 README。装好之后更新用 npx modern-web-guidance@latest update。

第 3 步:之后 Agent 会自己做这三件事

  1. 激活:遇到弹窗、表单、动画、无障碍、性能(LCP、INP)这类前端任务,Agent 先调用这个 Skill;
  2. 搜索:用 2 到 5 个词描述单个能力,比如搜 light dismiss dialog,而不是太笼统的 dialog,也不要带框架名;
  3. 取回:把匹配到的指南读进上下文,再动手写代码,写完对照指南检查。

另外,Skill 要求 Agent 在交付改动时,附一个 Modern Web Guidance 小节,说明用了哪些指南、避开了什么坑,你一眼就能看出它有没有真的用上。

一篇指南长什么样

以「表单字段出错时,给整个分组变色」为例。旧做法要用 JavaScript 监听输入、手动给父元素加类名。指南给出的做法是 :has() 配合 :user-invalid,纯 CSS 就行:

/* 卡片里只要有一个输入框被用户填错,就把左边框变红 */
.card-section:has(:user-invalid) {
  border-left-color: #d93025;
  background-color: #fff8f8;
}

指南里还写明了::user-invalid 从 2023-11-02 起属于 Baseline 广泛可用;如果要兼容不支持 :has() 的浏览器,就用 JavaScript 给父元素切换类名作为回退;还提醒作用范围要写具体(选字段分组,不要选 body),并且颜色变化只是强调,每个字段仍然需要自己的错误文字。

问题、方案、完整代码、兼容数据、回退写法,一篇指南全包了。

进阶用法

一、体检旧代码

legacy-scan 会扫描项目里的过时写法,输出结果后由 Agent 逐条核对,剔除误报,再按指南改写。要注意它只覆盖约 20% 的指南,也就是带确定性规则的那部分,所以「扫描没发现问题」不等于「已经完全现代化」。

二、控制实验性特性

默认情况下,Origin Trial 特性和只有单一浏览器引擎支持的新特性(最近 3 个月内上线或仍在稳定中)仍然可以被搜到,但取回时会被拦住,防止 Agent 擅自采用不稳定的 API。想放开,在项目根目录放一个 .mwgrc 文件,或用命令设置:

npx modern-web-guidance@latest set-allow-origin-trials
npx modern-web-guidance@latest set-allow-volatile-features

它们分别对应 allowOriginTrials 和 allowVolatileFeatures 两个配置项,文件可以提交进仓库,团队共用。

三、把浏览器支持策略写进 AGENTS.md

Skill 默认认为 Baseline 广泛可用的特性不需要回退。如果你的用户群有特殊要求,建议在 AGENTS.md 或 CLAUDE.md 里写清楚,比如允许采用「新近可用」的特性,但自定义回退代码不超过 20 行、不引入外部依赖,Agent 就会按这条规则取舍。

四、隐私与遥测

Google 会收集匿名使用信息:安装次数、调用它的 Agent 名称、取回的指南 ID,以及 Agent 生成的搜索词,不收集你的原始提示词。不想参与,在 shell 配置里设置环境变量:

export DISABLE_TELEMETRY=1

几个使用前要知道的点

  • 需要 Node.js 22 以上,第一次用 npx 要联网。在 Codex、Claude Code 这类沙箱环境里,要提前放行网络访问;
  • 官方评测是自测,效果以你自己的项目为准;
  • 它只管前端和浏览器侧 JavaScript,不会帮你处理后端;
  • v1.0.0 是 11 月 10 日才发布的,npm 上此前已有 100 多个版本,命令和指南内容迭代很快,装好后记得定期执行 update。

收藏清单

  1. 先试:npx modern-web-guidance@latest search "你的需求",不用安装;
  2. 再装:npx modern-web-guidance@latest install,或走 Claude Code、Codex 的插件命令;
  3. 配好:需要实验性特性就设 .mwgrc,有兼容要求就写进 AGENTS.md,不想上报数据就设 DISABLE_TELEMETRY=1。

项目地址:github.com/GoogleChrome/modern-web-guidance