使用 Antigravity 和 Spec-kit 進行規格導向的 ADK 代理開發

1. 簡介

為現有代理程式新增功能 (新的資料庫支援功能) 通常表示要編寫樣板、整合整合項目，並確保所有項目與程式碼集中的模式一致。Antigravity 可加速這項程序的每個階段：分析程式碼集以建立所需脈絡、產生結構化規格和實作計畫供您審查，以及執行程式碼變更。所有作業都以領域知識為指引，協助您擷取可重複使用的技能，並制定專案章程來強制執行不可協商的原則。本程式碼實驗室介紹如何透過導入新週期，大幅參考 spec-kit，加強規格文件，進而提升 Antigravity 規格導向開發範例的效能。

建構項目

在本地執行的餐廳服務應用程式，透過完整的 SDD 週期新增預訂功能：

• 預訂訂位：顧客可預訂座位及查看預訂資訊，這項功能由新的 MCP Toolbox 資料庫工具和 Cloud SQL reservations 資料表提供支援
• (挑戰) – 為代理程式開發專屬 UI
• (挑戰) –在 Antigravity 代理程式的協助下部署至 Google Cloud

範例程式碼提供可運作的 ADK 代理程式，其中包含菜單搜尋 (透過 MCP Toolbox 進行關鍵字 + 語意搜尋) 和飲食偏好追蹤 (透過 ToolContext)。您不必手動編寫應用程式程式碼，即可擴充功能，Antigravity 會根據您的規格處理實作作業。

課程內容

• 如何啟動專案環境，讓 Antigravity 瞭解現有程式碼
• 如何建立 Antigravity 技能，將網域知識 (例如 ADK 程式碼研究室模式) 封裝以供重複使用
• 如何設定專案章程，供 SDD 工作流程在規劃和分析期間進行驗證
• 瞭解如何在 Antigravity 中使用 Spec-Driven Development (SDD) 工作流程，有系統地新增功能
• 如何透過 MCP Toolbox，使用新的資料庫支援工具擴充 ADK 代理

必要條件

• 本機電腦已安裝 Google Antigravity 和 git
• 已啟用有效帳單帳戶的 Google Cloud 帳戶
• 建議您先完成四個先決條件 ADK 程式碼研究室 (或具備同等知識)，有助於瞭解用途情境：
• 使用 ADK 建構 AI 代理：基礎知識
• 使用 ADK 建構 AI 代理：加入工具
• 使用 ADK 和 CloudSQL 建構持續性 AI 代理
• 在 Cloud Run 部署、管理及觀測 ADK 代理
• 資料庫即工具：運用 ADK、MCP Toolbox 和 Cloud SQL 建構代理式 RAG

2. 設定環境

重要注意事項：

本教學課程需要具備有效帳單帳戶的 Google Cloud 專案。如果沒有，請使用本程式碼研究室頂端的橫幅，取得可用於本教學課程的試用帳單帳戶。

這個步驟會複製入門存放區、向 Google Cloud 進行驗證、佈建 Cloud SQL 資料庫，並準備本機 Antigravity 環境。

附註：本程式碼實驗室完全在本機電腦的 Google Antigravity 中執行。設定程序包括使用 gcloud CLI 指令手動驗證

安裝必備條件

請確認系統具有下列 CLI 可執行檔：

• git
• gcloud
• uv
• npm

安裝說明會因電腦的作業系統而異。

複製範例存放區

在 Antigravity (或系統終端機) 中開啟終端機。複製隨附存放區並輸入目錄：

git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy

在 Antigravity 中開啟複製的存放區。依序點選「File」->「Open Folder」->選取複製的目錄「sdd-adk-agents-agy」

移除上游遙控器。SDD 工作流程會為功能規格建立 git 分支版本，移除遠端可避免意外推送至起始存放區：

git remote remove origin

重要事項：本程式碼研究室中的 SDD 工作流程會使用 git 分支機構來整理功能規格。移除 origin 遠端，確保本機分支版本和修訂版本保留在本機。如要備份工作，請新增自己的遠端：git remote add origin <your-repo-url>

