Advanced Hands-on

Antigravity 発展ハンズオン(agy CLI 深掘り)

権限・サンドボックス・並列サブエージェント・スキル/プラグインで、エージェント運用を一段引き上げる

🤖 発展編
☁ Cloud Workstations + Antigravity CLI
🎯 中級〜上級
この発展ハンズオンについて
本ページは 基礎ハンズオン(Ch.0〜5)を完了した方向けの発展編です。基礎で作った同じ題材アプリ「お問い合わせ管理 API(Flask + SQLite)」をそのまま使い、agy CLI の上級機能を手を動かして体験します。各コマンド・パス・ショートカットの詳細は CLI リファレンス(日本語要約) も併せて参照してください。
「要確認」表記について 要確認
Antigravity CLI(agy)は新しいプロダクトで、コマンド名・フラグ・設定ファイルのパス・キーバインド・JSON のキー名などはバージョンによって変わる可能性があります。本ページの具体値は執筆時点の公式ドキュメントに基づきますが、変わりうる箇所には 要確認 を付けています。実施前に antigravity.google の最新ドキュメントをご確認ください。
共通の前提(作業ディレクトリ)
すべてのモジュールは、基礎ハンズオンと同じワークスペース gca-handson/antigravity/starter/(または完成版 completed/)を File → Open Folder で開き、統合ターミナルで agy を起動した状態を前提とします。グローバル設定は ~/.gemini/antigravity-cli/settings.json、ワークスペース設定は .agents/ 配下です。

発展モジュール一覧

Module 1

権限 & サンドボックスで安全運用

fine-grained permissions と Terminal Sandbox で、エージェントの「実行できる範囲」を設計する

このモジュールのねらい
エージェントが行うすべての操作は action(target) という権限リソースとして表現され、allow / deny / ask の 3 リストで評価されます。優先順位は Deny > Ask > Allow。さらに Terminal Sandbox(Linux は nsjail / macOS は sandbox-exec / Windows は AppContainer)でコマンド実行を OS レベルで隔離できます。安全に「攻めた自動化」を行うための土台です。
1-1. settings.json に権限ポリシーを書く 6分 要確認
グローバル設定ファイルを開きます。CLI から /open で外部エディタに開くか、IDE で直接開きます:
# パスは ~/.gemini/antigravity-cli/settings.json
agy
# プロンプトで:
/open ~/.gemini/antigravity-cli/settings.json
permissions ブロックを次のように設定します。deny に破壊的コマンド、allow に日常的に使う安全なコマンド、判断が要るものは ask に置きます:
// ~/.gemini/antigravity-cli/settings.json
{
  "permissions": {
    "allow": [
      "command(git)",
      "command(npm run (build|lint|test))",
      "read_url(google.com)"
    ],
    "deny": [
      "command(rm -rf)",
      "command(sudo)",
      "write_file(.git/)"
    ],
    "ask": ["command(*)"]
  }
}
優先順位は Deny > Ask > Allow
上の例では ask に command(*) があり allow に command(git) があります。Ask は Allow より優先されるため、allow に挙げていないコマンドはすべて確認が入ります(git は allow されているので素通り)。一方 deny の command(rm -rf) / command(sudo) は常にブロックされ、確認すら出ません。
マッチングの仕組み
command(...) はトークン単位の前方一致で、各トークンが ^(?:pattern)$ のアンカー付き正規表現として評価されます。例えば command(npm run (build|lint|test)) は npm run build / npm run lint / npm run test にマッチします。ファイル系(read_file / write_file)はワークスペース内が既定で auto-allow、ワークスペース外や URL(read_url / execute_url)は既定で Ask です。
1-2. Terminal Sandbox を有効化する 4分 要確認
同じ settings.json に、権限モードを proceed-in-sandbox に、サンドボックスを true にする設定を追記します:
// ~/.gemini/antigravity-cli/settings.json
{
  "toolPermission": "proceed-in-sandbox",
  "enableTerminalSandbox": true
}
設定を保存し、agy を起動し直します(Cloud Workstation の Linux 環境では nsjail で隔離されます)。
3 つの権限モード
  • request-review(既定): すべての書き込み・コマンド・リモート通信の前に確認。
  • proceed-in-sandbox: すべてのコマンドをサンドボックス内で実行。安全なものは自動実行、危険なものは確認。
  • strict: 読み取り以外のすべてで確認(行単位の完全な透明性)。
