它是什么
Modern Web Guidance 是一套专门提供给 AI 编程助手（coding agent）的“技能包”，由 Google Chrome 团队牵头，联合 Microsoft Edge、Mozilla Firefox 和 MDN 团队以及社区共同维护。它的出发点很直接：大模型的训练语料里堆积了十几年的存量前端代码，所以 agent 默认会写出大量手写 DOM 操作、重量级 polyfill 和早就该淘汰的第三方库，而对浏览器如今原生支持的能力视而不见。
这个项目把这些现代 Web 平台特性、最佳实践和浏览器兼容性数据整理成结构化指南，通过命令行工具按需送入 agent 的上下文窗口，让模型在写代码时优先选择平台原生方案。本次热榜上的仓库是它的源仓库，收录了指南的撰写、校准与评测代码，并附带一个公开的评测看板；日常使用则通过 npm 上发布的 CLI 完成。
核心功能
- 交互式安装向导：执行
npx modern-web-guidance@latest install即可完成接入，向导会引导你把技能挂到常用的编码 agent 上。 - 自然语言检索指南：
search子命令接受一句描述（例如“给弹窗遮罩层加动画”），返回最相关的现代实现方案。 - 按 ID 精确取回：
retrieve可以直接拉取某一条指南的完整内容，适合知道具体条目时精准调用。 - 遗留模式扫描：
legacy-scan会遍历代码库，找出仍在使用的过时写法，并给出对应的现代化替换建议。 - 令牌高效设计：团队通过评测剔除模型已经熟知的基础内容，只保留高信息密度的实战模式，减少上下文浪费。
- 覆盖面新且全：从 View Transitions、顶层元素进出场动画、视差滚动，到 CSS
scrollbar-color这类较新的属性都在收录范围内。
适用场景
用 AI 写前端时防止“越写越旧”。 无论你用的是 Cursor、Copilot 还是 Claude Code，只要 agent 会读文件、写代码，就能接上这套指南。
老项目现代化改造。 用 legacy-scan 先跑一遍存量仓库，把可以改用原生 API 的地方列出来，再决定重构顺序，比凭感觉翻文档高效得多。
团队规范统一。 把指南作为共享知识源，能让不同人手上的 AI 助手输出风格更接近，减少“一个人用新 API、另一个人引第三方库”的分裂。
性能与无障碍优化。 指南明确偏向浏览器可自行优化、自带无障碍语义的平台级 API，并主张用轻量降级方案替代沉重 polyfill。
上手建议
第一步不需要安装任何东西，直接用 npx 试跑：先用 search 问一个你手头正在纠结的问题，看看它返回的指南质量，再决定是否执行 install 正式接入。
第二步，挑一个技术债较多的老仓库跑 legacy-scan，但不要盲信报告——把它当成一份“待核实清单”，逐条对照目标浏览器版本和项目实际约束再改。
第三步，如果打算参与共建，先读仓库里的 CONTRIBUTING.md 和 GOVERNANCE.md，了解条目撰写与校准的流程；项目采用多厂商共治模式，提交指南需要经过评测验证。
最后提醒一点：指南更新节奏跟随 Web 平台演进，但你的用户环境未必同步，生产环境仍要自己核对兼容性数据与降级路径。