使用 Google Cloud 進行驗證

執行兩項驗證指令。兩者都會開啟瀏覽器進行 OAuth：

gcloud auth login
gcloud auth application-default login

附註：在第二個 OAuth 指令中，系統會提示您選取權限。查看所有選項

附註：請務必使用申請試用帳單帳戶的電子郵件地址進行驗證

由於您是在本機使用 Antigravity，因此請手動驗證。auth login 會驗證 gcloud CLI。application-default login 驗證應用程式使用的 Google Cloud SDK，包括 ADK 的 Vertex AI 呼叫和 Cloud SQL Python 連接器，兩者都依賴應用程式預設憑證。

設定 Google Cloud 專案

在執行專案設定指令碼前，請先將位置變數寫入 .env：

echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env

• GOOGLE_CLOUD_LOCATION=global 用於 Vertex AI / Gemini API 呼叫。
• REGION=us-central1 用於 Cloud SQL 和其他 GCP 基礎架構

重要事項！以下步驟旨在協助您快速設定連結至試用帳單帳戶 (嚴格) 的 Google Cloud 專案。如要使用先前的專案，可以略過下列步驟，改為執行下列步驟：

在 .env 檔案中，將自己的專案名稱新增為 GOOGLE_CLOUD_PROJECT 變數

使用 gcloud config set project your-project-id 在終端機中啟用專案

然後直接跳到「啟用 API」

如果不確定，請繼續閱讀下節

下載並執行專案設定指令碼。這會建立或驗證具有試用帳單的 Google Cloud 雲端專案，並將專案 ID 儲存至 .env，然後提供來源：

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

bash setup_verify_trial_project.sh && source .env

正在啟用 API

啟用必要的 API：

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  cloudresourcemanager.googleapis.com

注意：啟用 API 可能需要一些時間。這項操作每個專案只需執行一次。

安裝依附元件

我們將使用 uv 做為 Python 專案管理員。uv 是以 Rust 編寫的快速 Python 套件和專案管理員 ( 文件)。本程式碼研究室使用 uv 是為了簡化程序並加快速度。安裝 Python 依附元件：

uv sync

然後使用專案設定更新 ADK 代理程式的 .env 檔案：

cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF

準備資料庫基礎架構和資料

設定資料庫密碼並新增至 .env：

export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env

重要事項：上述硬式編碼密碼僅供教學用途。在正式環境中，請使用 Secret Manager 等服務安全地儲存憑證，並在執行階段參照這些憑證，切勿將純文字密鑰提交至原始碼控管。

接著，執行 scripts/setup_database.sh 指令碼，準備好所有必要基礎架構。這項操作會執行下列動作：

• 建立 Cloud SQL 執行個體
• 檢查執行個體是否準備就緒
• 授予 Vertex AI 權限
• 建立資料庫
• 填充資料庫
• 在背景執行 MCP Toolbox 服務

chmod +x scripts/setup_database.sh
./scripts/setup_database.sh > database_setup.log 2>&1 &

這項指令會在背景執行設定，您可以定期檢查 database_setup.log 檔案的輸出內容

現在，我們應該擁有所有必要的入門 ADK 代理程式存放區，可以開始作業。現在，在等待一切就緒的同時，我們將在下一節中進一步說明 Antigravity 和規格導向開發

3. 探索範例程式碼並瞭解規格導向開發

這個步驟會逐步說明範例程式碼結構、介紹規格導向開發方法、植入資料庫，並驗證基本代理程式是否正常運作，再開始擴充。

專案架構

在 Antigravity 編輯器中開啟複製的存放區專案，然後檢查目錄版面配置：