要確認 モード名は /permissions パネルの表記(always-proceed など)と差異がある場合があります。実際の選択肢は /permissions で確認してください。
1-3. わざと危険な指示を出してブロック/確認/隔離を体験する 5分
deny を体験: deny に入れたコマンドをエージェントに依頼し、即座にブロックされることを確認します(実害はありません):
CLI に入力するプロンプト
作業ディレクトリ内の一時ファイルを掃除したいので rm -rf ./tmp を実行してください。
command(rm -rf) が deny にあるため、エージェントは実行できず、別の安全な方法(個別 git clean の提案など)に切り替えるはずです。
ask を体験: allow に挙げていないコマンドを依頼し、確認カードが出ることを見ます:
CLI に入力するプロンプト
requirements.txt の中身を pip で再インストールしてください。
sandbox の隔離を体験: サンドボックス有効時、コマンド確認のプロンプトに「サンドボックスなしで実行」する選択肢が出ます。表示を観察してください:
# サンドボックス有効時のプロンプト例
Do you want to proceed?
1. Yes
2. Yes, and run without sandbox restrictions
3. No
YOLO モードは使わないでください
すべてを自動承認するモード(いわゆる「権限スキップ」)は、発展ハンズオンでも使わないでください。「deny で守り、ask で確認し、allow で素早く」という設計こそがこのモジュールの学びです。
特定コマンドだけサンドボックス外に出す
サンドボックスを有効にしつつ、信頼できる特定コマンドだけ隔離外で動かしたい場合は unsandboxed(prefix) を allow に追加します(例: unsandboxed(git push))。これはサンドボックス有効時のみ意味を持ちます。
Module 2

-p ワンショットで CI / Git フック自動化

非対話の -p フラグで、エージェントをシェルパイプラインや Git フックに組み込む

このモジュールのねらい
agy -p "..." は対話 TUI を開かずに1 回だけプロンプトを実行して結果を標準出力に返します。Git フック・CI・スクリプトに組み込むことで、「コミットメッセージ草案」「差分レビュー」「リリースノート生成」などを自動化できます。
2-1. ワンショットで差分からコミットメッセージを作る 4分
基礎ハンズオンで app.py に何か変更を加えた状態(または小さな変更を git add した状態)で、ターミナルから直接実行します:
# 公式ドキュメント記載の例(そのまま使えます)
agy -p "Review this git diff and draft a conventional commit message" --cwd $(pwd)
エージェントが差分を読み、Conventional Commits 形式(feat: / fix: など)のメッセージ案を標準出力に返します。気に入ったら手動でコミットに使います。
--cwd が効くポイント
--cwd $(pwd) でワークスペースのルートを明示すると、エージェントは AGENTS.md や対象ファイルを正しく解決できます。フックやスクリプトから呼ぶときは、カレントディレクトリが意図と違うことがあるため常に明示するのが安全です。
2-2. prepare-commit-msg フックに組み込む 6分 要確認
Git の prepare-commit-msg フックを作り、コミット時にメッセージ草案を自動生成します。.git/hooks/prepare-commit-msg を作成します:
#!/usr/bin/env bash
# .git/hooks/prepare-commit-msg
# ステージ済み差分から Conventional Commit のメッセージ案を生成し、
# コミットメッセージファイルの先頭に挿入する
COMMIT_MSG_FILE=$1

# ステージ済みの差分がある場合のみ実行
if git diff --cached --quiet; then
  exit 0
fi

DRAFT=$(agy -p "Review the staged git diff and output only a single-line conventional commit message" --cwd $(pwd))

# 既存メッセージの前に草案を差し込む
printf '%s\n\n%s\n' "$DRAFT" "$(cat $COMMIT_MSG_FILE)" > $COMMIT_MSG_FILE
実行権限を付与します:
chmod +x .git/hooks/prepare-commit-msg
何か変更して git add し、git commit を実行します。エディタが開くと、先頭に草案メッセージが入っているはずです。
フックでの権限・ネットワークに注意 要確認
フック内の agy -p は対話できないため、確認待ち(ask)で止まると失敗します。フックで使うなら、必要な操作(差分読み取り程度)が allow 済みであることを確認してください。また実運用ではレイテンシも考慮し、巨大な差分ではタイムアウト対策を入れると安心です。
2-3. リリースノートを自動生成する 4分
直近のタグからの変更履歴を -p に渡し、リリースノートの下書きを作ります。パイプで履歴を渡すこともできます:
# 直近タグからのコミットを基にリリースノートを生成
git log $(git describe --tags --abbrev=0)..HEAD --oneline \
  | agy -p "Summarize these commits into Markdown release notes grouped by Added / Changed / Fixed" --cwd $(pwd) \
  > RELEASE_NOTES.md
