Antigravity と Spec-kit を使用した仕様駆動の ADK エージェント開発

1. はじめに

既存のエージェントに機能（新しいデータベース ベースの機能）を追加するには、通常、ボイラープレートの作成、統合の接続、コードベースにすでに存在するパターンとの一貫性の維持が必要になります。Antigravity は、このプロセスのすべての段階を加速します。コードベースを分析して必要なコンテキストを構築し、レビュー用の構造化された仕様と実装計画を作成し、コード変更を実行します。これらはすべて、再利用可能なスキルとしてキャプチャするドメイン知識と、交渉不可能な原則を適用するプロジェクト憲章によってガイドされます。この Codelab では、spec-kit を参照する仕様ドキュメントを大幅に強化する新しいサイクルを導入することで、Antigravity 仕様駆動開発パラダイムを強化する方法を紹介します。

作成するアプリの概要

完全な SDD サイクルを通じて予約機能が追加された、ローカルで実行されるレストラン コンシェルジュ アプリケーション:

• 予約 - 新しい MCP Toolbox データベース ツールと Cloud SQL reservations テーブルを基盤として、ゲストがテーブルを予約し、予約を確認します。
• （チャレンジ）– エージェント用の独自の UI を開発する
• （チャレンジ）– Antigravity エージェントを使用して Google Cloud にデプロイする

スターター コードには、メニュー検索（キーワード + MCP Toolbox を介したセマンティック）と食事の好みトラッキング（ToolContext を介した）を備えた動作する ADK エージェントが用意されています。アプリケーション コードを手動で記述することなく拡張できます。Antigravity は、仕様に基づいて実装を処理します。

学習内容

• Antigravity が既存のコードベースを理解できるようにプロジェクト コンテキストをブートストラップする方法
• ドメイン知識（ADK Codelab パターン）を再利用する
• SDD ワークフローが計画と分析の際に検証するプロジェクト憲章を設定する方法
• Antigravity で仕様駆動開発（SDD）ワークフローを使用して機能を体系的に追加する方法
• MCP ツールボックスを使用して新しいデータベース バックエンド ツールで ADK エージェントを拡張する方法

前提条件

• ローカルマシンに Google Antigravity と git がインストールされている
• トライアルの課金アカウントが有効になっている Google Cloud アカウント
• ユースケースのコンテキストを理解するには、前提条件となる 4 つの ADK Codelab（または同等の知識）を事前に修了しておくことをおすすめします。
• ADK を使用した AI エージェントの構築: 基礎
• ADK を使用して AI エージェントを構築する: ツールによる強化
• ADK と CloudSQL を使用して永続的な AI エージェントを構築する
• Cloud Run で ADK エージェントをデプロイ、管理、モニタリングする
• ツールとしてのデータベース: ADK、MCP ツールボックス、Cloud SQL を使用したエージェント RAG

2. 環境をセットアップする

注意事項:

このチュートリアルには、有効な請求先アカウントを持つ Google Cloud プロジェクトが必要です。まだお持ちでない場合は、次の手順に沿って、このチュートリアルで使用できるトライアル請求先アカウントを取得してください。

1. シークレット ウィンドウを開く
2. ワークショップ セッションに参加する場合は、通常、セッションで利用コードの利用ポータルの URL が提供されます。それ以外の場合は、トライアルの請求先アカウントの利用ポータルに移動してください。
3. 個人の Gmail アカウントを使用してログインします。（Google Workspace や他のメールアドレスは使用できません）。
4. 利用手順に沿って操作します。

この手順では、スターター リポジトリのクローンを作成し、Google Cloud で認証を行い、Cloud SQL データベースをプロビジョニングして、ローカルの Antigravity 環境を準備します。

注: この Codelab は、ローカルマシンの 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 ブランチを作成します。リモートを削除すると、スターター リポジトリへの誤った push を防ぐことができます。

git remote remove origin

重要: この Codelab の SDD ワークフローでは、git ブランチを使用して機能仕様を整理します。origin リモートを削除すると、ローカル ブランチとコミットがローカルに保持されます。作業をバックアップする場合は、独自のリモートを追加します。git remote add origin <your-repo-url>