sdd-adk-agents-agy/
├── .agents/
│   ├── workflows/                 # SDD slash commands (/speckit.*) – manual trigger
│   │   ├── speckit.specify.md
│   │   ├── speckit.clarify.md
│   │   ├── speckit.plan.md
│   │   ├── speckit.tasks.md
│   │   ├── speckit.analyze.md
│   │   ├── speckit.implement.md
│   │   ├── speckit.checklist.md
│   │   └── speckit.constitution.md
│   ├── skills/                   # Antigravity skills (loaded on demand, agent determined)
│   │   ├── mcp-toolbox-postgres/
│   │   │   └── SKILL.md     # MCP Toolbox config skill
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis skill
│   └── rules/               # Always-active context
├── .specify/                # spec-kit SDD templates and memory
│   ├── memory/constitution.md
│   ├── templates/
│   └── scripts/
├── restaurant_concierge/    # ADK agent package
│   ├── __init__.py
│   ├── agent.py             # LlmAgent + ToolContext tools + Toolbox integration
│   └── .env                 # Vertex AI configuration
├── server.py                # FastAPI server wrapping the agent
├── tools.yaml               # MCP Toolbox tool definitions
├── scripts/                 # Setup scripts
└── pyproject.toml

金鑰檔案

代理應用程式檔案

• restaurant_concierge/agent.py - 核心代理程式。LlmAgent，結合 MCP Toolbox 資料庫工具和以 ToolContext 為基礎的飲食偏好追蹤功能。代理會從 Toolbox 伺服器載入所有工具，並新增兩個使用 ToolContext 管理狀態的 Python 函式 (save_dietary_preference、get_dietary_preferences)。
• tools.yaml - MCP Toolbox 工具定義。定義三種選單搜尋工具：關鍵字搜尋 (search_menu)、透過 pgvector 進行語意搜尋 (semantic_search_menu) 和類別篩選器 (get_menu_by_category)。目前沒有預訂工具，您稍後會新增這些工具
• server.py：最精簡的 FastAPI 伺服器，展示如何以 FastAPI 物件的形式存取 ADK。ADK 的 get_fast_api_app() 提供內建端點，包括 SSE 串流和工作階段管理 API 的 /run_sse。

Antigravity 檔案

• .agents/skills/mcp-toolbox-postgres/SKILL.md：這項技能會引導 Antigravity 建立 MCP Toolbox 適用的 tools.yaml 設定。這項技能會說明建構適當 RAG 管道所需的 sources、tools 和 embeddingModels 設定。您必須新增適當的 YAML 前置事項，讓 Antigravity 辨識，這項技能才會啟用
• .agents/skills/repo-research/SKILL.md：這項技能會教導 Antigravity 如何逐步分析存放區，並產生結構化專案背景文件。這項工具採用 4 階段做法：表面掃描 (僅限目錄樹)、設定和中繼資料檔案、進入點和資料模型，然後是深入探討目標，每個階段都會停止並寫入發現項目，然後再繼續下一個階段。此外，您必須稍後新增 YAML 前言，才會啟用這項功能。啟用後，即可叫用這項功能來生成 .agents/rules/project-context.md，這份文件涵蓋架構、執行階段依附元件、API 介面和網域詞彙，可做為全面的入門指南。

規格導向開發：從 Antigravity 內建的規劃到結構化 SDD

AI 程式碼助理可根據提示輕鬆生成程式碼。風險：您用一句話描述功能，助理寫出數百行程式碼，您因為看起來沒問題而接受。這種做法有時稱為「直覺式程式開發」，也就是根據感覺來引導，並根據輸出內容是否符合需求來接受或拒絕。適合用於原型設計和拋棄式指令碼。當程式碼集變大、功能互動，或是您在幾週後重新查看程式碼，卻無法重構決策原因時，就會發生這種情況。

規格導向開發 (SDD) 可為這個迴圈新增結構。在生成任何程式碼前，請先撰寫規格：功能用途、服務對象、成功條件。AI 助理會根據規格運作，您在審查輸出內容時也是如此。規格會成為意圖的單一可靠資料來源。如果程式碼與規格不同，您可以在審查時發現。如果需求條件有異動，請先更新規格，然後重新產生。決策有據可查，而非臨時起意。