生成された RELEASE_NOTES.md を確認し、必要に応じて手直しします。CI の「タグ push 時」ステップに組み込めば、リリースノート草案を自動で添付できます。
CI への組み込み
agy -p は終了コードと標準出力を返すので、GitHub Actions / Cloud Build の 1 ステップとして扱えます。レビュー結果を PR コメントに投稿したり、生成物をアーティファクトとして保存したりと、既存のパイプラインに自然に挿し込めます。要確認(CI 環境での認証方法は公式ドキュメントで確認)
Module 3

並列サブエージェントで一括改善

主エージェントにサブエージェントを fan-out させ、複数の改善を並行して進める

このモジュールのねらい
Antigravity CLI は非同期マルチスレッドで動き、主エージェントが重い作業をサブエージェントやバックグラウンドタスクに委譲します。あなたは主画面で作業を続けながら、/agents パネルで進捗を監視し、承認が必要な箇所だけ素早くさばけます。
3-1. 複数の改善を並列に依頼する 6分
基礎ハンズオンで完成した app.py(対応履歴機能つき)に対し、独立した複数タスクを並列で進めるよう主エージェントに依頼します:
CLI に入力するプロンプト
次の3つを、独立したサブエージェントで並行して進めてください。
1. app.py の全関数に Google Style の docstring を付与する
2. /tickets と /tickets/<id>/responses のエンドポイントに対する pytest のテストを追加する
3. 変数名の揺れ(例: ticket_id と tid の混在)を snake_case に統一する
それぞれ完了したら検証し、結果を報告してください。
主エージェントがタスクを分解し、サブエージェントを起動します。各サブエージェントには「Codebase Researcher」のような役割が割り当てられます。
なぜ並列が効くのか
docstring 付与・テスト追加・命名統一は互いに独立しているため、直列で待つ必要がありません。長い処理を待つ間も、あなたは主スレッドで別のプロンプトを打てます。
3-2. /agents と /tasks で監視する 5分
プロンプトに /agents と入力して Agent Manager パネルを開きます。実行中・完了・失敗の各サブエージェントが、ID・役割・状態・現在のステップ付きで一覧表示されます:
CLI に入力
/agents
↑/↓ で対象サブエージェントを選び Enter で Subagent Detail View に入ると、内部の思考ログ・ツール呼び出し・実行出力まで読めます。Esc で一覧に戻ります。
シェルコマンドやテスト実行などの非エージェント的なバックグラウンド処理は /tasks で監視します。stdout ログの確認や、暴走プロセスの安全な停止ができます:
CLI に入力
/tasks
3-3. 承認(ctrl+k)と承認待ちの移動 4分 要確認
サブエージェントが承認の必要な操作(ファイル書き込み・テスト実行など)に到達すると、プロンプト直上に Fast Path Alert(例: Subagent 12 asks to run "pytest")が表示されます。
その場で承認: パネルを切り替えずに ctrl+k を押すと、保留中のアクションを即座に承認できます。
承認待ちの間を移動: 公式 CHANGELOG のキーバインド一覧には ctrl+k のほか alt+j があります(承認待ちのサブエージェント間の移動に使えるとされますが、alt+j の正確な機能は公式に明記されていません — 要確認)。確認/却下したら Esc で元のスレッドに戻ります。なお ctrl+j は公式のキーバインド一覧には含まれていません。
キーバインドは要確認 要確認
公式 CHANGELOG(v1.0.2)のショートカット一覧は ctrl+r / ctrl+o / alt+j / ctrl+k で、承認は ctrl+k が確定です。ctrl+j はこの一覧に含まれず(「テレポート」の説明は AI 要約由来の誤りの可能性)、alt+j の正確な機能も公式には未記載です。実際の割り当ては /keybindings または /help のショートカットタブで確認してください。
監視 → 承認のリズムを作る
並列実行の価値は「待たないこと」です。/agents で全体像を掴み、Fast Path Alert が出たら ctrl+k で即承認、深く見たいときだけ Detail View で内容を確認、というリズムを身につけると、複数改善を一気に回せます。
Module 4

スキル / プラグインでチーム規約を配布

スキルを / コマンド化し、プラグインとして skills/agents/rules/MCP/hooks を一括配布する

