使用 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 中使用規格導向開發 (SDD) 工作流程，有系統地新增功能
• 如何透過 MCP Toolbox，使用新的資料庫支援工具擴充 ADK 代理

必要條件

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

2. 設定環境

重要注意事項：

本教學課程需要具備有效帳單帳戶的 Google Cloud 專案。如果沒有，請按照下列步驟取得可供本教學課程使用的試用帳單帳戶：

1. 開啟無痕視窗
2. 如要參加研討會，通常會在研討會中提供兌換入口網站網址，否則您可以前往這個試用帳單帳戶兌換入口網站
3. 使用個人 Gmail 帳戶登入( Google Workspace / 其他電子郵件無法登入！)
4. 按照兌換說明逐步操作

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

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

複製範例存放區

在 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>

安裝必備條件

執行先決條件指令碼。這個指令會檢查 git、curl、gcloud、uv、Python 3.12 和 MCP 工具箱，並在缺少時安裝：

bash scripts/setup_prerequisites.sh

注意：下載所有必要條件需要一段時間，請開啟新分頁，繼續下一節的內容，等待下載完成

使用 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 專案，並將專案 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：

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

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

佈建 Cloud SQL

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

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

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

建立 Cloud SQL 執行個體：

gcloud sql instances create restaurant-db \
  --database-version=POSTGRES_17 \
  --edition=ENTERPRISE \
  --region=${REGION} \
  --availability-type=ZONAL \
  --tier=db-custom-1-3840 \
  --root-password=${DB_PASSWORD} \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on &

db-custom-1-3840 層級是整合 Vertex AI ML 的最低要求。--enable-google-ml-integration 旗標可讓 Cloud SQL 直接從 SQL 呼叫 Gemini 嵌入模型，這項功能可支援語意搜尋功能。

注意：這個指令大約需要 5 分鐘，且會在背景執行。請讓這個終端機分頁保持執行狀態，並開啟新的終端機分頁，以進行後續步驟。

安裝依附元件

開啟新的終端機分頁。確認您仍在複製的存放區專案目錄中，然後重新載入環境變數：

source .env

我們將使用 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

現在，我們應該擁有所有必要的入門 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)
│   │   ├── adk-agent-development/
│   │   │   ├── SKILL.md     # ADK patterns
│   │   │   └── examples/
│   │   │       ├── basic_agent.py
│   │   │       ├── Dockerfile
│   │   │       ├── server.py
│   │   │       ├── stateful_agent.py
│   │   │       ├── toolbox_agent.py
│   │   │       ├── tools_agent.py
│   │   │       └── tools.yaml
│   │   └── repo-research/
│   │       └── SKILL.md     # Repo analysis 
│   └── 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型飲食偏好追蹤功能。代理程式會從工具箱伺服器載入所有工具，並新增兩個使用 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 Files

• .agents/skills/adk-agent-development/SKILL.md：預先設定的技能 ( 由 Antigravity 生成)，內含四個 ADK 程式碼研究室的濃縮參考模式。目前處於非使用中狀態 (缺少 YAML 前言) - 您稍後需要更新此狀態。Antigravity 偵測到與 ADK 代理程式功能及其範例相關的工作時，會自動載入這項技能。這項知識會在 Antigravity 稍後規劃預訂功能時提供指引
• .agents/skills/repo-research/SKILL.md：這項技能會教導 Antigravity 如何逐步分析存放區，並產生結構化專案背景文件。這項工具採用 4 階段做法：表面掃描 (僅限目錄樹)、設定和中繼資料檔案、進入點和資料模型，然後是深入探討目標，每個階段都會停止並寫入發現項目，然後再繼續下一個階段。與 ADK 技能一樣，您必須稍後新增 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. 完成 Cloud SQL 設定並確保 Base Agent 正常運作

切換回執行 Cloud SQL 建立指令的終端機分頁。完成後，請確認執行個體是否已準備就緒：

gcloud sql instances describe restaurant-db --format="value(state)"

如果輸出結果顯示 RUNNABLE，請繼續操作。如果顯示「PENDING_CREATE」，請稍候片刻，然後重新執行指令。

授予 Cloud SQL 服務帳戶 Vertex AI 存取權 (資料庫內嵌函式需要這項權限)：

SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

建立資料庫：

gcloud sql databases create restaurant_db --instance=restaurant-db

輸出內容應如下所示：

Creating Cloud SQL database...done.
Created database [restaurant_db].
instance: restaurant-db
name: restaurant_db
project: <your-project-id>