前提条件をインストールする

前提条件スクリプトを実行します。git、curl、gcloud、uv、Python 3.12、MCP Toolbox を確認し（不足している場合はインストールします）。

bash scripts/setup_prerequisites.sh

注: すべての前提条件をダウンロードするには時間がかかります。ダウンロードが完了するまで、新しいタブを開いて次のセクションに進んでください。

Google Cloud での認証

2 つの認証コマンドを実行します。どちらも OAuth のブラウザを開きます。

gcloud auth login
gcloud auth application-default login

注: 2 回目の 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 の有効化にはしばらく時間がかかることがあります。この操作が必要なのはプロジェクトごとに 1 回だけです。

Cloud SQL をプロビジョニングする

データベース パスワードを設定して、.env に追加します。

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

重要: 上記のハードコードされたパスワードは、チュートリアルでの使用のみを目的としています。本番環境では、Secret Manager などのサービスを使用して認証情報を安全に保存し、実行時に参照します。平文のシークレットをソース管理に commit しないでください。

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

Python プロジェクト マネージャーとして uv を使用します。uv は、Rust で記述された高速な Python パッケージおよびプロジェクト管理ツールです（ドキュメント）。この Codelab では、高速性と簡便性を実現するためにこれを使用します。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 - コア エージェント。MCP ツールボックスのデータベース ツールと ToolContext ベースの食事の好みトラッキングを組み合わせた LlmAgent。エージェントは、ツールボックス サーバーからすべてのツールを読み込み、ToolContext を使用して状態を管理する 2 つの Python 関数（save_dietary_preference、get_dietary_preferences）を追加します。
• tools.yaml - MCP ツールボックスのツール定義。3 つのメニュー検索ツール（キーワード検索（search_menu）、pgvector を介したセマンティック検索（semantic_search_menu）、カテゴリ フィルタ（get_menu_by_category））が定義されています。予約ツールはまだ存在しません。これらは後で追加します。
• server.py - ADK に FastAPI オブジェクトとしてアクセスする方法を示す最小限の FastAPI サーバー。ADK の get_fast_api_app() は、SSE ストリーミングとセッション管理 API の /run_sse などの組み込みエンドポイントを提供します。

Antigravity ファイル

• .agents/skills/adk-agent-development/SKILL.md - 4 つの ADK Codelab すべての参照パターンを凝縮した、事前構成済みのスキル（Antigravity によって生成）。現在非アクティブ（YAML フロントマターがない）です。後で更新する必要があります。Antigravity は、ADK エージェントの機能とその例に関連する作業を検出すると、このスキルを自動的に読み込みます。これは、Antigravity が後で予約機能を計画する際にガイドとなる知識です。
• .agents/skills/repo-research/SKILL.md - リポジトリを段階的に分析し、構造化されたプロジェクト コンテキスト ドキュメントを生成する方法を Antigravity に教えるスキル。4 フェーズのアプローチを使用します。サーフェス スキャン（ディレクトリ ツリーのみ）、構成ファイルとメタデータ ファイル、エントリ ポイントとデータモデル、ターゲットを絞った詳細分析です。各フェーズは、次のフェーズに進む前に停止して結果を書き込みます。ADK スキルと同様に、後で YAML フロントマターを追加するまで無効になっています。有効にしたら、呼び出して .agents/rules/project-context.md を生成します。これは、アーキテクチャ、ランタイム依存関係、API サーフェス、ドメイン用語集を網羅した包括的なオンボーディング ドキュメントです。

仕様駆動開発: Antigravity の組み込みプランニングから構造化された SDD まで

AI コーディング アシスタントを使用すると、プロンプトからコードを簡単に生成できます。リスク: 1 つの文で機能を説明すると、アシスタントが何百行ものコードを生成し、それが正しいように見えるため、受け入れてしまう。これは「バイブ コーディング」と呼ばれることもあります。つまり、うまくいくかどうかを感覚的に判断して、出力を受け入れたり拒否したりします。プロトタイプや使い捨てスクリプトには高速です。コードベースが大きくなった場合、機能が相互作用する場合、数週間後にコードを再確認したときに決定の理由を再構築できない場合は、この原則が破られます。

