1. 简介与设置
欢迎
您好！欢迎来到 Coding Jam。在接下来的 75 分钟内，您将构建一个可正常运行的真实 AI Web 应用。
点击此处查看网站：Coding Jam 网站
构建内容
一款基于本周项目简报的 AI 赋能型 Web 应用。在浏览器中运行。使用 Google 的 Gemini AI。在会话结束时完全归您所有。
安装 Antigravity
Antigravity 是我们将用于处理所有事务的 AI 助理。它是一款安装在电脑上的应用。
第 1 步 - 下载
👉 在浏览器中前往 https://antigravity.google/download。
👉 点击适用于您的操作系统（Mac、Windows 或 Linux）的下载按钮。
👉 运行下载的安装程序。默认设置没有问题 - 点击完成。
第 2 步 - 启动并登录
👉 从“应用程序”文件夹 (Mac) 或“开始”菜单 (Windows) 中启动 Antigravity。
👉 出现提示时，点击登录。
👉 使用您的 Google 账号。
第 3 步 - 验证欢迎界面
您应该会看到 Antigravity 的欢迎界面，其中包含三个大按钮：
- 打开文件夹 - 将现有文件夹作为工作区打开
- 打开代理管理器 - 前往代理信息中心（我们的大部分工作将在此处完成）
- 克隆代码库 - 从 GitHub 下载项目（我们将在第 3A 部分中使用此功能）
如果您想深入了解，请访问 https://antigravity.google/ 查看更多文档。
✅ 检查点：您已安装 Antigravity，已登录，并且看到了包含三个按钮的欢迎界面。
2. 安装所需工具（通过 Antigravity）
Antigravity 需要在您的计算机上安装两个辅助工具：
工具 | 说明（简单易懂） |
uv | 管理 Python（应用后端所用的语言） |
git | 从互联网下载项目文件（Antigravity 使用此功能进行克隆） |
您无需自行输入安装命令。您只需用英语提问，剩下的交给 Antigravity。
第 1 步 - 打开临时工作区
Antigravity 需要打开文件夹才能进行聊天。（没有文件夹 = 无法聊天。）
👉 在欢迎界面上，点击“打开文件夹”。
👉 创建或选择任意空文件夹。建议：在方便的位置（例如桌面）创建一个名为 coding-jam-setup 的新文件夹。
👉 点击打开（或选择文件夹）。
系统会打开代理管理器视图，并选择您的新（空）工作区。
第 2 步 - 要求 Antigravity 检查并安装工具
👉 按 Cmd+L (Mac) 或 Ctrl+L (Win/Linux) 将焦点置于聊天输入框中。
👉 确认底部的模型选择器显示 Gemini 3 Flash（默认 - 适合此任务）。
📝 最简单的提示 - 将此提示粘贴到聊天中：
Install uv and git on my computer if they're not already there.
Don't install Node.js. Ask permission before each install command.
📝 更详细的版本（如果需要）：
Check whether uv and git are installed by running their --version commands.
For any tool that's missing, install it using the best method for my OS:
- Mac: prefer `brew install` (install Homebrew first if missing)
- Windows: prefer `winget install`
- Linux: prefer `apt install` or `dnf install`
Ask permission before each install command.
Do NOT install Node.js — we'll install it later only if needed.
When done, give me a summary of what's installed.
👉 按 Enter 键即可发送。
🤖 观看代理运行，点击弹出式窗口中的“允许”
第 3 步 - 阅读摘要
代理完成操作后，您会看到类似以下内容：
✅ Setup complete:
- uv 0.4.18 ✅ (installed)
- git 2.42.0 ✅ (already had it)
- Node.js: skipped (will install later if needed)
如果出现问题
✅ 检查点：代理确认 uv 和 git 均已安装。总时间：约 3-5 分钟（如果必须先在 Mac 上安装 Homebrew，则约为 7 分钟）。
克隆项目
1 - 选择本周项目
Coding Jam 是一项为期 8 周的计划，每周都会有一个不同的迷你项目。辅导员会告诉您我们今天要做哪一周的练习。找到相应行并复制网址。
周 | 项目 | 代码库网址 |
1 | AI 发型试穿 |
|
2 | AI 虚拟形象生成器 |
|
3 | 我的特别年份日历 |
|
4 | 从冰箱到食谱 |
|
5 | AI 情绪罐 |
|
6 | 单页投资组合 |
|
7 | Resume Tailor |
|
8 | AI 角色对话 |
|
2 - 返回到欢迎界面
我们需要返回到启动界面，才能使用“克隆代码库”按钮。
👉 在 Antigravity 中，克隆您选择的项目。例如，克隆第 1 周的项目，但您需要输入正确的代码库
📝 参考提示
Git clone ⚠️ PASTE_YOUR_PROJECT and save to my local folder: ⚠️ PASTE_YOUR_PROJECT
3 - 项目导览
查看文件列表。您应该会看到：
文件 / 文件夹 | 简介 |
BRIEF.md | 产品创意 - 我们正在构建的产品，用简单的英语描述 |
参考文档/ | 包含可正常运行的示例应用的文件夹。AI 在编写代码时会读取此文件夹，以便您的应用符合相应模式。 |
.gitignore | Git 应忽略的文件列表（技术性 - 请忽略） |
👉 点击
BRIEF.md 打开它，这就是项目创意。
✅ 检查点：您已克隆项目，并以工作区形式打开该项目，还阅读了 BRIEF.md。
3. 安装工作坊技能
技能是一组存储在 GitHub 上的指令，您可以将这些指令交给 AI。
第 1 步 - 要求 Antigravity 安装技能
📝 将以下提示粘贴到对话中：
Please install the workshop skills into this workspace's .agent/skills/
folder. Run these two git clones from the project root:
1. git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
2. git clone https://github.com/google-gemini/gemini-skills .agent/skills/gemini-skills
When Antigravity asks permission to run each command, I'll click Allow.
When done, list the skills that are now available in this workspace.
第 2 步 - 点击两个弹出式窗口中的“允许”
🤖 您应该会看到类似如下所示的内容
I'll create the .agent/skills/ folder and clone both repos into it.
Running: git clone https://github.com/cuppibla/skills-garden .agent/skills/skills-garden
如果智能体提示，则允许执行任何操作。
👉 检查文件列表。您现在应该会看到一个新的 .agent/ 文件夹。点击展开该文件夹，确保其中包含多个技能，例如 skills-garden 和 gemini-skills。
每项技能的作用（仅供参考，无需执行任何操作）
Skill | 作用 |
| 撰写产品设计文档 |
| 撰写用户体验设计文档 |
| 撰写工程设计文档（包含测试策略部分） |
| 编写测试、运行测试、自动修复失败（最多尝试 3 次） |
| 官方 Google 技能 - 如何正确使用 Gemini API |
| 如果官方技能不可用，可使用更简单的备份方式 |
| 视觉风格参考 |
✅ 检查点：您的文件列表显示了一个新的 .agent/skills/ 文件夹，其中包含 skills-garden/ 和 gemini-skills/。
4. Spec Talk
规范对话是一段 2 分钟的对话，您可以在其中告诉 AI 您想构建什么内容。没有代码、没有文档，尚未构建任何内容。我们只是讨论一下。
一个必答题
AI 需要了解的最重要信息：
“输入什么，输出什么？”
🎯 模型：Gemini 3 Flash（默认）- 简单问答。
📝 粘贴以下内容：
Here's what's in @BRIEF.md. Before we lock the spec, ask me 3 short
questions to refine it:
1. What's the one input I want the user to provide?
2. What's the magical moment for the user?
3. What are we deliberately NOT building (to keep scope tight)?
DO NOT generate any plans, docs, or code yet. Just ask me the questions
and wait for my answers.
🤖 与 AI 对话并优化您的方案
暂时不生成文档
在 Spec Talk 结束时，代理不应生成任何文件。如果您看到 product.md 或其他新文件，可以告诉代理：“停止 - 删除您刚刚创建的所有文档。我们仍处于“规格讨论”阶段。
提示
✅ 检查点：您已与 Antigravity 就您的产品创意进行简短对话，并且 Antigravity 了解输入和输出。尚未生成任何文件。
5. 生成 3 份设计文档
现在，AI 会先在纸上写出三个方案，然后再编写任何代码。我们使用三个设计文档技能按顺序在一个提示中完成这三项任务。
3 个文档
文件 | 包含的产品 | 使用的技能 |
product.md | 用户是谁、我们要解决的问题、 |
|
ui.md | 屏幕外观、颜色、字体、布局 |
|
engineering.md | 技术栈、文件结构、+ 测试策略部分 |
|
第 1 步 - 一次性生成所有三份文档
🤖 切换到 Gemini 3.1 Pro（低思考）（推荐）
📝 粘贴以下提示，一次性完成这三项任务：
Apply all three design-doc skills in this order:
1. pm-design-doc from .agent/skills/skills-garden/design-doc-skills/pm-design-doc/
→ Generates product.md
2. ux-design-doc from .agent/skills/skills-garden/design-doc-skills/ux-design-doc/
→ Generates ui.md (based on the product.md you just created)
3. eng-design-doc from .agent/skills/skills-garden/design-doc-skills/eng-design-doc/
→ Generates engineering.md (based on product.md, ui.md, and @BRIEF.md)
→ MUST include a "Testing strategy" section with real content
(specific functions to unit-test, one integration test per major flow,
and what's deliberately NOT being tested)
Use the patterns in @reference/ as guidance for the engineering doc
(but vary if the brief justifies it).
Save all three files in the project root. After each one is saved,
briefly confirm what you saved before moving to the next.
When all three are done, give me a final summary listing the section
titles in each file.
第 2 步 - 验证文件是否已保存
👉 检查文件列表。现在，您应该会看到（除了之前的内容之外）：
codingjam-week-1/
├── product.md ← NEW
├── ui.md ← NEW
├── engineering.md ← NEW
├── BRIEF.md
├── reference/
└── .agent/
第 3 步 - 查看和迭代
您是老板。AI 撰写了计划。现在，您需要阅读该文档并请求更改。
最重要的习惯
当您想要进行更改时，请更改 DOC，而不是代码。该文档是可信来源。
🤖 阅读并查看所有三份文档
👉 依次打开每个文件（在文件列表中点击），从上到下：
product.md- 这是否描述了我想要的内容？ui.md- 界面和外观是否正确？engineering.md- 测试策略是否合理？（您无需了解技术细节，只需确认有相应方案即可。）
🤖 现在文档已准备就绪，请继续执行后续步骤。
6. 实施 + 测试
Codelab 中最大的部分。AI 会获取这三个文档并构建应用，一次性生成代码和测试。本部分结束时，您将获得一个可以通过自身测试的有效代码库。
为何要将代码和测试放在一起？
您的 engineering.md 已指定应存在哪些测试（“测试策略”部分）。只有在这些测试通过后，实现才算完成。因此，我们会在一个阶段中同时执行这两项操作。
🤖 切换到 Gemini 3.1 Pro（高思维）（推荐）
第 1 步 - 让 AI 构建代码和测试
📝 粘贴以下内容：
You're going to do two things in one shot.
PART 1 — IMPLEMENT THE APP CODE
- Build it according to @engineering.md (stack, file structure)
- Match the UI described in @ui.md
- Use the patterns in @reference/ as guidance for code style
- Backend: use Python with `uv` for dependency management
- If your chosen stack requires Node.js and it isn't installed on my
system, install it via Antigravity (use brew/winget/apt) — ask
permission first
- DO NOT start any dev servers — that's a later section
PART 2 — APPLY THE TEST-GATE SKILL
After the code is written, apply the test-driven-dev skill from
.agent/skills/skills-garden/eng-skills/test-driven-dev.md.
Use the "Testing strategy" section in @engineering.md as the test plan.
IMPORTANT: Mock the Gemini API calls in tests — use a stub that returns
fake response data. The real API key isn't set up yet, and tests should
be deterministic and free anyway (best practice).
The skill should:
1. Write the tests described in the Testing strategy
2. Run them (use pytest for Python, Vitest or Jest for JS)
3. If any fail, fix the CODE (not the tests) and re-run
4. Up to 3 retry attempts max
5. If still failing after 3 tries, STOP and tell me what's broken
When Antigravity asks permission to run commands (uv sync, uv pip
install, pytest, etc.), click Allow.
Report results when both parts are done.
🤖 点击“允许弹出式窗口”（多次）
第 2 步 - 阅读最终报告
完成后，请检查以下内容：
- ✅ 存在包含代码的
backend/文件夹 - ✅ 存在包含代码的
frontend/文件夹 - ✅ 存在包含测试文件的
tests/文件夹 - ✅ 摘要显示“所有测试均通过”（而不是“重试 3 次后失败”）
- ✅ 代理未启动任何服务器
如果所有 3 次测试重试均失败，该怎么办？
虽然很少见，但有可能发生。这通常意味着工程文档的测试策略对于已构建的内容来说是不切实际的。
📝 粘贴以下内容：
The auto-fix loop hit the 3-try cap. Pull up @engineering.md and look
at the Testing strategy section. Is the strategy realistic for what
got built? Suggest updates to the doc so the tests align with reality.
Don't change the code yet — update the doc, then re-apply the
test-driven-dev skill.
如果发现异常情况，该怎么办？
👉 如果 AI 构建的内容与文档不符，请返回文档，不要单独要求 AI“修复代码”。
示例：
I see you built the chat as a popup, but @ui.md says it should be a
full page. Either update ui.md if a popup is actually better, OR
rebuild the chat as a full page to match the current ui.md.
始终：文档是可信来源。
✅ 检查点：代码存在、测试存在、测试通过。准备好设置 API 密钥。
7. Google Cloud + API 密钥设置
第 1 步 - 从 AI Studio 获取 Gemini API 密钥（1 分钟）
- 在新浏览器标签页中打开 https://aistudio.google.com/app/apikey。
- 登录了同一 Google 账号。
- 点击右上角的“创建 API 密钥”。
- 系统会打开一个对话框，其中包含项目下拉菜单：
- 如果您之前已创建 Google 项目，可以选择该项目，然后点击“在现有项目中创建 API 密钥”
- 如果不在列表中：点击“创建项目”。
- 复制显示的 API 密钥。以
AIza...开头，约 40 个字符。
✏️ 将其粘贴到安全的位置 - 接下来您将把它提供给 Antigravity。
第 2 步 - 告诉 Antigravity 设置 .env（30 秒）
返回到 Antigravity，打开对话。
⚠️ 停止。粘贴之前请先阅读此内容。
以下提示包含 PASTE_YOUR_API_KEY_HERE 和 PASTE_YOUR_PROJECT_ID_HERE 占位符。
您必须将这些值替换为步骤 1 中的实际值，否则 .env 文件将包含字面意义上的 ⚠️ PASTE_... 文本，并且您的应用将无法正常运行。
在点击“发送”之前，请扫描提示并确认您看到以下内容：
GEMINI_API_KEY=AIzaSy...（以AIzaSy开头，约 40 个字符）
如果您仍然看到
⚠️ PASTE_...
提示中的任何位置，但请勿立即发送，请先替换它们。
📝 要粘贴的提示（替换
⚠️ PASTE_...
标记优先！）：
Apply the gemini-api-dev skill from .agent/skills/gemini-skills/skills/gemini-api-dev/.
(If that skill isn't found, fall back to .agent/skills/skills-garden/eng-skills/gemini-api.md)
Create a .env file in the backend folder with these settings:
- GEMINI_API_KEY= ⚠️ PASTE_YOUR_API_KEY_HERE
- Any other env vars the app needs based on @engineering.md
Also verify:
- .env is in .gitignore so the key never gets committed
- The backend code reads GEMINI_API_KEY at startup
- The Gemini SDK is initialized correctly (use google-genai for Python)
When Antigravity asks permission to install Python packages, click Allow.
When done, show me the .env contents with the KEY redacted (just first 6 chars + ...).
🤖 预期：代理创建 .env，安装 google-genai（您点击“允许”），并使用已遮盖的密钥进行确认：
✅ .env created at backend/.env
GEMINI_API_KEY=AIzaSy... (40 chars, redacted)
.env is already in .gitignore ✓
Backend reads GEMINI_API_KEY via os.getenv() ✓
Gemini client initialized ✓
8. 预览和验证
代码已构建。测试通过。API 密钥已配置。现在打开应用，随意点击。
人类能发现（但测试会遗漏）的问题
测试捕获 | 人类捕捉 |
返回值有误 | 难看的颜色 |
函数调用中断 | 令人困惑的文案 |
缺少导入 | 位置奇怪的按钮 |
差一错误 | 动画感觉卡顿 |
逻辑 bug | 氛围不佳 |
第 1 步：让 Antigravity 启动开发服务器
🎯 MODEL：默认（闪光）即可。
📝 粘贴以下内容：
Please start the dev server(s) so I can preview the app in my browser.
Tell me the URL when it's ready. When Antigravity asks permission to
run the server command, I'll click Allow.
🔔 弹出式窗口：uv run uvicorn main:app --reload（或类似内容）→ 点击允许
第 2 步 - 打开预览网址
🤖 代理报告：
Backend running at: http://localhost:8000
Frontend served at: http://localhost:8000 (backend serves it)
网址通常为 http://localhost:8000 或 http://localhost:5173。
👉 点击聊天中的网址，或将其复制并粘贴到新的浏览器标签页中。
第 3 步 - 随意点击
像真实用户一样使用它：
- 点击每个按钮
- 输入内容
- 将鼠标悬停在内容上
- 尝试从头到尾完成主要流程
如果一切看起来和感觉都正常，请跳至第 9.7 步（撰写 README）。只有在发现问题时，才需要执行步骤 9.4-9.6。
第 4 步 - 编写 README
应用正常运行后，请锁定它：
📝 粘贴以下内容：
The app works! Please create a README.md in the project root that explains:
- What this app does (in plain English)
- How to install it on a new machine (uv sync, etc.)
- How to run the dev server(s)
- The 3 design docs (@product.md, @ui.md, @engineering.md) are the
source of truth — anyone can read them to understand the system
Save it as README.md.
🤖 预期： README.md 会显示在文件列表中。
README 的重要性
✅ 检查点：您已在应用中点击浏览，修复了所有问题（如有），并保存了自述文件。
9. 🎉 您发布了 MVP！
你做到了
您构建的内容
- ✅ AI 赋能的 Web 应用
- ✅ 三份设计文档（
product.md、ui.md、engineering.md） - ✅ 每次更改代码时都会运行的真实测试套件
- ✅
README.md，以便您随时返回此页面 - ✅ 连接到 Google 的 Gemini AI
您从想法 → 可正常运行的应用，无需自己编写任何代码。太疯狂了。
学习内容
Skill | 重要意义 |
规范 → 代码+测试 → 验证 | 先制定计划。同时构建代码和测试。最后点击“环绕”。始终按此顺序。 |
修复文档，而不是代码 | 如果出现问题，请更改方案并重新构建。不修补。 |
测试作为安全门 | 内置于实现中 - AI 会在您发现之前发现愚蠢的错误。 |
回归规则 | 每个人工发现的 bug 都会成为一个测试。相应 bug 永远不会再出现。 |
基于文档的透视 | 当方向发生变化时，更改文档，其余工作交给 AI 处理。 |
Antigravity 3 层流程 | 在对话中输入英文 → 智能体选择命令 → 您批准。 |
下周回来？
- 从 8 周表格中选择其他行
- 通过 Antigravity 的“克隆代码库”按钮克隆当周的代码库
- 技能会针对每个工作区全新安装（工作区范围 = 无剩余状态）
- 您可以重复使用同一 Google Cloud 项目
- 其他所有步骤都与您刚刚学到的工作流程相同
后续步骤
- 发布项目：在 Coding Jam 网站上发布您的项目！
- 在家办公：您的三个文档均可携带。在任意 AI 工具中打开它们，然后继续构建
- 结交新朋友：通过此 Codelab 与新朋友配对。教学是学习的最快方式