让 AI Agent(如 Claude Code、GitHub Copilot 或 OpenAI Codex)写前端页面时,很多人会遇到一种情况:代码能跑,但写法像五年前的教程。明明浏览器早就支持原生的新特性,AI 却还在堆砌复杂的 <div> 嵌套和冗长的 JavaScript 脚本。
为了解决这个问题,Google Chrome 发起了开源项目 Modern Web Guidance,并在 1.0 稳定版迎来 Mozilla Firefox 和 Microsoft Edge 加入,目前由 Chrome、Edge、Firefox、MDN 团队及 Web 开发社区共同维护。如果你不想深究复杂的前端标准,只想搞清楚这个仓库到底能不能帮上忙,可以通过以下三个问题快速读懂它。
一、它是什么:装进 AI 编码代理的“技能”
按照官方定义,Modern Web Guidance 是一套面向 AI 编码代理的“技能”(Skills),作用是把 Web 平台专业知识、最佳实践以及浏览器兼容性数据直接嵌入到代理的上下文窗口中。
理解这个项目,最关键的是先弄清它不是什么:
-
它不是一个新的前端框架,你不需要修改现有的技术栈(无论是 React、Vue 还是原生开发)去迁就它。
-
它也不是一个会被打包进生产环境的运行库,不会增加最终网页的体积。
你可以把它看作一本专门给 AI 准备的“随身参考手册”和检索工具。
举个具体场景:当你对 AI 说“帮我做一个点击外部区域就能自动关闭的确认弹窗”时,没有装这套技能的代理,通常会直接凭记忆手写一套基于 <div> 的遮罩层,再加上一堆监听点击事件和焦点的 JavaScript 代码。而安装了 Modern Web Guidance 的代理,会在动笔前先通过内置指令去查这本“手册”,把官方整理好的现代实现方案(比如原生的 <dialog> 元素及对应的属性规范)读进自己的上下文里,然后再开始写代码。
从项目结构上看,你在 GitHub 上看到的 modern-web-guidance 是供代理安装和调用的技能分发仓库;而指南的编写、校准和自动化评测代码,则存放在配套的源码仓库 modern-web-guidance-src 中。
二、有什么用:纠正 AI 的“老习惯”
为什么大模型写前端代码总是带着一股“陈旧感”?
原因在于训练数据。互联网上积累了海量的历史代码,大语言模型在训练时吸收了太多旧时代的写法和妥协方案。这导致 AI 编码代理在面对任务时,往往默认退回到老路子上——比如为了实现一个滚动动画去引入庞大的 JavaScript 动画库,而不是使用现代 CSS 的滚动驱动动画(Scroll-driven animations);或者为了改个下拉菜单样式,放弃原生表单控件去手搓一套缺乏无障碍支持的复杂组件。
即便模型“知道”某个新 API 的存在,它脑海里也往往缺乏足够密集的、经过生产环境验证的现代实现模式,很容易用错 API,或者漏掉关键的焦点管理、键盘操作等无障碍细节。
Modern Web Guidance 的核心作用,就是在代理写代码的关键节点“拉它一把”,主要解决三个层面的问题:
-
优先采用现代原生方案:引导代理用更少、性能更好的原生 HTML 和 CSS 替代臃肿的 JavaScript。例如用 Popover API 配合 CSS 锚点定位(Anchor Positioning)做提示框,或者用容器查询(Container Queries)做自适应组件。
-
补齐无障碍与性能短板:原生平台特性通常自带浏览器级别的优化和无障碍支持。指南会明确告诉代理如何同步视觉状态与屏幕阅读器状态(如配合
:user-invalid处理表单报错)、如何避免主线程长任务阻塞交互(INP 优化)等。 -
提供负责任的降级方案(Fallbacks):用新特性最怕老浏览器报错。这套指南集成了 Baseline 项目的浏览器兼容性数据。对于还没广泛普及的特性,指南不会让 AI 盲目引入沉重的第三方 Polyfill 库,而是提供针对性的轻量级降级代码(通常控制在 50 行以内)或
@supports渐进增强写法。同时,对于尚处于实验阶段的 Origin Trial API 或刚在单一浏览器引擎推出不足 3 个月的不稳定特性,工具默认会在检索后拦截获取,除非开发者在项目的.mwgrc配置文件中显式开启许可。
根据仓库说明,该项目目前已覆盖 250 项现代 Web 特性(包含 140 项 CSS 与布局特性、36 项 HTML 与 DOM 特性、74 项 JS 与 API 特性)以及 203 个真实开发用例,涵盖用户体验、CSS 布局、性能优化、表单与 UI 组件、无障碍、安全隐私以及浏览器端内置 AI 等多个领域。
为了确保这些指南真的对 AI 有用,维护团队还搭建了一套端到端的自动化评测流水线:向代理发出不点名具体 API 的自然语言需求(例如“让我的图片加载更快”),对比代理在“有指南”和“无指南”两种模式下的真实浏览器测试通过率。如果某个知识点模型本来就懂,团队就会把它从指南里删掉以节省 Token;如果代理频繁出错,就针对性地打磨指南表述。
三、怎么用:安装后由代理自己查
在实际使用中,你不需要自己去背这 200 多篇指南的名字,也不需要每次在提示词里提醒 AI 用哪个 API。它的标准工作流是“你装好,AI 自己查”。
1. 一键安装
在你的项目根目录下,运行官方推荐的 CLI 安装命令:
npx modern-web-guidance@latest install
这个命令会启动一个交互式向导,帮你把技能配置到你常用的编码代理中。如果你想按需选择技能包(例如除了默认的 Web 指南外,还想安装专门针对 Manifest V3 的 chrome-extensions 浏览器扩展开发指南),可以加上 --choose 参数:
npx modern-web-guidance@latest install --choose
日后如果指南库更新了,只需运行 npx modern-web-guidance@latest update 即可升级。
2. 代理的内部运作流程
安装完成后,你只需要像平时一样给 AI 提需求。比如你在对话框里输入:
“帮我实现一个弹窗打开和关闭时的背景过渡动画。”
此时,代理会按照内置的技能工作流规范自动执行以下步骤(你也可以在终端里直接运行这些命令来手动体验):
第一步:本地语义搜索(Search)
代理会把你的需求提炼成简短的动作短语,调用 CLI 的搜索功能:
npx modern-web-guidance@latest search "animate a dialog modal backdrop"
值得一提的是,这个搜索匹配过程使用的是内置的离线、零依赖嵌入模型和 BM25 搜索引擎。搜索计算本身完全在本地完成,不需要调用外部网络 API,也不需要配置任何 API Key(不过工具默认会向 Google 发送匿名的使用与搜索词统计,详见第五部分,可通过环境变量关闭)。搜索结果会返回匹配度最高的指南 ID 及简介(例如匹配到 animate-to-from-top-layer)。
第二步:取回具体指南(Retrieve)
拿到指南 ID 后,代理会执行取回命令:
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"
这条命令会把该场景下的标准代码结构、常见坑点(Gotchas)以及兼容降级方案直接注入到代理的上下文窗口中。
第三步:核对与披露
代理参照取回的指南编写代码,并在回复你的结尾附上一小段 ### Modern Web Guidance 说明,交代它具体参考了哪篇指南、采用了什么现代写法,以及借此避开了什么坑。
四、额外工具:扫描老项目
在实际工作中,大部分开发并不是从零新建项目,而是在维护已经写了多年的老代码库。在 2026 年 11 月发布的 1.0 稳定版中,项目新增了一个专门用于老代码现代化的扫描工具:legacy-scan。
如果你想看看手头的老项目里有哪些陈旧的 workaround、多余的依赖或可以替换成原生特性的旧写法,可以在项目目录下运行:
npx modern-web-guidance@latest legacy-scan .
或者直接在支持该技能的代理中输入提示词,让代理来主持扫描和改造:
/modern-web-guidance Modernize the code in this directory
代理会先运行静态扫描,再根据内置的判定规则(keepWhen / dropWhen)过滤掉误报(例如不能随便删掉的必要降级代码或第三方库代码),最后向你汇报可行的升级计划,并在你同意后逐个取回对应指南完成重构。
不过使用这个功能时要有一个合理的预期:legacy-scan 目前只覆盖了大约 20% 的指南语料。因为静态语法分析只能抓取那些特征非常明确的旧代码模式,官方选择先从结果可预测的小范围规则做起。因此,它非常适合用来在老项目里快速寻找改造线索、顺手偿还一部分技术债,但不能代替全面的代码审计或性能排查。
五、使用前的两点提醒
在把 Modern Web Guidance 接入日常开发流程前,有两个细节值得留意:
1. 关注遥测与隐私设置
虽然工具的语义搜索是在本地离线完成的,但为了改进工具的可靠性和指南的相关性,Google 默认会收集匿名的使用统计数据。根据官方说明,收集的内容包括安装次数、调用该工具的代理名称、被取回的指南 ID,以及代理生成的 CLI 搜索词(例如 "dark mode scrollbar color-scheme"),不会收集用户的原始提示词(Raw user prompts)。
如果你在企业内部项目中使用,或者不希望发送任何搜索词及使用统计,可以在你的终端配置文件(如 .bashrc 或 .zshrc)中设置环境变量将其关闭:
export DISABLE_TELEMETRY=1
2. 不同代理的安装命令存在差异
如果你不想用通用的 npx 向导,也可以通过各个编码代理自带的插件市场或 CLI 来安装(项目已支持 Claude Code、GitHub Copilot CLI、OpenAI Codex、Google Antigravity、Kimi Code、Grok Build 等)。
需要注意的是,这些 AI 编程工具本身的命令格式迭代很快,甚至在官方自己的 GitHub README 和开发者文档页面之间,针对同一个代理(如 Claude Code)展示的插件安装写法都存在细微出入。因此,如果你选择通过代理自带的插件命令安装,建议直接对照你当前所用代理工具的最新官方文档来操作;或者干脆使用最稳妥的通用命令 npx modern-web-guidance@latest install,让安装向导替你处理配置细节。