仕様駆動開発（SDD）は、このループに構造を追加します。コードを生成する前に、仕様（機能の内容、対象ユーザー、成功基準）を記述します。AI アシスタントはこの仕様に基づいて動作します。出力結果を確認する際も、この仕様に基づいて確認します。仕様はインテントの信頼できる唯一の情報源になります。コードが仕様から逸脱している場合は、レビューで検出します。要件が変更された場合は、まず仕様を更新してから再生成します。決定は文書化され、即興で行われることはありません。

トレードオフは実際に存在します。SDD は、機能あたりの速度がバイブレーション コーディングよりも遅くなります。コードを記述する前にドキュメントを作成します。しかし、その効果は複合的に現れます。コードベースの将来の変更にはすべてコンテキストがあり、AI によって生成された実装にはすべてレビュー可能なコントラクトがあり、共同作業者（人間または AI）をオンボーディングする際に、記憶に基づいて決定を説明するのではなく、仕様を参照させることができます。

Antigravity はすでに仕様駆動開発の原則に従っています。エージェントをプランニング モードに設定すると、コードを記述する前に次の 2 つのアーティファクトが生成されます。

• 実装計画 - 提案された技術的アプローチ、ファイルの変更、アーキテクチャの決定の概要
• タスクリスト - 作業項目の構造化された内訳

Antigravity は、実行前にこれらのアーティファクトを確認して承認するよう求めます。この計画と実装のループが仕様駆動開発の中核です。仕様がコードをガイドし、その逆ではありません。

この Codelab では、spec-kit（GitHub の仕様主導開発フレームワーク）に基づく、意見主導のバージョン管理されたワークフローを使用して、その基盤をさらに発展させます。すべての機能は、各アーティファクトが git で確認、編集、追跡できるスタンドアロン ドキュメントである、慎重なパイプラインを通過します。パイプラインには、実装上の問題が発生する前に問題を検出する 2 つのオプションの品質ゲートフェーズ（明確化と分析）が含まれています。

フェーズ	アーティファクト	目的
/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 で優位性があり、ユーザーは生成されたアーティファクト（画像など）にコメントできます。）。したがって、このチュートリアルでは、implement フェーズで組み込みアーティファクトと統合するように元の spec-kit プロンプトを変更します。

スターター リポジトリには、これらの SDD ワークフローが .agents/workflows/ に、テンプレートが .specify/templates/ に含まれています。これらのビューは、後でエージェントに機能を追加するために使用します。

4. Cloud SQL の設定を完了し、ベース エージェントが機能していることを確認する

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 を直接呼び出します。3,072 次元のベクトルは menu_items の embedding 列に保存されます。アプリケーション側のエンベディング コードは必要ありません。

ベース エージェントをテストする

MCP ツールボックスをバックグラウンド プロセスとして起動します。

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 開発 UI を起動します。

uv run adk web .

ブラウザで Dev UI を開きます。次に、次のプロンプトでエージェントをテストします。

What appetizers do you have?

検査: エージェントがデータベースにクエリを送信し、メニュー項目を返します。

I'm vegetarian

検査: エージェントがエージェントの状態に食事の好みを保存します

Can I make a reservation for tomorrow?

確認: エージェントはこれに対応できません（予約ツールはまだ存在しません）。

Ctrl+C を 2 回押して ADK 開発 UI を停止します。ツールボックスをバックグラウンドで実行したままにします。後で再び使用します。

チェックポイント: ベース エージェントが動作する - メニュー検索（キーワード + セマンティック）と食事の好み機能が正しく動作する。予約ツールが存在しないため、予約リクエストが失敗します。プロジェクトの構造と、これから埋めるギャップを理解している。

5. Antigravity でプロジェクト コンテキストをブートストラップする

では、日常業務に近い条件でシミュレーションしてみましょう。

• 管理が不十分なリポジトリ
• README が廃止されました
• ドキュメントが頻繁に更新されない

注: このような状況に当てはまらない場合は、非常に幸運です。

