Cloud Workstations + Antigravity CLI で、実装から Cloud Run デプロイまで
.agents/ のパス・モデル名などの具体値は変わる可能性があります。本ガイドでは確実な土台（Cloud Workstations のブラウザ IDE / ウェブプレビュー、エージェントの「計画→承認→実行→検証」、AGENTS.md、curl 検証、Cloud Run デプロイ）をベースに記述し、ツール固有の具体値には 要確認 を付けています。実施前に公式ドキュメント（antigravity.google / cloud.google.com）で最新手順をご確認ください。 なお、agy CLI のコマンド詳細は CLI リファレンス（日本語要約） にまとめています。
Cloud Workstation を起動し、Antigravity CLI を GEAP 認証してアプリを動かす 15分
? でいつでもコマンド一覧を表示できます。まず /config（=/settings）で verbosity を low にするとノイズが減ります。よく使うコマンドは附録 Bにまとめています。
https://80-<workstation>.<cluster>.cloudworkstations.dev の形式）。左にエクスプローラー、下に統合ターミナルがある、VSCode に近い画面です。agy）が未インストールの場合はインストールします（理想は管理者がカスタムイメージにプリイン済み — 附録 A）。公式インストーラ（antigravity.google 配信）が agy バイナリを ~/.local/bin に配置します（永続ディスク上なので次回以降も残ります）。agy は実行中にバックグラウンドで自動更新されます。# 公式インストーラ（macOS / Linux）
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy --version
# ログイン（初回はウィザードで「Google Cloud プロジェクトを使う」を選択） # プロジェクトをフラグで指定する形式： agy auth login --project YOUR_GEAP_PROJECT_ID # ロケーションはログイン時に選択（global / eu / us のいずれか） # プロジェクト / ロケーションの変更は /logout 後に再ログインして選び直す
agy auth login --help で確認 要確認agy auth login です（旧表記の agy login / agy config set project|location は公式ソースで確認できませんでした）。ロケーションは us-central1 のような細粒度リージョンではなく global / eu / us の 3 エンドポイントです。公式ドキュメント（antigravity.google）は JS レンダリングのため自動取得が難しく、正確なフラグは実機の agy auth login --help と /help で確認してください。
gcloud を認証します。gcloud はワークステーションに同梱されていますが、ユーザーとしてのログインは別途必要です。gcloud auth login --no-launch-browser # 表示された URL をブラウザで開き、コードを貼り付け gcloud config set project YOUR_PROJECT_ID
git clone https://github.com/nozoyoshida/gca-handson.git
gca-handson/antigravity/starter/ を開いてください。AGENTS.md はワークスペースのルートから読み込まれるため、サブフォルダ（antigravity/starter/）を開く必要があります。
# 統合ターミナルで（starter/ にいる状態） python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python app.py
http://localhost:5000 のリンクをクリックします。Code OSS が認証済みのプレビュー URL（https://5000-<ws>.<cluster>.cloudworkstations.dev）に自動変換して開きます。/tickets が JSON を返すことを確認してください。127.0.0.1 ではなく 0.0.0.0 で待ち受けているか確認してください（flask run --host 0.0.0.0 -p 5000 で起動し直すと確実です）。
Flask + SQLite で構築したシンプルなチケット管理 REST API です。
| Method | Path | 説明 |
|---|---|---|
GET | /tickets | チケット一覧取得（status, priority でフィルタ可） |
GET | /tickets/<id> | チケット詳細取得 |
POST | /tickets | チケット作成 |
PUT | /tickets/<id> | チケット更新 |
PATCH | /tickets/<id>/status | ステータス変更 |
GET | /tickets/search?q= | チケット検索 |
「計画 → 承認 → 実行 → 検証」のエージェントループを体験する 10分
git restore . で元に戻すか、計画段階で却下してください。Ch.2 以降で app.py を本格的に変更します。
@ パス補完 / ! ターミナル直実行 / esc esc 入力クリア / Esc 中断。セッションは /rewind(/undo) で巻き戻し・/fork で分岐・/resume で再開できます。
antigravity/starter/ のターミナルで CLI の対話 UI（TUI）を起動します。# 対話 TUI（ターミナル UI）を起動
agy
curl などで動作を確認します。確認できたら、変更を破棄して元に戻します：git restore .
# 追加された未追跡ファイルがあれば: git clean -fd
allow、破壊的な操作は ask にするのが基本です。すべてを自動承認する --dangerously-skip-permissions（いわゆる YOLO モード）は、ハンズオンでは使わないでください。
デスクトップ IDE 版はブラウザ拡張で画面操作を録画して検証しますが、CLI（ヘッドレス）では次の方法で検証します：
curl で API の挙動を確認（エージェントが自動で行うこともあります）git diff で変更を確認し、計画と突き合わせる習慣をつけましょう。
AGENTS.md（Rules）と Skill で、AI の出力品質を一貫してコントロールする 16分
AGENTS.md（Rules） がプロジェクトの規約を伝える中心的な仕組みで、エージェントが毎タスクで自動的に読み込みます。
AGENTS.md は空のままです。CLI に以下を依頼します：git restore .（未追跡ファイルは git clean -fd）で元に戻してください。Exercise 2-3 の Before/After 比較のため、app.py を綺麗な状態に保ちます。
現在のコードはたまたま snake_case で書かれていますがルールとして明文化されていません。エラーハンドリングは関数ごとにバラバラで、create_ticket() や search_tickets() には一切ありません。SQL は安全なパラメータ化クエリと危険な f-string が混在（get_tickets() のフィルタ、search_tickets()）。docstring は全関数で 0 個です。
AGENTS.md で規約を明示すると、AI の出力を一貫してコントロールできます。
AGENTS.md（空ファイルが用意されています）に、antigravity/templates/AGENTS.md の内容をコピーします：# お問い合わせ管理 API — エージェント向けルール（AGENTS.md） ## プロジェクト概要 Flask と SQLite を使用したチケット管理 REST API です。 ## コーディング規約 ### 命名規則 - 変数名・関数名: snake_case - 定数: UPPER_SNAKE_CASE ### ドキュメント - 全ての関数に Google Style の docstring を記述すること - API エンドポイントの docstring には HTTP メソッドとパスを含めること ### エラーハンドリング - エラー時は {"error": "説明"} の形式で適切な HTTP ステータスコードを返す - 400: バリデーションエラー、404: リソース未検出、500: サーバーエラー ### データベース - SQL クエリには必ずパラメータ化クエリ（? プレースホルダー）を使用 - f-string や % 演算子で SQL を組み立てることは禁止 ### バリデーション - 全てのユーザー入力に対してバリデーションを実施すること - 文字列フィールドには最大長制限を設けること ### セキュリティ - 秘密鍵やパスワードをハードコードしてはならない - 本番環境では debug モードを無効にすること
GEMINI.md に加えて AGENTS.md（クロスツール標準）も読み込みます。スコープはグローバル（~/.gemini/）→ プロジェクトルートの AGENTS.md → サブディレクトリ の順です。会社全体の規約をグローバルに、プロジェクト固有のルールをルートに置くことで、チーム全体で一貫した出力が得られます。注意: サブディレクトリの AGENTS.md は既定で無効で、Settings → Agent →「Load nested AGENTS.md files」で有効化します（有効時もルートを上書きせず補完）。競合時の優先順位は System Rules → GEMINI.md → AGENTS.md → ワークスペースの rules フォルダ、とされます（この優先順位は公式 JS ドキュメントで未確認のため要確認）。
git restore .（+ git clean -fd）で破棄します（Ch.3 をきれいな状態から始めるため）。AGENTS.md があるだけで出力品質が劇的に変わります。AGENTS.md は、プロジェクトに追加できる最もレバレッジの高いファイルです。
antigravity/templates/code-review.skill.md の内容を .agents/skills/code-review.md に置きます（先頭に frontmatter: name: code-review / description: ... を付ける）。登録すると /code-review として呼び出せます。.gemini/styleguide.md を使った GitHub PR 自動レビューでしたが、Antigravity では Skill（再利用可能な / コマンド）として、チームのレビュー基準をその場で実行できます。
| 仕組み | 用途 | 読み込みタイミング |
|---|---|---|
AGENTS.md（Rules） | プロジェクトの常時ルール（規約・背景） | 全タスクで自動 |
.agents/skills/（Skill） | 再利用する手順。frontmatter の name が / コマンド名になる（例 /code-review） | 起動時に登録 → / で実行 |
@ ファイル参照 | 特定ファイルをそのプロンプトの文脈に追加 | プロンプトで明示指定時 |
AGENTS.md を追加してみてください。10分の投資で、チーム全体の AI 出力品質が向上します。
複数ファイルにまたがる機能を、計画レビュー付きで一気に実装する 16分
completed/app.py を参照してください。
/agents・/tasks で進捗を監視できます。ベストプラクティスは「検証ループ」: テストや curl をエージェント自身に実行させ、結果を見て反復させましょう。
responses テーブルに is_internal カラムが含まれているかticket_id に外部キー制約が設定されているかticket_detail.html の更新が含まれているかAGENTS.md の規約に従っているか確認します：{"error": "..."} 形式かpython app.py
curl でテストします：# 対応履歴を追加 curl -X POST http://localhost:5000/tickets/1/responses \ -H "Content-Type: application/json" \ -d '{"responder": "鈴木", "message": "パスワードリセットのリンクを送信しました", "is_internal": false}' # 内部メモを追加 curl -X POST http://localhost:5000/tickets/1/responses \ -H "Content-Type: application/json" \ -d '{"responder": "山田", "message": "原因調査中。認証基盤側の障害の可能性あり", "is_internal": true}'
/tickets/1/view を開き、対応履歴セクションを確認します：脆弱性を検出し、修正し、ルールとして定着させる 13分
starter/app.py には教育目的の脆弱性が埋め込まれています。本番コードでは絶対に使用しないでください。
AGENTS.md にセキュリティ規約が含まれるため、Ch.3 のエージェントが一部の脆弱性を自動的に避けている可能性があります。残っている脆弱性に集中してください — これは Context Engineering が効いている証拠です。
| 脆弱性 | 場所 | 内容 |
|---|---|---|
| SQLi | search_tickets() | f-string で SQL を組み立て |
| SQLi | get_tickets() フィルタ | status を直接 SQL に埋め込み |
| Validation | update_status() | 任意の文字列をステータスとして受け付ける |
| Config | app.run() | debug=True でデバッガー露出 |
| Secrets | app.secret_key | 秘密鍵がハードコード |
search_tickets() が以下のように変わっているか確認します：sql = f"SELECT * FROM tickets
WHERE title LIKE '%{q}%'"
db.execute(sql)
sql = "SELECT * FROM tickets
WHERE title LIKE ?"
db.execute(sql, (f'%{q}%',))
antigravity/templates/AGENTS_security.md の「セキュリティ（最優先）」セクションを、AGENTS.md の先頭付近に追記します：## セキュリティ（最優先） ### SQL インジェクション防止 - f-string、% 演算子、.format() を SQL 文で絶対に使用しないこと - 必ずパラメータ化クエリ（? プレースホルダー）を使用すること ### 入力バリデーション - 全てのユーザー入力に対してバリデーションを実施すること - 文字列フィールドには最大長制限を設けること - HTML タグやスクリプトタグを除去またはエスケープすること - ステータス等の列挙値は許可リストで検証すること ### 設定 - 秘密鍵は環境変数から読み込むこと - 本番環境で debug=True を使用しないこと - エラーメッセージに内部情報（スタックトレース等）を含めないこと
/code-review で自動的にチェックされます。
| 機能 | 説明 |
|---|---|
| 権限モデル（allow/deny/ask） | コマンド・ファイル・URL を action(target) 単位で制御（詳細は下の設定例）。 |
| URL 許可リスト | エージェントがブラウザ操作する際の接続先を制限し、プロンプトインジェクションを防ぐ。要確認 |
| GEAP ガバナンス | Agent Identity / Registry / Gateway によりエージェントを集中管理・監査。 |
| Model Armor | LLM の入出力をリアルタイムにスクリーニング（プロンプトインジェクション検出・PII マスキング等）。 |
settings.json（~/.gemini/antigravity-cli/settings.json）の permissions（allow/deny/ask、優先順位 Deny > Ask > Allow）と enableTerminalSandbox（nsjail / sandbox-exec / AppContainer）で、エージェントの実行自体を制限できます（例 deny: command(rm -rf), command(sudo)）。
flowchart LR
A["User Input"] --> B
subgraph B["Model Armor - 入力"]
direction TB
B1["Prompt Injection 検出"]
B2["PII マスキング"]
B3["不正 URL ブロック"]
end
B --> C["Antigravity
(GEAP)"]
C --> D
subgraph D["Model Armor - 出力"]
direction TB
D1["有害コンテンツ検出"]
D2["機密データ除去"]
end
D --> E["Response"]
style A fill:#e8f0fe,stroke:#4285f4,color:#202124
style C fill:#e6f4ea,stroke:#34a853,color:#202124
style E fill:#e8f0fe,stroke:#4285f4,color:#202124
style B fill:#fce8e6,stroke:#ea4335,color:#202124
style D fill:#fce8e6,stroke:#ea4335,color:#202124
完成したアプリを本番化し、ワークステーションからサーバーレスで公開する 16分
gcloud が同梱され、Ch.0 で認証済みなので、そのままデプロイできます。
gcloud auth login 済み・プロジェクト設定済みであること、ユーザーに Cloud Run デプロイ権限（roles/run.admin 等）が付与されていること（附録 A）。
agy -p "..." --cwd $(pwd) でエージェントを非対話実行でき、git hook や CI などに組み込めます。
app.py は init_db() を if __name__ == '__main__' 内でのみ呼びます。Cloud Run では gunicorn がアプリを import して起動するため __main__ は実行されず、DB 未初期化で 500 エラーになりがちです。完成形は completed/ を参照してください。
gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
gcloud run deploy inquiry-system \ --source . \ --region asia-northeast1 \ --allow-unauthenticated
@google-cloud/cloud-run-mcp、またはマネージドのリモート MCP サーバー）の deploy-local-folder などのツールを呼び出してデプロイし、URL を読み戻します（実行時に許可を求められます）。このデプロイは Cloud Build API・Google Cloud クライアントライブラリ経由で行われ、gcloud run deploy をシェル実行するわけではありません（同等の手動コマンドは上の gcloud run deploy --source .）。要確認 公式 codelab では同フローを「Gemini CLI」で説明しているため、agy 固有の呼称・操作は実機でご確認ください。
Service URL: https://inquiry-system-xxxxx.run.app が表示されます。/tickets の JSON を確認します。4分
| Chapter | 学んだこと | 持ち帰りアクション |
|---|---|---|
| Ch.1 CLI の基本 | 計画→承認→実行→検証のループ | 日々のタスクをエージェントに任せてみる |
| Ch.2 Context Engineering | AGENTS.md で AI の出力品質を制御 | 明日、自分のプロジェクトに AGENTS.md を追加 |
| Ch.3 Agentic Coding | 複数ファイルの機能を計画レビュー付きで実装 | フィーチャーブランチで試し、計画をレビューする |
| Ch.4 セキュア開発 | 脆弱性検出 → 修正 → ルール化 | AGENTS.md / Skill にセキュリティルールを追加 |
| Ch.5 Cloud Run デプロイ | 本番化 → デプロイ → 公開 URL で確認 | 小さなサービスを gcloud run deploy --source . で公開 |
「エージェントが成功するか失敗するかを決める最大の要因は、モデルの性能ではなくコンテキストの質である」。AGENTS.md のような小さな追加が、精度と信頼性を大きく改善します。
Sources: Martin Fowler / Anthropic / Google Cloud
AI 生成コードは 1.7 倍の問題を含み、45% にセキュリティ欠陥があるという調査も。AI は開発者を「コードを書く人」から「設計し、レビューし、判断する人」に変えます。計画レビューの体験はその縮図です。
Sources: CodeRabbit 2025 / Qodo / GitHub Blog
脆弱性が悪用されるまでの期間は 2020 年の 700 日超から 2025 年にはわずか 5 日に短縮。AGENTS.md / Skill による自動チェック、Model Armor や GEAP のガバナンスは「あれば便利」ではなく必須の防御です。
Sources: Google Cloud / DeepStrike / Deep Instinct
agy の権限・サンドボックス・並列サブエージェント・-p 自動化などをさらに深掘りしたい方は 発展ハンズオン（agy の特徴を深掘り） へ。各コマンドの詳細は Antigravity CLI リファレンス にまとめています。
受講者がすぐ始められるよう、管理者が事前に行う準備 参考
aiplatform.googleapis.com を有効化（有効化には roles/serviceusage.serviceUsageAdmin が必要）。開発者には Agent Platform User（roles/aiplatform.user）を付与global / eu / us）を選択する# API 有効化 gcloud services enable workstations.googleapis.com compute.googleapis.com # クラスタ作成（リージョンに1つ。作成に ~20 分） gcloud workstations clusters create handson-cluster --region=asia-northeast1 # コンフィグ作成（マシンタイプ / イメージ / アイドルタイムアウト / カスタム SA） gcloud workstations configs create handson-config \ --cluster=handson-cluster --region=asia-northeast1 \ --machine-type=e2-standard-4 \ --idle-timeout=3600s # 各受講者のワークステーションを作成し、利用権限を付与 gcloud workstations create ws-user01 \ --cluster=handson-cluster --config=handson-config --region=asia-northeast1
agy や追加ツールを焼き込んだカスタムイメージを Artifact Registry に push してコンフィグで指定すると、受講者は Ch.0 の導入手順を省けます。/home は永続ディスクが実行時にマウントされビルド時の変更が上書きされるため、/home 依存の初期化は /etc/workstation-startup.d/ のスタートアップスクリプト（3 桁の数値プレフィックス >200 で実行順を制御、root 実行）で行います。
roles/workstations.user（自分で作成させる場合は roles/workstations.workstationCreator も）を付与受講者の Google アカウントに以下を付与しておくと、Ch.5 がスムーズです：
| ロール | 用途 |
|---|---|
roles/run.admin | Cloud Run サービスのデプロイ・更新 |
roles/iam.serviceAccountUser | Cloud Run 実行 SA として動作 |
roles/cloudbuild.builds.editor | ソースデプロイ時の Cloud Build 実行 |
roles/artifactregistry.writer | ビルド済みイメージの push |
よく使う操作のまとめ 参考 要確認
# インストール / バージョン確認（公式インストーラ） curl -fsSL https://antigravity.google/cli/install.sh | bash agy --version # 対話 TUI を起動（Google アカウントでサインイン。ログアウトは /logout） agy # 一発実行（CI / git hook 向け） agy -p "コミット前の差分をレビューして" # ── 確認済み（公式 CHANGELOG / README）────────────── # フラグ: -p（非対話実行） --model（モデル指定） # サブコマンド: agy models / agy changelog / agy plugin / agy update # スラッシュ: /settings /permissions /resume /diff /usage /quota # /credits /statusline /help /logout /changelog /add-dir # キーバインド: ctrl+r(Artifact Review) ctrl+k(承認) ctrl+o # ctrl+d(終了) ctrl+delete alt+j # ── 要確認（公式ソース未確認。Claude Code / Gemini CLI 由来の可能性）── # --cwd, /model /agents /tasks /skills /rewind /undo /fork /switch /clear, # プロンプト内 @ ! ? esc, ctrl+v(画像添付) は実機の /help で確認してください
| ファイル / 仕組み | 役割 |
|---|---|
AGENTS.md / GEMINI.md（ルート） | 起動時に自動読込される常時ルール（Rules） |
~/.gemini/antigravity-cli/settings.json | 設定・permissions（allow/deny/ask）・enableTerminalSandbox |
スキル / プラグイン~/.gemini/antigravity-cli/plugins/ | /skills で参照。skills / agents / rules / MCP / hooks を配布 |
権限アクション action(target) | command(...) / read_file(...) / mcp(...) 等を allow/deny/ask |
agy コマンドを実行できます。要確認