超越了 Web 氛围编程

1. 简介

随着编码智能体成为日常软件开发中不可或缺的一部分，无论您是经验丰富的工程师，还是希望发布首款应用的新手开发者，您构建应用的方式和构建的应用都在发生根本性变化。开始使用编程智能体时，您通常会从“零样本”提示词入手，即用简短的人类语言说明您想要的结果。但很快就会遇到问题：

  • 讨好人类的偏见：模型通常会接受有缺陷的限制条件或前提，力求尽快完成您的请求，但不会验证其生成的内容是否确实符合您的预期。
  • 验证缺口：即使代理编写了测试，他们通常也不会检查自己的工作，以确保其正常运行。在实时浏览器中尝试使用网站会发现隐藏的 bug、损坏的布局和无法访问的控件。
  • 技术债务：由于模型的训练和工作方式，它们编写的代码倾向于旧的和过时的模式，从而增加技术债务，这不仅会消耗更多 token，还会消耗更多的人力和机器时间与精力来管理。技术债务甚至会对用户体验产生负面影响。

4 步游戏计划

为帮助引导编码代理生成更符合您要求的优质代码，请考虑遵循 4 步产品开发生命周期：

  1. 规划和设计：与代理共同撰写产品需求文档 (PRD)，让代理在浏览器中对 PRD 进行原型设计和设计，然后在开始生产实现之前，根据您的 PRD 和设计草拟架构设计文档（规范），然后再开始编码。
  2. 编码和构建：指示智能体根据 PRD、设计和规范进行构建，而不是根据零样本提示进行构建，并让智能体运行另一个智能体来检查其工作。
  3. 冲洗并重复：针对要添加的每个新功能，再次执行第 1 步和第 2 步。
  4. 部署：发布到生产环境。

本文档将引导您了解如何将 AI 智能体用作积极的协作伙伴，并介绍相关实践，以帮助您减少技术债务并提高输出代码质量。您可以使用 Antigravity 搭配Modern Web Guidance和 DevTools for Agents 来构建休闲文字游戏，并使用 AI 功能对其进行增强。然后，您可以使用 Firebase 将其部署到 Google Cloud，以便与亲朋好友分享。

学习内容

  • 如何将 AI 编码任务视为小型产品开发生命周期。
  • 为何应将产品要求与架构规范分开。
  • 如何编排多智能体工作流，以便直接在浏览器中进行原型设计并查看代码。
  • 如何利用第三方技能和工具来改进开发和用户体验。
  • 如何使用 Firebase MCP 将 Web 应用直接部署到生产环境。

前提条件

  • 个人 Google 账号和 Google Cloud 或 Firebase 项目（有关说明，请参阅项目设置）
  • 对 HTML、CSS 和 JavaScript 有一定的了解。
  • 网络浏览器，例如 Chrome。
  • 已安装 Node.js（建议安装 LTS 版本）。

2. 项目设置

Google 账户

如果您还没有个人 Google 账号，可以创建一个 Google 账号。

登录 Google Cloud 控制台。

使用个人 Google 账号登录 Google Cloud 控制台。

启用结算功能

如需设置个人结算账号，请在 Cloud 控制台中前往启用结算功能。

创建 Firebase 项目

  1. 前往 Firebase 控制台，然后使用您的个人 Google 账号登录。
  2. 点击添加项目（或创建项目）。
  3. 在项目创建向导中：
    • 输入项目名称（例如 wordup-web-app），或重复使用您在项目设置期间设置的 Google Cloud 项目。
  4. 关联结算账号
    • 在 Firebase 控制台边栏中，找到底部的方案徽章（显示“Spark”）。点击升级。
    • 选择随用随付方案。
    • 选择您在项目设置步骤中设置的结算账号。
    • 确认选择，将结算账号关联到项目。（Firebase Hosting 提供慷慨的免费层级；完成本教程通常不会产生任何费用）。

安装工具

  • Antigravity 2.0：您使用的主要智能体编码框架，搭配最新的 Gemini Flash 模型，可实现快速、前沿的编码。
  • Modern Web Guidance：用于帮助编码智能体编写现代 CSS、HTML 和 JavaScript 的技能。通过 Antigravity 安装：Settings > Customization > Build With Google Plugins > Modern Web Guidance。
  • 面向智能体的开发者工具：让智能体能够驱动 Chrome、检查实时 DOM、测试布局，并在运行时进行调试。通过 Antigravity 设置 > 自定义 > 使用 Google 插件构建 > Chrome 开发者工具和 Antigravity 设置 > 自定义 > 添加 MCP 服务器 > 面向智能体的 Chrome 开发者工具进行安装。
  • Firebase MCP 服务器：可实现无缝项目设置和一键式部署。通过 Antigravity 安装 Settings > Customization > Build With Google Plugins > Firebase and Antigravity Settings > Customization > Add MCP Servers > Firebase。