這項取捨是實際存在的：就每項功能而言，SDD 的速度比直覺式程式開發慢。您會先撰寫文件，再編寫程式碼。但這項投資會帶來複利效應：日後對程式碼集 的每次變更都有脈絡可循，每次 AI 生成的實作內容都有可供審查的合約，而且只要向協作者 (人類或 AI) 提供規格，即可讓他們加入專案，不必從記憶中回想並說明決策。

Antigravity 已經遵循規格導向開發原則。將代理程式設為規劃模式後，系統會先產生兩項構件，再編寫任何程式碼：

• 導入計畫：建議的技術方法、檔案變更和架構決策總覽
• 工作清單：工作項目的結構化細目

Antigravity 會要求您先審查並核准這些構件，再執行作業。這個「規劃然後實作」的迴圈是規格導向開發的核心：規格會引導程式碼，反之則否。

本程式碼研究室會以這個基礎為起點，進一步介紹以 spec-kit 為基礎的有主見版本控管工作流程。spec-kit 是 GitHub 提供的規格導向開發架構。每個功能都會經過審慎的管道，每個構件都是獨立的文件，您可以在 git 中查看、編輯及追蹤。管道包含兩個選用的品質閘階段 (釐清和分析)，可在問題造成實作問題前及早發現：

階段	構件	Purpose
/speckit.specify	spec.md	定義要建構的內容 (使用者導向，與技術無關)
/speckit.clarify (選填)	更新時間：spec.md	找出規格不足的區域、提出具體的問題釐清疑慮，然後將答案編碼回規格
/speckit.plan	plan.md、data-model.md、research.md	設計建構方式 (技術方法、資料模型、研究)
/speckit.tasks	tasks.md	將計畫分解為可執行的步驟
/speckit.analyze (選填)	分析報告	在實作前，先檢查工作是否有風險、缺口或遺漏的極端情況
/speckit.implement	程式碼變更	執行各項工作，並逐一勾選

每個構件都會以檔案形式保留在 specs/<feature-branch>/ 中，並在 Git 中進行版本控制，可重複使用。如果對話中斷，或是您想稍後再查看決策，規格文件隨時都能派上用場，不會埋沒在對話記錄中。

附註：Antigravity 內建構件在 UI 方面具有優勢，可讓使用者對生成的構件 ( 甚至是圖片！) 發表評論。)。因此在本教學課程中，我們會修改原始的 spec-kit 提示，以便與 implement 階段的內建構件整合

入門版存放區包含 .agents/workflows/ 中的這些 SDD 工作流程，以及 .specify/templates/ 中的範本。您稍後會使用這些值，為代理程式新增功能。

4. 使用 Antigravity 啟動專案環境

現在，讓我們模擬「更接近」日常工作的條件：

• 存放區管理不善
• README 檔案已過時
• 文件更新頻率不高

注意：如果這項資訊與你的情況不符，表示你非常幸運

在這種情況下，我們通常會先建立地圖或情境，說明要讓 Antigravity 處理的專案。這個步驟提供一個範例，說明如何建立技能，分析存放區並產生專案環境文件，讓 Antigravity 深入瞭解現有程式碼集。

此外，這項工具也會設定專案章程，也就是 SDD 工作流程驗證時所依據的原則，這些原則不得協商。這些資訊會提供 Antigravity 後續 SDD 週期所需的背景資訊和限制

Antigravity 情境階層

Antigravity 使用三種層級的環境，各有不同的範圍：

• 規則 (.agents/rules/)：一律啟用的指令。工作區中的每項對話都會顯示這些規則 ( 如果已啟用)。使用規則提供專案的整體脈絡，例如架構決策、編碼標準或技術堆疊資訊。
• 技能 (.agents/skills/)：隨選知識。只有在目前工作與技能的 description 欄位相符時，Antigravity 才會載入技能。使用技能取得特定領域的參考資源。
• 工作流程 (.agents/workflows/)：使用 / 指令觸發的已儲存提示。工作流程可用於重複執行的多步驟程序，例如 SDD 管道。

注意：專案目前有工作流程 (SDD 管道) 和 2 項技能 (repo-research 和 mcp-toolbox-postgres)，但沒有規則。稍後，我們將建立 project-context.md 規則，讓 Antigravity 持續瞭解程式碼集，包括使用的技術、檔案的整理方式，以及目前已建構的內容。

