Modern Web Guidance 1.0：Claude Code、Codex 与 Cursor 安装配置

将 Modern Web Guidance 1.0 安装为项目级技能（skill），先用一项前端任务验证指南的使用情况，再考虑用于整个仓库。用 legacy-scan 生成需要审查的改造方案，不要直接进入无人审核的代码重写流程。如果不希望发送 Modern Web Guidance 的使用遥测，请在执行第一条命令前设置 DISABLE_TELEMETRY=1。

Modern Web Guidance 1.0 带来了什么

Modern Web Guidance 为现有编码代理提供有针对性的浏览器平台指引，供它在编写代码前参考。2026 年 11 月 10 日发布的 1.0 版本包含 203 篇面向具体场景的指南，覆盖 250 项 Web 平台功能。Chrome、Edge、Firefox 和 MDN 团队与社区贡献者共同维护这个项目。

技能会指示代理搜索相关指南、获取正文，再应用其中的实现规则和兼容回退方案。搜索结合了本地嵌入模型和按关键词排序的 BM25。根据项目官方 README，匹配过程不需要调用外部模型 API，也不需要 API 密钥。

这适合代理知道某个浏览器 API，却容易遗漏过渡效果或兼容回退细节的场景。你仍需明确支持哪些浏览器，审查修改，并运行应用测试。

在 Claude Code、Codex 或 Cursor 中安装

三种代理都可以使用同一套 CLI 命令，按项目安装技能。安装命令的封装代码会调用 Vercel Skills。截至 2026-11-13，请使用 Node.js 22.20 或更新版本，以满足当前 Skills 安装器的要求。你还需要 npm/npx，以及下载所需软件包的权限。

在项目根目录打开 Bash。执行官方安装命令前，先关闭 Modern Web Guidance 的遥测：

export DISABLE_TELEMETRY=1
npx modern-web-guidance@latest install

交互式安装器允许选择目标代理。选择 Claude Code、Codex、Cursor，或只选择实际使用的工具。在单个仓库中试用时，保持项目级安装；底层安装器默认也采用这一范围。

通过这条 CLI 路径安装后，检查以下项目文件和显式调用方式：

代理	项目内的技能文件	显式调用方式
Claude Code	`.claude/skills/modern-web-guidance/SKILL.md`	输入 `/modern-web-guidance`。
Codex	`.agents/skills/modern-web-guidance/SKILL.md`	使用 `/skills`，或在输入中提及 `$modern-web-guidance`。
Cursor	`.agents/skills/modern-web-guidance/SKILL.md`	在 Agent 聊天中输入 `/`，然后选择该技能。

这些目录对应当前安装器为各代理配置的路径。它们不是插件缓存目录，也不是全局安装路径。

在同一个仓库中新建代理会话，首次验证时显式调用技能。如果找不到技能，重新安装前先确认选中的代理、安装范围和文件位置。

通过 CLI 安装的技能，可以在项目目录中执行以下命令更新：

npx modern-web-guidance@latest update

更新后审查发生变化的技能文件，并重复下文的指南获取检查。这些命令使用 @latest，不要假定未来的更新仍停留在版本 1.0。

插件市场是另一种安装途径，应使用对应的更新流程，不要与这里的 CLI 步骤混用。关于 Claude Code 插件的打包方式与生命周期管理，可参阅Claude Code 插件安装、验证与移除指南。

验证搜索、指南获取及代理的实际使用情况

既要验证 CLI 能正常工作，也要确认代理实际使用了它的输出。终端命令执行成功，并不能单独证明代理已经加载技能。

在 Bash 中运行文档里的对话框示例：

npx modern-web-guidance@latest search "animate a dialog modal backdrop"
npx modern-web-guidance@latest retrieve "animate-to-from-top-layer"

搜索返回包含指南 ID 和说明的 JSON，获取操作则返回所选指南的内容。输出较大时，CLI 可能改为显示已保存文件的路径；此时应让代理完整读取该文件。

然后调用已安装的技能，为代理安排一项范围明确的任务。下面的提示词要求保留现有框架和浏览器支持策略，在编辑前获取指南，并报告使用的指南、回退方案和测试结果：

Use the modern-web-guidance skill to add an animated modal dialog.
Keep the existing framework and browser support policy.
Retrieve the relevant guidance before editing.
Afterward, report the guide IDs, required fallbacks, and tests run.

在工具调用记录中确认搜索与获取操作确实发生。最终报告应注明使用了哪篇指南，以及指南影响了哪些实现决定。仅说“采用了最佳实践”不能作为验证依据。

发布版本中的对话框动画指南提供了一个具体审查点。使用 transition 简写属性时，必须把 transition-behavior: allow-discrete 写在它之后，避免该值被简写属性重置。测试入场和退场行为、启用“减少动态效果”设置时的表现，以及对话框原有的交互。

如果第一条命令还没返回搜索结果就失败，先检查 Node.js 和软件包下载权限。发布版本中的技能指令明确区分了软件包下载与离线运行。只批准所需软件包的执行命令，不要放开任意 npx 调用。

如果搜索结果不相关，尝试用更具体的浏览器行为搜索，例如“confirmation modal dialog”。不要为了让流程看起来成功，就获取一篇无关指南。

用 legacy-scan 审查候选项，不要自动重写代码

用 legacy-scan 在仓库或目录中识别改造候选项。对于单个组件的具体修改，则使用搜索和获取指南的方式，现代化改造流程文档也做了这一区分。

在项目根目录运行以下命令，获得便于阅读的扫描结果：

npx modern-web-guidance@latest legacy-scan .