このモジュールのねらい
スキルは frontmatter 付きの Markdown で、登録すると自動的に /<name> スラッシュコマンドになります。プラグインは skills / agents / rules / MCP 定義 / hooks を 1 つの配布可能なバンドルにまとめた仕組みです。チームの規約や定型作業を「インストールするだけ」で全員に配れます。
4-1. code-review スキルを作って /code-review で実行 6分
ワークスペースルート(antigravity/starter/)に .agents/skills/ ディレクトリを作り、code-review.md を作成します:
mkdir -p .agents/skills
.agents/skills/code-review.md に frontmatter(name / description)と指示を書きます。name がそのまま / コマンド名になります:
# .agents/skills/code-review.md
---
name: code-review
description: お問い合わせ管理 API のコードを規約とセキュリティ観点でレビューする
---

あなたはこのリポジトリのレビュアーです。AGENTS.md の規約に従い、
変更(または指定ファイル)を次の観点でレビューしてください:

1. SQL: f-string や % 演算子で SQL を組み立てていないか(必ずパラメータ化クエリ)
2. バリデーション: 文字列フィールドの最大長・許可リスト検証があるか
3. エラーハンドリング: {"error": "..."} 形式と適切な HTTP ステータスか
4. docstring: 全関数に Google Style の docstring があるか

指摘は「ファイル:行 / 重大度 / 修正案」の形式で簡潔に出力してください。
このディレクトリで agy を起動するとスキルがコンパイルされ、/code-review が使えるようになります。/skills で登録状況を確認できます:
CLI に入力
/code-review
ワークスペース or グローバル
.agents/skills/ に置いたスキルはリポジトリと一緒に git 管理でき、チームで共有されます。全ワークスペースで使いたい個人用スキルは ~/.gemini/antigravity-cli/skills/ に置くと、どのディレクトリで agy を起動しても / コマンドとして読み込まれます。
4-2. プラグインの構造を理解する 4分
プラグインはインストールするとグローバル設定パスにステージされます。標準的なレイアウトは次のとおりです:
~/.gemini/antigravity-cli/plugins/<plugin_name>/ ├── plugin.json # 必須: パッケージのマーカーファイル ├── mcp_config.json # 任意: MCP サーバー定義 ├── hooks.json # 任意: pre/post ツールイベントフック ├── skills/ # 任意: スキル ├── agents/ # 任意: サブエージェント定義 └── rules/ # 任意: コードベースルール
先ほどの code-review.md を skills/ に入れ、rules/ に AGENTS.md 相当の規約を、hooks.json にフォーマッタ実行などを束ねれば、チーム規約一式を 1 つのプラグインとして配布できます。
スキル単体との違い
スキルは「1 つの / コマンド」を配るのに向きます。プラグインは skills / agents / rules / MCP / hooks をまとめて配るバンドルで、「このプロジェクトに参加したら、これを入れるだけ」というオンボーディングの単位になります。
4-3. plugin サブコマンドで管理する 5分
agy plugin(複数形 plugins も可)サブコマンドで、プラグインの一覧・インストール・有効化/無効化・アンインストールを行います:
# インストール済みプラグインの一覧
agy plugin list

# ローカル(またはリモート)パッケージをインストール
agy plugin install /path/to/local/plugin

# 一時的に無効化 / 再有効化(アセットは残る)
agy plugin disable <plugin_name>
agy plugin enable <plugin_name>

# 完全に削除(ディレクトリとレジストリを掃除)
agy plugin uninstall <plugin_name>
インストール後、/skills や /hooks、/mcp でプラグインが提供するコンポーネントがロードされているか確認します。
読み込みの優先順位 要確認
スキル・ルールは グローバル → プロジェクト(.agents/)の順で適用されます。同名の / コマンドがある場合の優先順位や、フックの実行順序はバージョンで変わりうるため、/skills / /hooks パネルで実際のロード状況を確認してください。
Module 5(任意)

MCP 連携

Model Context Protocol で、エージェントにローカル API や DB ツールを安全に接続する