このような状況で最初にすべきことは、通常、Antigravity に取り組んでほしいプロジェクトの地図やコンテキストを作成することです。このステップでは、リポジトリを分析してプロジェクト コンテキスト ドキュメントを生成するスキルを作成し、Antigravity に既存のコードベースを深く理解させる方法の一例を示します。

また、プロジェクトの構成（SDD ワークフローが検証する交渉不可の原則）も設定します。これらを組み合わせることで、Antigravity は後で SDD サイクルに必要なコンテキストと制約を取得します。

Antigravity コンテキスト階層

Antigravity は、それぞれスコープが異なる 3 つのレベルのコンテキストを使用します。

• ルール（.agents/rules/）: 常に有効な指示。このワークスペースのすべての会話で、このユーザーが確認されます（有効にした場合）。アーキテクチャの決定、コーディング標準、テクノロジー スタック情報など、プロジェクト全体のコンテキストにルールを使用します。
• スキル（.agents/skills/）: オンデマンドの知識。Antigravity は、現在のタスクがスキルの description フィールドと一致する場合にのみスキルを読み込みます。スキルを使用して、ドメイン固有の参考資料を取得します。
• Workflows（.agents/workflows/）: / コマンドでトリガーされる保存済みプロンプト。SDD パイプラインなどの繰り返し可能な複数ステップのプロセスには、ワークフローを使用します。

注: 現在、このプロジェクトにはワークフロー（SDD パイプライン）とスキル（ADK エージェント開発）がありますが、ルールはありません。project-context.md ルールにより、Antigravity はコードベースを永続的に理解できます。使用されているテクノロジー、ファイルの構成方法、これまでに構築されたものなどを把握できます。

スキルを有効にする

スターター リポジトリには、.agents/skills/ に 2 つの事前作成されたスキルが含まれています。詳細な手順が含まれていますが、必要な YAML フロントマターではなく TODO(codelab) コメントで始まっています。フロントマターがない場合、Antigravity はそれらを検出できません。

反重力スキルには、ファイルの先頭に 2 つのフィールドを含む YAML フロントマター ブロックが必要です。

• name - スキルの一意の識別子
• description - 特定のリクエストに対してどのスキルを読み込むかを決定する際に、Antigravity が照合する自然言語の概要

開く

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

エディタで。先頭にある 2 つの 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 エージェント開発スキルには、5 つの ADK Codelab（エージェント構造、ツールタイプ、状態管理、デプロイ）から抽出されたパターンと例が含まれています。

開く

.agents/skills/repo-research/SKILL.md

エディタで。先頭にある 2 つの 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 のエージェント マネージャー/チャット ボックス（エディタモードで ctrl + L を押します）で、新しい会話を開始します。タイプ:

Research this repository and create a project context document

Antigravity はリクエストを repo-research スキルと照合し、コードベースの体系的な分析を開始します。構成ファイル、ソースコード、ドキュメントを読み取り、その結果をプロジェクト コンテキスト テンプレートに入力します。

完了したら、エディタで .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 は違反を重大として報告します。憲法がプレースホルダ トークンを含む空白のテンプレートのままの場合、これらのチェックは検証対象がないため、計画と分析はガードレールなしで実行されます。

憲章では、交渉不可能なプロジェクトの原則を定義します。これは 1 人のデベロッパーが管理する小さなリポジトリであるため、憲章はその範囲を反映したものにする必要があります。シンプルで一貫性があり、オーバー エンジニアリングを避けるようにしてください。

Antigravity のエージェント マネージャーで、新しい会話を開始します。構成ワークフローを実行します。

/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 つの原則が明記されていることを確認します。

注: 憲法は、ソロ デベロッパーを対象とした 3 つの原則に限定されています。/speckit.constitution ワークフローは増分修正をサポートしています。追加の原則を使用して再度実行すると、バージョン管理が自動的に処理されます。チーム プロジェクトの場合は、コードレビュー、テストの規律、オブザーバビリティ、API バージョニングの原則を追加します。