如果需要供代理审查的结构化输出，使用：

npx modern-web-guidance@latest legacy-scan . --json

预期得到的是与相关指南关联的候选结果，而不是已经重写的源文件。静态扫描器不调用 LLM。代理随后分析结果、修改代码时，仍会使用它通常连接的模型。

让代理按文档中的四个阶段执行：

扫描选定目录，收集候选结果。
结合周边代码和 keepWhen/dropWhen 规则核实每一项。排除误报，不要把每个匹配项都当成必须修改的问题。
报告已核实的结果和拟议修改。开始改造前，先获得你的批准。
获取对应指南，再按指南实施获批的修改。运行现有测试，并重新扫描修改过的范围。

特别留意有意保留的回退方案，以及带有功能支持检查的兼容代码。某种写法看似过时，却仍可能是项目浏览器支持策略所必需的。

1.0 版本的扫描器只覆盖约 20% 的指南，即具备确定性旧模式检测规则的那部分。这个比例以指南目录为分母，不是你的代码库占比。因此，没有发现候选项，并不代表项目已全面采用现代写法，也不能证明无障碍表现或正确性。

改造前先设置浏览器支持策略和 .mwgrc

先明确兼容性要求，除非项目确实需要，否则保持实验性指南禁用。默认情况下，技能认为标记为 Baseline Widely available 的功能可以直接使用，无需回退方案。

Baseline 配置说明介绍了如何将项目目标写入 AGENTS.md 或 CLAUDE.md。使用项目真实的支持策略，不要只是为了接受某项替代实现而修改策略。

项目根目录中可选的 .mwgrc JSON 文件控制实验性指南的访问权限。要记录保守策略，请把以下字段合并到现有配置中：

{
  "allowOriginTrials": false,
  "allowVolatileFeatures": false
}

volatile（易变）指南针对仅在单一浏览器引擎中提供、且在最近 3 个月内发布或仍处于稳定过程中的功能。这些指南仍可被搜索到，但获取正文需要明确授权。Origin Trial 指南有独立的许可开关。

要允许获取易变功能指南，请在自己操作的交互式 Bash 终端中运行：

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

对于 Origin Trial 指南，仅在需要时使用单独的命令：

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

这些命令会要求确认，并在确认后把对应布尔值设为 true。检查输出中的配置文件路径和修改后的键，再重试指南获取。

在代理内部或非交互式 shell 中遭到拒绝，是刻意设置的限制。授权逻辑的实现要求由开发者本人操作交互式终端。不要让代理绕过这项检查。

这些开关只解锁指南，不会启用浏览器功能、替网站注册 Origin Trial，也不会扩展项目承诺支持的浏览器范围。

控制遥测与上下文开销

应在实际启动 Modern Web Guidance 的环境中关闭遥测，而不是只在一个无关终端里设置变量。根据项目隐私说明，收集的信息包括安装次数、调用代理的名称、已获取指南的 ID，以及代理生成的搜索词。说明称不会收集用户的原始提示词。

但搜索词仍可能透露任务细节。在 Bash 启动配置（如 .bashrc）中添加 export DISABLE_TELEMETRY=1，并确保代理的命令执行环境继承该变量。必要时，让已经运行的代理或 IDE 在更新后的环境中重新启动。

在执行工具调用所用的 Bash 环境里，以下检查可以确认变量值，而不打印它：

test "${DISABLE_TELEMETRY:-}" = 1

退出状态为 0，表示该环境中的变量值为 1。这不是网络流量审计，也不能据此判断代理提供商或其他工具的遥测设置。

离线搜索不等于整个流程离线运行。下载软件包需要联网；如果没有主动关闭，Modern Web Guidance 的遥测也会保持启用。

评估上下文开销时，README 标注的技能包大小可作参考：modern-web-guidance 约为 205 tokens，chrome-extensions 约为 175 tokens。这些数字不是完整代理任务的用量上限。获取的指南正文也会进入上下文窗口，核实与编辑还需要代理继续工作。

用有代表性的任务测量实际用量。不要仅凭标注的技能大小计算节省额。

把评测增益作为试用依据，在自己的项目中验证

Google 的结果支持你尝试这项技能，但不能代表普遍适用的成功率，也不保证节省 token。日期为 2026-11-08 的官方 README 评测快照列出了以下结果：

代理与模型标签	任务数 / 断言数	无指南	有指南	增幅
`claude_code` / `opus-5-5`	215 / 1801	57%	88%	31 个百分点
`codex_cli` / `gpt-6.1-sol`	215 / 1795	54%	82%	28 个百分点
`antigravity_cli` / `gemini-4-argon`	214 / 1673	58%	94%	36 个百分点

这些数字是断言通过率，不是生产项目成功完成的比例。各行的任务数和断言数也不同，不能把表格当成在完全相同工作负载下得到的受控模型排名。

评测面板的方法说明将通过率定义为通过检查数除以实际执行的检查数。评分前崩溃或超时的运行会被剔除，与其配对的另一次运行也会一并剔除。

Google 围绕自己的指南设计了这套评测。其代理常见错误说明介绍了如何按照指南定义的预期检查输出。这是工具提供方自行开展的评测，不是对你的应用质量进行的独立验证。

决定是否推广前，选择一项有代表性的组件任务，比较有指南和无指南的两种情况。保持模型、提示词和浏览器支持策略不变。检查相关浏览器行为、回归测试、投入时间及实际用量。

成本方面，应看每项已完成编码任务的成本，而不只是 token 单价。当 Modern Web Guidance 改善了仓库中真正重要的检查结果，且没有带来不可接受的审查或使用成本时，再继续采用。