Modern Web Guidance：用RAG文档填补AI编程的现代Web能力短板

当AI编程遇上现代Web的能力鸿沟

如今几乎每位开发者都在与各类编码智能体（coding agents）协作。编码智能体是指具备自主规划、执行和迭代能力的AI编程系统，它们不仅仅是简单的代码补全工具（如早期的GitHub Copilot），而是能理解高层需求、分解任务、编写代码、运行测试并自我修正的完整工作流系统。典型代表包括Cursor、Devin、Claude Code等。这些智能体通常基于大语言模型，但在其上叠加了工具调用（tool use）、上下文管理和多步推理等能力层。

然而，一个隐蔽的问题始终存在：模型自身的能力，与现代Web平台真正提供的能力之间，横亘着一道鸿沟。

Google Chrome团队知名工程师 Paul Irish 在一次演示中直言不讳地指出了这个痛点。现代Web标准演进极快，CSS、HTML每年都在引入大量新特性，但大语言模型的训练数据往往滞后，导致它们不总能正确使用这些新功能。更棘手的是，很多时候连开发者本人都不清楚某个新特性的「正确行为」应该是什么样，也就无从判断AI生成的代码是否合理。

这种双重信息缺失，使得AI辅助的Web开发经常出现「能跑，但不够现代、不够健壮」的结果——要么用了过时的实现方式，要么忽略了浏览器兼容与渐进增强。

Modern Web Guidance 项目介绍

为了填补这道鸿沟，Paul Irish 团队推出了一个名为 Modern Web Guidance 的项目。它的定位非常清晰：一套可供编码智能体直接调用的现代Web开发文档集合。

本质上，它是一个「文档包」，但不同于普通文档的地方在于——它以「技能」（skill）的形式暴露给AI编程工具，让智能体在需要时能够主动检索并获取权威的实现指导。这种「文档即技能」（Docs-as-Skills）模式在技术实现上通常包含以下层次：首先是文档层——高质量的Markdown文档，每份聚焦一个具体主题；其次是索引层——将文档内容通过嵌入模型（embedding model）转换为向量并存储在向量数据库中；最后是工具接口层——将检索能力封装为符合智能体工具调用协议（如MCP、OpenAI Function Calling等）的标准接口。这种模式的优势在于知识更新只需修改文档并重新索引，无需重新训练或微调模型，实现了知识维护与模型演进的解耦。

这套指南目前包含 超过100份指导文档（guides），覆盖了现代Web平台的各类能力实现，并且每一份都强调最佳实践。它们并非泛泛而谈，而是针对具体场景给出经过验证的实现方案。

值得一提的是，这些文档本身就是高质量的Markdown内容，即使不通过AI调用，开发者直接在GitHub上阅读也能获得很大价值。

实战演示：让AI正确实现模态对话框

在演示中，Paul Irish 使用了 Anti-Gravity 这一编码环境，尝试添加一个模态对话框（modal dialog）。

这是个很典型的例子：现代CSS已经提供了处理模态对话框的原生方案。HTML的<dialog>元素是HTML5.2中引入的原生对话框组件，它提供了showModal()和show()两个API方法，分别用于打开模态和非模态对话框。相比传统的div+JavaScript自行实现模态框，<dialog>原生支持焦点陷阱（focus trapping）、Escape键关闭、::backdrop伪元素样式化背景遮罩等特性，极大减少了无障碍（accessibility）方面的实现负担。配合CSS的:modal伪类和新的@starting-style规则，开发者还能实现平滑的入场/退场动画。然而由于该元素的完整特性集是逐步成熟的，不同浏览器的支持程度和行为细节仍存在差异——这正是AI容易生成不正确实现的典型案例，也是Paul本人坦言并不完全清楚其正确行为的原因。

RAG检索流程详解

整个交互过程展示了这套工具的核心机制：

1. 触发技能：AI智能体识别到需求后，自动搜索 Modern Web Guidance 技能库
2. 语义检索：以「modal dialogs」为查询词进行搜索
3. 相似度排序：系统采用 RAG 风格的余弦相似度（cosine similarity） 匹配，返回一组带相似度分数的结果
4. 拉取指南：最终获取最相关的那份Markdown指南

RAG（Retrieval-Augmented Generation，检索增强生成）是一种将外部知识检索与大语言模型生成能力相结合的架构模式。其核心思想是：在模型生成回答之前，先从外部知识库中检索与当前查询最相关的文档片段，然后将这些片段作为上下文注入到模型的提示词中。余弦相似度是RAG系统中最常用的相似度度量方法，它通过计算查询向量与文档向量之间的夹角余弦值来衡量语义相似程度，值域为[-1, 1]，值越接近1表示语义越相似。在本项目中，用户的自然语言查询（如「modal dialogs」）首先被嵌入模型转换为高维向量，再与文档库中预计算的文档向量逐一比较，最终返回相似度最高的文档作为智能体的参考依据。

为什么这套流程有效

这套设计的巧妙之处在于，它把「现代Web最佳实践」以结构化、可检索的方式注入到AI的工作流中。智能体拿到的不再是模型记忆里可能过时的知识，而是一份明确告诉它「这才是正确做法」的权威文档。

更重要的是，这些指南内置了完善的兼容性考量：

• 回退策略（fallback strategies）：处理不同浏览器的差异
• 渐进增强（progressive enhancement）：确保基础功能在各类环境下都可用
• Polyfill 建议：在必要时提供垫片方案

渐进增强（Progressive Enhancement）是一种Web开发哲学，主张先确保核心功能在所有浏览器和设备上可用，再在支持更高级特性的环境中逐层叠加增强体验。这与「优雅降级」（Graceful Degradation）形成对比——后者从完整功能出发，再为旧环境做减法。Polyfill则是一种代码垫片，它在不支持某个现代API的浏览器中模拟该API的行为。例如dialog-polyfill可以让不支持<dialog>元素的旧版浏览器也能使用相关功能。在AI生成代码时，如果缺乏这些兼容性考量，生成的代码可能在开发者的Chrome最新版中运行完美，却在用户的实际浏览器环境中出现严重问题。

这意味着AI生成的代码不仅现代，而且在真实的多浏览器环境中足够健壮。

对AI辅助开发的启示与价值

Modern Web Guidance 代表了一种解决AI编程局限性的务实思路。与其等待模型本身知识更新，不如通过 RAG + 权威文档 的方式，为智能体提供实时、可靠的领域知识补给。

这种「文档即技能」模式的核心价值在于：

• 它把「知识时效性」问题从模型内部转移到了可维护的外部文档库，更新成本低；
• 它让编码智能体的输出质量不再单纯依赖模型规模，而是依赖高质量的领域指导；
• 它体现了「技能（skill）」这一交互范式的潜力——AI不只是生成代码，而是学会主动去查阅权威资料。

从更宏观的AI工具生态来看，这一项目揭示了一个重要趋势：未来AI编程的质量竞争，不仅取决于模型本身的参数规模和推理能力，更取决于其能接入多少高质量的、持续更新的领域知识源。这与人类工程师的工作方式高度一致——优秀的开发者从来不是记住所有API，而是知道去哪里找到权威答案。Modern Web Guidance 本质上是在教会AI这一关键能力。

对于Web开发者而言，这套工具既能提升AI辅助编码的质量，其Markdown文档本身也是一份优质的现代Web学习资料。随着越来越多领域采用类似的「文档即技能」模式，AI编程的可靠性有望得到系统性提升。

感兴趣的开发者可以在 GitHub 上查看这套指南的完整内容。

核心要点