チェックポイント: .agents/rules/project-context.md が存在し、リポジトリに関する具体的な情報が含まれています。.agents/skills/repo-research/SKILL.md は、YAML フロントマター、手順、競合の解決によるスキルの作成を示しています。.specify/memory/constitution.md には、計画と分析のワークフローで検証される 3 つのプロジェクト原則が含まれています。3 レベルのコンテキスト階層（ルール（常にアクティブ）、スキル（オンデマンド）、ワークフロー（スラッシュ コマンド））を理解している。

6. SDD サイクル - 予約機能を追加

このステップでは、完全な SDD サイクルを説明し、レストラン コンシェルジュ エージェントに予約を追加します。各フェーズ（指定、明確化、計画、タスク、分析、実装）を Antigravity で進め、各アーティファクトが前のアーティファクトをどのように基盤としているかを確認します。これが、この Codelab の中心的な学習内容です。

重要: Antigravity は AI アシスタントです。生成されたアーティファクト（仕様、計画、タスク、コード）は、このチュートリアルで説明されているものと異なる場合があります。ファイル名、正確な SQL スキーマ、コード構造は異なる場合があります。これは想定どおりの動作であり、AI 支援開発の機能の一部です。SDD ワークフローでは、すべてのアーティファクトがコードになる前に確認されるため、期待どおりの出力が得られない場合は、判断に基づいて受け入れるか、変更するか、再生成します。

機能を指定する

Antigravity のエージェント マネージャーで、新しい会話を開始します。機能の説明を含む /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 は、次の 2 つのフェーズで技術計画を生成します。

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 は、別の移行スクリプト（seed_db.py を更新する代わりに scripts/create_reservations.py）を使用します。git diff --name-only で scripts/ の新しいスクリプトを確認し、代わりにそれらを実行します。

ここまでの手順がすべて正常に完了したら、ADK エージェントの Dev UI で機能をテストできます。Toolbox を再起動して、tools.yaml の新しいツール定義を読み込みます。既存の Toolbox プロセスを停止してから、新しいプロセスを開始します。

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

ADK 開発 UI を起動します。

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 を 2 回押して ADK 開発 UI を停止します。

チェックポイント: エージェントは予約の予約と検索を処理します。SDD のサイクル全体（指定 → 明確化 → 計画 → タスク → 分析 → 実装 → テスト）が完了しました。各フェーズで、specs/<branch-name>/ にバージョン管理されたアーティファクトが生成されました。

8. 課題（省略可）

これで、SDD のワークフロー全体を理解できました。テストしてみましょう。

• 2 回目の 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 でテストします。
• リファレンス Codelab では、ADK エージェントをデプロイして永続化する方法がすでに示されています。Antigravity にこのリファレンスを渡してください。

9. 完了

レストラン コンシェルジュ ADK エージェントを予約機能で拡張しました。これは、Antigravity の SDD ワークフローを介して完全に実現されており、アプリケーション コードを手動で記述する必要はありません。

構築した内容

• メニュー検索、セマンティック検索、食事の好みに関する情報の追跡、予約機能が搭載されたレストラン コンシェルジュ ADK エージェント
• プロジェクト コンテキスト ドキュメントを生成して維持する、リポジトリ調査用の Antigravity スキル
• 計画と分析の際に交渉不可能な原則を適用するプロジェクト憲章
• 指定 → 明確化 → 計画 → タスク → 分析 → 実装のワークフローを示す完全な SDD サイクル

学習した内容

• Antigravity で仕様駆動開発ワークフローを使用して既存のコードベースに体系的に機能を追加する方法
• 会話全体で再利用できるようにドメイン知識をパッケージ化する Antigravity スキルを作成する方法
• Antigravity がアーキテクチャ、パターン、テクノロジーの選択について十分な情報に基づいて意思決定を行えるように、プロジェクトのコンテキストをブートストラップする方法
• SDD ワークフローが検証するプロジェクト憲章を設定する方法
• MCP ツールボックスを使用して新しいデータベース バックエンド ツールで ADK エージェントを拡張する方法

クリーンアップ

実行中のローカル プロセス（ツールボックス）を停止します。

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} を使用して、一定期間元に戻すことができます。