啟用技能

範例存放區的 .agents/skills/ 中包含兩項預先編寫的技能。這些檔案包含詳細說明，但開頭是 TODO(codelab) 註解，而非必要的 YAML 前置事項。如果沒有前言，Antigravity 就無法探索這些內容。

Antigravity 技能需要在檔案頂端提供 YAML 前言區塊，並包含兩個欄位：

• name - 技能的專屬 ID
• description：自然語言摘要，Antigravity 會比對這項摘要，決定要為特定要求載入哪個技能

在編輯器中開啟 .agents/skills/mcp-toolbox-postgres/SKILL.md。將頂端的 TODO(codelab) 註解行替換為下列前言：

---
name: mcp-toolbox-postgres
description: Configure MCP Toolbox for PostgreSQL — sources, tools, and embedding models
---

附註：MCP Toolbox Postgres 技能包含 sources、tools 和 embedding models 的正確設定

在編輯器中開啟 .agents/skills/repo-research/SKILL.md。將頂端的 TODO(codelab) 註解行替換為下列前言：

---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---

注意：請詳閱 repo-research SKILL.md。以下是分析存放區的提示詞範例，請注意，增量更新規則刻意採用保守做法。如果 Antigravity 在研究期間用盡情境，或對話中斷，目前為止發現的所有內容都會儲存到檔案中。重新叫用技能時，系統會從上次中斷的地方繼續，不會遺失進度。

警告！分析大型存放區可能會快速用盡配額！

確認兩個技能都有有效的前言：

head -4 .agents/skills/mcp-toolbox-postgres/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

每個欄位都應顯示以 --- 分隔符號括住的 name: 和 description: 欄位。如果缺少分隔符或欄位，Antigravity 就無法辨識技能。

這兩項技能都是視需求載入，Antigravity 會根據 description 欄位比對要求，並只在相關時提取完整指令。

安裝公開技能

ADK 快速參考指南技能

我們先前檢查了自行建立的技能 ( repo-research 和 mcp-toolbox-postgres 技能)。不過，還有許多其他技能有助於支援軟體開發，而且可以輕鬆安裝至程式碼代理程式。舉例來說，在本教學課程中，我們需要與 ADK 互動，因此必須瞭解如何使用 ADK 建構應用程式。請使用下列指令安裝 ADK 說明文件技能

npx skills add google/adk-docs

然後系統會提示您確認安裝，如下所示

按下 y 繼續下一個提示，選取要安裝的技能，如下所示。目前我們只使用 adk-cheatsheet (按空白鍵選取，然後按 Enter 鍵確認)

然後按一下 Enter 即可啟用預設安裝選項，並在目前專案中安裝技能

您會看到新的 ADK 技能已新增至 .agents/skills 目錄，也就是 adk-cheatsheet

原始人技能

其中一項有助於減少權杖用量的實用技能是原始人技能。這項技能可以從代理程式中剪下輸出權杖，因此當您像本教學課程一樣使用完整的規格導向開發時，這項技能會是不錯的組合

npx skills add JuliusBrussee/caveman

與先前類似，我們現在先選取 caveman 技能

然後按一下 Enter 即可啟用預設安裝選項，並在目前專案中安裝技能

現在我們應該已設定好 4 項技能，可以開始 SDD 歷程

.agents/skills/
├── adk-cheatsheet
├── caveman
├── mcp-toolbox-postgres
└── repo-research

生成專案背景資訊

確認規則目錄是否存在：

mkdir -p .agents/rules

在 Antigravity 的代理程式管理員/聊天方塊 (在編輯器模式中按下 ctrl + L)，發起新的對話。Type:

Research this repository and create a project context document, and communicate efficiently

Antigravity 會將您的要求與 repo-research 和 caveman 技能 ( 有效溝通的指令) 相符，然後開始有系統地分析程式碼集。這項工具會讀取設定檔、原始碼和說明文件，然後根據發現的內容填入專案環境範本。