檢查點：您的 .env 檔案包含 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、REGION 和 DB_PASSWORD。Cloud SQL 執行個體「restaurant-db」正在執行中。toolbox 可在 PATH 中使用 (由 setup_prerequisites.sh 安裝)。Python 依附元件已安裝。

填充資料庫

載入環境變數，然後執行資料庫種子指令碼，建立結構定義並插入 16 個菜單項目：

source .env
uv run python scripts/seed_db.py

預期輸出內容：

Creating extensions...
Creating menu_items table...
Inserting 16 menu items...
Seeded 16 menu items.
Done.

產生向量嵌入，用於語意搜尋：

uv run python scripts/generate_embeddings.py

預期輸出內容：

Generating embeddings for 16 menu items...
Generated embeddings for 16 menu items.

這會使用 Cloud SQL 的內建 embedding() 函式 (透過 google_ml_integration 擴充功能)，直接從 SQL 呼叫 gemini-embedding-001。3072 維度的向量會儲存在 menu_items 的 embedding 欄中，不需要應用程式端的嵌入程式碼。

測試基礎代理

將 MCP Toolbox 啟動為背景程序：

set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

Toolbox 會透過 HTTP 提供資料庫工具。代理程式會在 http://127.0.0.1:5000 連線至該服務。

啟動 ADK 開發人員使用者介面：

uv run adk web .

在瀏覽器中開啟開發人員使用者介面。接著，使用下列提示測試代理：

What appetizers do you have?

檢查：代理程式查詢資料庫並傳回菜單項目

I'm vegetarian

檢查：代理程式會將飲食偏好儲存在代理程式狀態中

Can I make a reservation for tomorrow?

檢查：代理無法處理這項要求 (目前沒有預訂工具)

按兩次 Ctrl+C 即可停止 ADK 開發人員使用者介面。讓 Toolbox 在背景執行，稍後會再次使用

檢查點：基本代理程式可正常運作，選單搜尋 (關鍵字 + 語意) 和飲食偏好設定功能運作正常。由於沒有預訂工具，預訂要求會失敗。您瞭解專案結構，以及即將填補的缺口。

5. 使用 Antigravity 啟動專案環境

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

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

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

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

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

Antigravity 情境階層

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

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

注意：專案目前有工作流程 (SDD 管道) 和技能 (ADK 代理程式開發)，但沒有規則。project-context.md 規則可讓 Antigravity 持續瞭解程式碼基底，包括使用的技術、檔案的整理方式，以及目前已建構的內容。

啟用技能

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

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

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

開啟

.agents/skills/adk-agent-development/SKILL.md

在編輯器中。將頂端的兩行 TODO(codelab) 註解替換為這個前言：

---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---

注意：ADK 代理程式開發技能包含五個 ADK Codelab 的濃縮模式和範例，包括代理程式結構、工具類型、狀態管理、部署

開啟

.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/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md

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

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

生成專案背景資訊

確認規則目錄是否存在：

mkdir -p .agents/rules

在 Antigravity 的 Agent Manager/Chat box (在編輯器模式中按下 ctrl + L)，發起新的對話。Type:

Research this repository and create a project context document

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

完成後，在編輯器中開啟 .agents/rules/project-context.md。其中包含專案的具體資訊：技術堆疊 (Python 3.12、ADK、MCP 工具箱、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 包含三個專案原則，計畫和分析工作流程會根據這些原則進行驗證。瞭解三層脈絡階層架構：規則 (一律啟用)、技能 (隨選) 和工作流程 (斜線指令)。

6. 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

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

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

7. 實作

執行導入工作流程：

/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，查看完整變更內容，並確認是否已新增預訂相關邏輯。

變更應該會影響種子資料庫指令碼，讓我們嘗試執行該指令碼

source .env
uv run python scripts/seed_db.py

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

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

如果一切順利，我們可以在 ADK 代理程式開發人員 UI 中測試這項功能。重新啟動工具箱，即可在 tools.yaml 中取得新的工具定義。停止所有現有的 Toolbox 程序，然後重新啟動：

pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &

啟動 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>/ 中產生版本化構件。

8. 挑戰 (選填)

您現在已瞭解完整的 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 的相關內容！

9. 恭喜！

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

您建構的內容

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

您學到的內容

• 如何在 Antigravity 中使用規格導向開發工作流程，有系統地將功能新增至現有程式碼集
• 如何建立 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}，在一段時間內復原這項刪除作業