このモジュールのねらい
MCP(Model Context Protocol)は、モデルがローカル API・ファイルパーサ・独自ツールに安全に接続するためのオープン標準です。Antigravity CLI はローカルプロセスとリモートホストの両方の MCP サーバーをサポートします。
5-1. ワークスペースに MCP サーバーを定義する 5分
ワークスペース固有の MCP 設定は .agents/mcp_config.json に置きます(グローバルは ~/.gemini/antigravity-cli/mcp_config.json)。題材アプリの SQLite を読む例:
// .agents/mcp_config.json
{
  "mcpServers": {
    "sqlite-explorer": {
      "command": "node",
      "args": ["/usr/local/bin/sqlite-mcp-server.js"],
      "env": {
        "SQLITE_DB_PATH": "/var/data/app.db"
      }
    }
  }
}
/mcp で MCP Manager Overlay を開き、サーバーの状態(active / disconnected / loading)を確認します。必要なら設定を再読み込みします:
CLI に入力
/mcp
リモート接続は serverUrl 必須
リモートの SSE / websocket ベースの MCP 接続を宣言する場合は、必ず serverUrl フィールドを定義してください。レガシーな url / httpUrl はサポートされません。
権限との連携
MCP ツールの実行も権限エンジンの対象です。mcp(server/tool) や mcp(*) を allow / deny / ask に書けます(例: mcp(sql/execute_mutation) を ask にして書き込み系だけ確認を入れる)。
Module 6(任意)

視覚デバッグ(ctrl+v)

スクリーンショットをプロンプトに貼り、UI 崩れをエージェントに診断・修正させる

このモジュールのねらい
UI の崩れ・レンダリングバグ・レイアウトの不整合は、文章で説明するより画像を見せる方が速いことがあります。スクリーンショットや録画をコピーし、プロンプトボックスで ctrl+v を押すと、エージェントがそのメディアを参照して原因を診断します。
6-1. チケット詳細画面の崩れを画像で直す 6分
ウェブプレビューで /tickets/1/view(対応履歴つきの詳細ページ)を開きます。意図的に CSS を 1 行壊すか、表示が崩れている箇所のスクリーンショットを撮ります。
画像をコピーした状態で、agy のプロンプトボックスにフォーカスし ctrl+v で添付します。続けて指示を書きます:
CLI に入力するプロンプト(画像添付つき)
添付のスクリーンショットのとおり、対応履歴の「内部メモ」バッジが本文に重なって表示が崩れています。@templates/ticket_detail.html のレイアウトを修正してください。
エージェントが画像を参照して原因(CSS の重なり等)を特定し、テンプレートの修正を提案します。承認してプレビューで再確認します。
@ ファイル参照と組み合わせる
画像(何が崩れているか)と @templates/ticket_detail.html(どこを直すか)を同時に渡すと、エージェントは探索範囲を絞り込めます。視覚情報とファイル参照の併用が、視覚デバッグの精度を上げるコツです。
Module 7(任意)

/fork で A/B 比較・/rewind で巻き戻し

セッションを分岐して実装案を比較し、行き詰まったら安全な地点へ戻す

このモジュールのねらい
実装方針に迷ったら、セッションを破棄せずに /fork で並行セッションに分岐して試せます。ビルドエラーが続くなど行き詰まったら /rewind(別名 /undo)で安定していた地点まで巻き戻せます。
7-1. /fork で実装 A/B を比較する 6分
安定した状態(例: 基礎ハンズオン完了直後)でベースラインのスレッドを作ります。そこから /fork で複製した並行セッションを立ち上げます:
CLI に入力
/fork
分岐先で案 Aを試します。例えばチケット検索の実装を変えてみます:
分岐セッションでのプロンプト(案 A)
/tickets/search を SQLite の LIKE ではなく FTS5 全文検索インデックスで実装し直してください。
うまくいかなければ /resume(別名 /switch)で安定したメインのスレッドへ戻り、案 B(例: 既存 LIKE のまま正規化を強化)を試します。両者の差分を見比べて採用案を決めます。
破棄せずに試せる安心感
/fork は「失敗しても元に戻れる」ため、思い切った実装を試しやすくなります。A/B どちらも実物のコードで比較できるのが、口頭の議論との大きな違いです。
7-2. /rewind で巻き戻す 4分
エージェントが連続して変更を加えた結果ビルドが壊れたとします。セッションを捨てずに、会話スレッドを直前の安定チェックポイントまで戻します:
CLI に入力
/rewind
巻き戻し後、壊れる前の状態から別のアプローチで再挑戦します。途中で方針がずれていると気づいたら、esc でその場でターンを中断するのも有効です。
発展ハンズオンのまとめ
権限/サンドボックスで安全を設計し(M1)、-p で自動化し(M2)、並列サブエージェントで一気に改善し(M3)、スキル/プラグインでチームに展開する(M4)。さらに MCP(M5)・視覚デバッグ(M6)・/fork・/rewind(M7)で表現の幅が広がります。基礎で身につけた「計画→承認→実行→検証」を、これらの上級機能でスケールさせてください。