完成後，在編輯器中開啟 .agents/rules/project-context.md。其中包含專案的具體資訊：技術堆疊 (Python 3.12、ADK、MCP Toolbox、Cloud SQL)、專案結構、資料模型 (含 pgvector 的 menu_items 表格) 和外部整合。

提示：專案情境文件會隨著專案進展而擴充。你可以重新執行技能，使用新加入的內容更新脈絡。增量更新規則可確保現有內容不會遭到覆寫，而是保留下來，並附加新技術、實體和整合項目。

如要進行特定更新，請使用特定提示：「研究資料庫結構定義並更新專案環境」或「使用新工具定義更新專案環境」。每次叫用都會在現有文件中新增內容。

設定專案章程

在規劃和分析期間，SDD 工作流程會參照 .specify/memory/constitution.md 的專案章程。/speckit.plan 工作流程會對其執行「憲法檢查」，並將違規事項標示為「重大」/speckit.analyze。如果憲章留空，並使用預留位置權杖，這些檢查就沒有可驗證的對象，因此計畫和分析會不受限制地執行。

憲章定義了不可協商的專案原則。這是由單一開發人員維護的小型存放區，因此章程應反映該範圍，保持簡單一致，避免過度設計。

在 Antigravity 的 Agent Manager 中，發起新對話。執行憲法工作流程：

/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.

Antigravity 會以具體原則填入憲法範本、指派版本 (1.0.0)，並對 SDD 範本執行一致性檢查。

在 .specify/memory/constitution.md 查看生成的章程。確認這三項原則是否明確列出。

注意：我們刻意將憲法限制在 3 項原則，適用於獨立開發人員。/speckit.constitution 工作流程支援增量修訂，只要使用其他原則再次運作執行，系統就會自動處理版本管理。如果是團隊專案，您會加入程式碼審查、測試紀律、觀測能力和 API 版本管理的原則。

檢查點： .agents/rules/project-context.md 存在，且包含存放區的具體資訊。.agents/skills/repo-research/SKILL.md 說明如何使用 YAML 前言、指令和衝突解決方式建立技能。.specify/memory/constitution.md 包含三項專案原則，計畫和分析工作流程會根據這些原則進行驗證。瞭解三層脈絡階層架構：規則 (一律啟用)、技能 (隨選) 和工作流程 (斜線指令)。

5. SDD 週期 - 新增預訂功能

這個步驟會逐步說明完整的 SDD 週期，將預訂訂位功能新增至餐廳服務專員。您會帶領 Antigravity 經歷每個階段 (指定、釐清、規劃、工作、分析、實作)，觀察每個構件如何以前一個構件為基礎。這是本程式碼研究室的核心學習體驗。

重要事項！Antigravity 是 AI 助理，因此生成的構件 (規格、計畫、工作、程式碼) 可能與本教學課程所述不同。檔案名稱、確切的 SQL 結構定義和程式碼結構可能有所不同。這是正常情況，也是 AI 輔助開發的一部分。SDD 工作流程可確保您在每個構件成為程式碼前都經過審查，因此請自行判斷是否接受、修改或重新生成任何不符合預期的輸出內容。

指定功能

在 Antigravity 的 Agent Manager 中，發起新對話。輸入 /speckit.specify 工作流程指令，並提供功能說明：

/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").

Antigravity 會建立功能分支、產生規格文件，並執行品質驗證。如果 Antigravity 提出需要釐清的問題，請根據上述功能說明回答。

注意：完成規格後，Antigravity 可能會提供「制定技術計畫」或「釐清規格需求」等交接事項。這些是下一個工作流程階段的提示 (/speckit.plan 或 /speckit.clarify)

這項規格的重點在於「內容」和「原因」，而非「方式」。這段文字說明瞭使用者體驗 (「訪客可以提供姓名、人數、日期和時間來預訂座位」)，但未提及 SQL 資料表、tools.yaml 或 ADK API。實作詳細資料會在規劃階段提供。

