在谷歌自家评测里,不装指南的 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 / 1673 | 58% → 94% | +36 个百分点 |
| Claude Code(opus-5-5) | 215 / 1801 | 57% → 88% | +31 个百分点 |
| Codex CLI(gpt-6.1-sol) | 215 / 1795 | 54% → 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 会自己做这三件事
- 激活:遇到弹窗、表单、动画、无障碍、性能(LCP、INP)这类前端任务,Agent 先调用这个 Skill;
- 搜索:用 2 到 5 个词描述单个能力,比如搜
light dismiss dialog,而不是太笼统的dialog,也不要带框架名; - 取回:把匹配到的指南读进上下文,再动手写代码,写完对照指南检查。
另外,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。
收藏清单
- 先试:
npx modern-web-guidance@latest search "你的需求",不用安装; - 再装:
npx modern-web-guidance@latest install,或走 Claude Code、Codex 的插件命令; - 配好:需要实验性特性就设
.mwgrc,有兼容要求就写进AGENTS.md,不想上报数据就设DISABLE_TELEMETRY=1。
项目地址:github.com/GoogleChrome/modern-web-guidance