3. 从制定计划着手

在智能体编码中，人们通常会忍不住提交零样本提示（“帮我构建一个文字游戏”），然后就希望一切顺利。这几乎总是会导致跳过边缘情况、代码库臃肿和无休止的 bug 修复周期。

相反，应将每个任务视为一个小型产品开发生命周期。编码智能体具有研究和推理工具，可充当协作伙伴，帮助您在编写任何代码之前理清思路。将想法说出来通常有助于您在问题出现之前发现并解答问题，这在软件工程中称为橡皮鸭调试法。您可以将编码智能体用作橡皮鸭，来规划项目和功能。

您正在构建一款休闲文字游戏。提示代理帮助您设计所需的游戏。

I want to make a casual word guessing game. Go do deep research on those kinds
of games, then ask me questions to help me write a PRD for the game's features.

这是提示的基本格式，您可以根据自己的需求进行调整。这里的关键在于，让它进行深入研究，并根据研究结果向您提问，以帮助您规划工作。

先从这个提示入手，因为使用编程智能体需要进行大量检查。将完整的实施计划分解为更小的专注部分，可以更轻松地进行审核，让您尽早发现极端情况，引入代理训练数据之外的知识，最重要的是，让您在审核期间有更多休息时间。

  • 将“是什么”与“如何做”分开：在正式的产品需求文档 (PRD) 中定义用户体验和产品范围，可将想要实现的目标与实现方式分开，让您一次专注于产品开发的一个方面，而不是同时处理所有方面。
  • 尽早发现极端情况：互动式问答会话可让您在开始设计或实现之前明确要求。
  • 主动智能体研究：由于智能体训练会在特定日期停止，并且其中的信息会高度总结，因此从实时研究中提取信息可以带来智能体原本会错过的全新信息。

练习 1

现在该您亲自试试了！设置项目并构建 PRD。

  1. 向 AGENTS.md 文件添加一条指令，让它将输出保存到 docs/plans/{{YYYY-MM-DD}}-{{description}}.md。
  2. 运行上述研究提示（可根据需要进行调整），以构建 PRD。
  3. [拓展目标] 使用您发现智能体在执行的您不喜欢的事情来更新 AGENTS.md 文件，然后再次运行提示。

4. 在浏览器中设计

静态界面设计依赖于通常看起来很棒但可能无法考虑极端情况、限制和实际用户互动的模拟。与代码类似，要求代理“设计”您的网站应用会导致设计趋向于通用（通常为紫色）设计。

对于 Web 应用，您可以使用代理通过 DevTools for agents 控制 Web 浏览器的能力，在浏览器中进行设计。无论您是致力于提高设计保真度的设计师，还是希望改进项目界面和用户体验的编码人员或构建者，抑或是两者兼而有之，在您要构建的实际媒介中工作都能产生更好的效果。

在浏览器中设计还可以让您协调多个智能体协同工作，生成单个输出。这些子智能体是具有特定角色和目标的智能体，可以进行协调，从而产生比单个智能体单独工作更好的结果。在设计方面，您可以请求视觉设计智能体、用户体验智能体和无障碍功能智能体共同协作，帮助您完成设计，并直接在浏览器中向您展示设计成果。

启动设计代理专家组，帮助您根据 PRD 选择设计。

Using the PRD, start a panel of expert agents: one UX design, one web
accessibility, and one for visual design, and have them work together to design
3 different UI mockups and show them to me in-browser.

在您要构建的媒介（在本例中为 Web）中进行设计，而不是在静态媒介中进行设计，这样一来，您就可以发现难以管理的其他极端情况和限制，并获得与实际生产环境一致的即时视觉反馈。

练习 2

现在该您亲自试试了！设计项目。

  1. 运行上述设计提示，并根据需要进行调整，以构建设计。提供您希望看到的各种设计方向（例如现代、活泼、写实等）。
  2. 选择您喜欢的设计，然后与智能体一起对其进行迭代。
  3. 让您的代理更新 PRD，使其指向商定的设计。
  4. 拓展目标：针对所选设计运行无障碍功能测试和自适应设计测试，并根据这些审核结果调整设计。

5. 编写规范

在 PRD（“要构建什么”）获得批准且视觉设计（“外观如何”）选定后，您现在需要就架构（“如何构建”）达成技术上的一致。

技术设计文档或规范（简称“规范”）详细说明了文件结构、状态管理、组件接口、事件管道和依赖项。在编写代码之前创建规范，可让您尽早发现不一致和不良的编码模式，避免它们变成难以推理和重构的代码。

Write a detailed technical design document on how to implement the game with
the chosen design.