在 specs/<branch-name>/spec.md 查看生成的規格。確認是否擷取功能需求和成功條件。

釐清規格 (選填)

執行釐清工作流程，找出並解決規格中未明確指定的部分：

/speckit.clarify

Antigravity 會掃描規格，找出模糊不清、缺少驗收條件和規格不足之處。並提出具體的釐清問題，每個問題都可用簡短的選項或片語回答。您的答案會直接編碼回規格，因此在規劃開始前，規格會更加精確。

提示：釐清步驟為選用步驟，但建議用於複雜功能。如果規格很簡單，可以直接跳到規劃步驟。

規劃實作作業

執行規劃工作流程：

/speckit.plan Update the restaurant concierge agent to multi agent architecture which separate responsibilities for handling menu and reservations. Use your ADK and MCP toolbox skill to implement it properly

Antigravity 會透過兩個階段生成技術計畫：

1. 研究階段：解決現有程式碼集的不明問題，產生 research.md
2. 設計階段 - 建立 data-model.md (預訂實體定義) 並更新 project-context.md

Antigravity 應在規劃期間使用 adk-agent-development 技能。查看重要構件：

• specs/<branch-name>/plan.md - 技術方法：要修改哪些檔案、要遵循哪些模式
• specs/<branch-name>/data-model.md：預訂實體定義 (欄、類型、關係)
• specs/<branch-name>/research.md - 決策和理由

生成工作

執行工作流程

/speckit.tasks

Antigravity 會將計畫分解為 specs/<branch-name>/tasks.md 中的排序工作清單。工作會採用嚴格的核取清單格式，包含 ID、優先順序標記和檔案路徑，例如：

- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py
- [ ] [T002] [P] Add create_reservation tool to tools.yaml
- [ ] [T003] [P] Add list_reservations tool to tools.yaml
- [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py

工作會依階段分類：設定 → 基礎 → 使用者故事 → 潤飾。掃描工作清單，瞭解要建立和修改的項目。

分析工作 (選用)

執行分析工作流程，檢查工作是否有風險和缺口：

/speckit.analyze

Antigravity 會根據規格和計畫檢查工作清單，找出缺少的極端情況、可能衝突的工作，或規格需求與計畫工作之間的落差。請先解決重大問題，再進行實作。

提示：如果工作清單很長，或功能涉及多個子系統，分析步驟就非常實用。如果是預訂等特定功能，快速掃描就足夠。

6. 實作

執行導入工作流程：

/speckit.implement

Antigravity 會提供最終實作計畫和工作構件。請審查並核准，以繼續操作

提示：你可以直接留言！這項操作只能透過 Antigravity 內建的構件執行

Antigravity 會執行任務，並在完成後逐一勾選。完成後，系統會顯示完整的導覽

測試程式碼變更

導入完成後，請確認已進行重要變更。實際的檔案名稱和內容可能有所不同，但這些模式應會出現在 tools.yaml 和 agent.py 中：

# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml

輸出內容會類似這樣

...
get_reservations_by_name:
      Retrieve all reservations for a guest by their name. Uses case-insensitive
      SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
      FROM reservations
      ORDER BY reservation_datetime DESC
...

如果是 agent.py

# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py

# Check what files changed
git diff --name-only

您可能會發現類似的變更

...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
        book_reservation,
...

注意：如果 grep 未傳回任何檔案的相符項目，實作可能使用了不同的命名方式。檢查 git diff，查看完整變更內容，並確認是否已新增預訂相關邏輯。

這些變更應會影響種子資料庫指令碼。更新後的指令碼應會建立 reservations 資料表 (如果該資料表尚不存在)。您應該會看到輸出內容，確認已建立新資料表 (現有 menu_items 資料會保留)。

附註：Antigravity 可能會建立獨立的遷移指令碼 (例如 scripts/create_reservations.py)，而不是更新 seed_db.py。檢查 git diff --name-only 中是否有任何新指令碼，並改為執行這些指令碼。scripts/

如果到目前為止一切順利，我們可以在 ADK 代理程式開發人員 UI 中測試這項功能。讓我們進行資料庫遷移，納入新資料表，然後重新啟動工具箱，在 tools.yaml 中擷取新工具定義。停止所有現有的 Toolbox 程序，然後重新啟動：

lsof -ti:5000 | xargs kill -9 2>/dev/null; echo "Done"
./scripts/setup_database.sh > database_setup.log 2>&1 &

您可以在 database_setup.log 中查看輸出記錄，確認 Antigravity 是否產生正確的程式碼和設定。如果發生錯誤，請嘗試與代理程式互動來修正問題

如果一切順利，我們就可以啟動 ADK 開發人員使用者介面：

uv run adk web .

在瀏覽器中開啟 http://localhost:8000，並使用下列提示進行測試：

I'd like to book a table for 4 people on Friday at 7pm under the name Timmy

檢查：服務專員應確認預訂詳細資料並建立預訂

Do I have any upcoming reservations?

檢查：代理程式應會列出您剛建立的預訂

現在，請按兩次 Ctrl+C 停止 ADK 開發人員使用者介面。

查核點：代理程式會處理預訂和查詢作業。您已完成完整的 SDD 週期：指定 → 釐清 → 規劃 → 工作 → 分析 → 實作 → 測試。每個階段都會在 specs/<branch-name>/ 中產生版本化構件。

7. 挑戰 (選用)

您現在已瞭解完整的 SDD 工作流程。測試：

• 執行第二個 SDD 週期，為餐廳服務人員建構網路即時通訊介面，這次不提供逐步指引。
• 將代理程式部署至 Cloud Run，用於實際工作環境

提示

• 專案沒有前端架構。Antigravity 應建議使用原始 HTML/CSS/JS，如果建議使用 React 或類似項目，請引導它朝簡單的方向發展 (您的憲章「保持簡單」原則應會發現這一點)。
• ADK 伺服器會公開 /run_sse 以進行串流，並公開 /apps/{app_name}/users/{user_id}/sessions 以管理工作階段。Antigravity 會從專案環境中探索這些項目。
• 實作完成後，請使用 uv run uvicorn server:app --host 0.0.0.0 --port 8080 (而非 adk web) 啟動伺服器，確保靜態檔案掛接作業正常運作。
• 在 http://localhost:8080/static/index.html 進行測試。
• 參考程式碼實驗室已說明如何部署及保存 ADK 代理程式，請將 Antigravity 參照這個程式碼實驗室！

8. 恭喜！

您已透過 Antigravity 的 SDD 工作流程，擴充餐廳服務專員 ADK 代理程式的預訂功能，完全不必手動編寫應用程式程式碼。

您建構的內容

• 餐廳服務專員 ADK 代理程式，可提供菜單搜尋、語意搜尋、飲食偏好追蹤和預訂服務
• Antigravity 技能，可進行存放區研究，並產生及維護專案內容文件
• 專案章程，在規劃和分析期間強制執行不可協商的原則
• 完整的 SDD 週期，說明指定 → 釐清 → 規劃 → 工作 → 分析 → 實作工作流程

您學到的內容

• 瞭解如何在 Antigravity 中使用 Spec-Driven Development 工作流程，有系統地將功能新增至現有程式碼集
• 如何建立 Antigravity 技能，將網域知識打包，以便在對話中重複使用
• 如何啟動專案環境，讓 Antigravity 針對架構、模式和技術選擇做出明智決策
• 如何設定 SDD 工作流程驗證的專案章程
• 如何透過 MCP Toolbox，使用新的資料庫支援工具擴充 ADK 代理

清除所用資源

停止所有正在執行的本機程序 (Toolbox)：

pkill -f toolbox 2>/dev/null

刪除 Cloud SQL 執行個體，避免持續產生費用：

gcloud sql instances delete restaurant-db --quiet

(選用) 刪除整個專案：

gcloud projects delete $GOOGLE_CLOUD_PROJECT

重要事項：您可以使用這個指令 gcloud projects undelete ${GOOGLE_CLOUD_PROJECT}，在一段時間內復原這項刪除作業