您为何要这样做

  • 架构清晰度：定义组件层次结构和状态转换流程（例如 Idle → InGame → EvaluatingGuess → GameOver）可防止出现竞态条件和脆弱的意大利面式代码。
  • 与现代标准保持一致：启用 Modern Web Guidance 后，代理会引用现代标准（例如 CSS @container 查询、用于模态框或帮助叠加层的内置 元素和模块化 ES 模块），而不是拉取旧版大型库。
  • 分阶段进行审核：将功能性 PRD 审核与技术设计文档审核分开，可让您独立评估架构和用户体验。

练习 3

  1. 指示 AGENTS.md 将输出保存到当前文件夹：
    PRDs should _always_ be written to the current project's root in `docs/plans/{{YYYY-MM-DD}}-{{description}}.md` format
  2. 运行设计文档提示并查看，确保其涵盖目录结构、事件处理和存储等各个方面。
  3. 扩展目标：如果尚未包含，则添加 Mermaid 图表来解释应用中的状态流。

6. 最后，构建应用

PRD、界面模拟和设计文档都已确定，现在可以开始构建了。这三项内容为代理提供了清晰明确的指导，指明了代理应制作的内容。

这是使用子智能体的另一个好机会。您可以在构建代码后运行这些测试，以检查构建的内容与预先设计有多接近，还可以运行另一个测试来检查构建的内容的代码质量。

Use the PRD, design doc, and mockup to implement the site, then send out 2
agents, one to check how closely you followed the requirements, and one to
review the code.

您为何要这样做

通过规范驱动的开发和第一轮审核人员，您的代理可以根据清晰、预先审核的要求进行构建，并且在交付给您之前，会有新的审核人员确保代理遵循了计划，从而提高质量和保真度。

  • 经过审核的要求：智能体无需猜测您想要什么；在编写任何代码之前，您已经审核了除实现之外的所有内容。
  • 全新视角：在新的上下文中生成的审核智能体在构建代码库时不会出现确认偏差，因此能够有效地发现未处理的极端情况、缺失的实现要求以及其他被忽略的代码或产品细节。

练习 4

  1. 运行 build 提示，指向您希望它检查的确切文件。
  2. 观看输出的运行情况。您会看到它在尝试构建时，会根据您的要求进行推理。如果发现有失控的迹象，您可以及时制止并纠正。
  3. 让它运行您的开发服务器，以查看最终网站并检查其工作。
  4. 拓展目标：再次完成此流程，添加自动化测试。
  5. 扩展目标：选择您希望它使用哪个特定的框架或技术堆栈来构建网站 - 由于 PRD、模拟和设计文档是分开的，因此应该很容易适应不同的框架或技术堆栈。

7. 部署到生产环境

您已完成规划、设计和编码。还剩下什么？部署到生产环境。

Deploy this site to my Firebase project [YOUR_PROJECT_ID] using Firebase
Hosting.

练习 5

  1. 运行部署提示，替换为您的项目 ID。
  2. 复制代理提供的直播托管网址。
  3. 打开实际网址，验证其是否已部署并正常运行。
  4. 拓展目标：使用适用于智能体的开发者工具对您的正式版网站运行 Lighthouse 审核，进行调整以提高 Lighthouse 得分，并发布更新。

8. [可选] AI 增强功能

您的字词游戏现在可以使用静态字典正常运行了。若要将静态字典更改为动态字词，您可以每次使用 Prompt API 中的小型本地语言模型提示用户输入字词。

由于并非所有设备都支持此功能，因此您可以使用渐进增强来检查 API 和模型是否可用。如果存在，则使用这些动态列表；如果不存在，则回退到静态列表。

练习 6

将您学到的所有知识融会贯通，并付诸实践。

  1. 与您的代理合作，编写 PRD 以使用 Prompt API 生成有效的隐藏字词。
  2. 在浏览器中设计下载进度条和集成 AI 的界面。
  3. 为实现编写规范。（提示：运行代理，确保此处使用了正确的 API 语法。）
  4. 开发新功能。
  5. 将其部署到生产环境。

9. 收尾

恭喜！您已成功使用代理式编码最佳实践构建、优化、增强和部署了现代化的、无障碍的 AI 优先 Web 应用。

要点回顾

  • 以产品为导向的智能体工作流：如何将任务视为迷你产品生命周期（PRD → 设计 → 规范 → 构建），从而减少债务、审核开销和来回摩擦。
  • 多智能体专家小组：运行多个 AI 子智能体如何有助于提高工作质量和保真度。
  • PRD 与设计文档：为什么将功能范围（计划）与技术架构（规范）分开，比零样本功能提示更具可扩缩性和准确性。
  • 无缝部署：如何使用 MCP 服务器（例如 Firebase MCP）简化对第三方系统（例如部署网站）的访问。