対象全レベル

達成目標失敗パターンの事前回避

前提知識Ch.1完了

所要時間10分

よくある落とし穴

Google Antigravity利用時に陥りやすい失敗パターンと具体的な対策。料金、レート制限、サンドボックスの注意点。

レート制限の罠

Google Antigravityの利用制限はリクエスト回数ではなく「Work Done（作業量）」で計算されます。そのため、曖昧な指示や巨大なタスクの丸投げはすぐに制限に到達します。

⚠️ 重要: Work Done ベースの計算

「1リクエスト = 1カウント」ではありません。エージェントが内部で行うファイル読み取り・ツール呼び出し・推論のすべてが「作業量」として計算されます。1つの曖昧な指示が内部で数十ステップに展開され、一気にクォータを消費することがあります。

プラン別リセットサイクル

プラン	リセット周期	優先アクセス	特徴
Free	週次リセット	なし（混雑時は待機）	月曜AM 0:00 UTC にリセット
Pro	5時間ごとリセット	あり	$20/月、継続的に利用可能
Ultra	5時間ごとリセット	最優先	$249.99/月、最大クォータ

クォータ枯渇を招くNG行動

✗

計画なしの即実装

Planを立てずにいきなり「このアプリを作って」と指示すると、エージェントが試行錯誤を繰り返し、Work Doneが爆増します。必ずPlanning Modeで計画を承認してから実装に入りましょう。

✗

無限ループの放置

エージェントがテスト失敗→修正→再テスト失敗のループに入った場合、自動的に停止しないことがあります。Agent Managerで常にステータスを監視し、3回以上同じエラーが続いたら手動介入してください。

✗

巨大なコンテキストの丸投げ

「このリポジトリ全体をリファクタリングして」のような指示はWork Doneが膨大になります。ファイル単位・機能単位に分割して指示しましょう。

モデル別のレート制限

Work Doneに加え、RPM（Requests Per Minute）のレート制限も存在します。

モデル	無料枠 RPM	Pro RPM	Ultra RPM
`gemini-2.5-pro`	5 RPM	60 RPM	1000 RPM
`gemini-2.5-flash`	15 RPM	120 RPM	2000 RPM
`gemini-2.0-flash`	15 RPM	120 RPM	2000 RPM

制限に達した時の挙動

レート制限に達すると、Antigravityは即座にエラーを返すのではなく、自動リトライを試みます。しかし、この挙動には問題があります。

サイレントスローダウン — エラーメッセージなくレスポンスが遅くなるため、制限に気づきにくい
バックオフの蓄積 — 連続してリトライすると指数関数的に待ち時間が増加し、1リクエストに数分かかることも
セッション内のクォータ消費 — 長時間セッションでは、初期のリクエストがクォータを食い潰し、後半で制限に到達する

⚠️ Warning

無料枠のgemini-2.5-proは5 RPMしかありません。エージェントが複数のツール呼び出しを連続して行う場合、1分間に5回の制限にすぐ到達します。並列エージェント実行時は特に注意してください。

対策

リクエスト間隔の設定
GEMINI.md に「ツール呼び出しの間に2秒以上の間隔を空けること」と明記し、エージェントの暴走を防ぎます。
モデルのフォールバック設定
Proモデルが制限に達した場合にFlashに自動切替するよう設定します。品質は多少下がりますが、作業を止めるよりはるかに効率的です。
使用量モニタリング
セッション中に定期的に /cost コマンドでトークン消費量を確認する習慣をつけましょう。

料金体系の注意点

Google Antigravityの料金体系は3段階ですが、各段階の境界でコスト効率が大きく変わります。意図しない課金パターンを事前に把握しておきましょう。

⚠️ クォータ削減の歴史（2025年12月〜2026年3月）

リリース以降、4ヶ月間で4回のクォータ削減が事前通知なしに実施されました: 2025年12月に無料枠が92%削減、2026年2月に画像クォータ制限、3月にクレジットシステム導入、Ultraユーザーもスロットリング対象に。今後もクォータ変更が予告なく行われる可能性があります。重要なプロジェクトでは余裕を持ったプラン選択を推奨します。

⚠️ サードパーティツール使用によるアカウントBAN

2026年2月、OpenClawなどのサードパーティツール経由でAntigravityのOAuthトークンを使用したユーザーが大量にアカウント停止されました。$250/月のUltra課金中でも停止対象となり、返金なしのケースも報告されています。Antigravityの認証情報を外部ツールに渡すことは利用規約違反となるため、公式IDE以外でのトークン利用は避けてください。

料金プランの比較

プラン	月額	主な制限	推奨用途
Free	$0	低RPM、1日のリクエスト上限あり	個人学習・検証
Pro	$20	中程度RPM、優先アクセス	個人開発・小規模プロジェクト
Ultra	$250	高RPM、最大コンテキスト	チーム・本番運用

意図しない課金パターン

コンテキストの肥大化 — 大きなファイルを繰り返し読み込むと、入力トークンが急増。1セッションで数万トークンを消費することがある
ループ実行の放置 — /loop コマンドで定期実行を設定し、停止を忘れるケース。バックグラウンドでクレジットが消費され続ける
Thinking tokens — gemini-2.5-proの「思考」トークンは出力トークンとしてカウントされるため、通常の3〜5倍のコストになることがある
画像・マルチモーダル入力 — スクリーンショットやPDFを頻繁に送信すると、テキストの数十倍のトークンを消費

✅ Tip

月初にクレジット残高のアラートを設定しましょう。Google Cloud Consoleの予算アラート機能を使えば、指定した金額に達した時点で通知を受け取れます。

サンドボックスの落とし穴

Google AntigravityのサンドボックスはOS別に異なるメカニズムを使用しており、挙動の差がバグの原因になることがあります。

OS別の挙動差

OS	サンドボックス技術	主な制限	注意点
macOS	Seatbelt (sandbox-exec)	ファイルシステムの書込制限	Homebrewパスが読めないことがある
Linux	nsjail	ネットワーク・プロセス分離	Docker内で動作しない場合がある
Windows	限定的なプロセス分離	完全なサンドボックスなし	セキュリティリスクが最も高い

よくある問題

npm installの失敗 — サンドボックス内でネイティブモジュールのビルドができず、node-gyp がエラーになる
ファイル権限エラー — サンドボックス外のディレクトリにアクセスしようとして Permission denied が発生
ネットワークアクセス制限 — 外部APIへのリクエストがブロックされ、テストが失敗
Docker-in-Docker問題 — CI環境のDockerコンテナ内でAntigravityのnsjailが動作しない

サンドボックス無効化（開発時のみ）

# 注意: セキュリティリスクを理解した上で使用すること
antigravity --disable-sandbox

⚠️ Warning

サンドボックスの無効化は開発環境でのみ行ってください。本番環境やCI/CDパイプラインでは、サンドボックスを有効にしたまま、必要なパスを明示的にホワイトリストに追加する方法を推奨します。

OS別サンドボックス機能比較

機能	macOS (Seatbelt)	Linux (nsjail)	Windows
ファイルシステム分離	✅ 完全	✅ 完全	⚠️ 限定的
ネットワーク分離	✅ ポート単位	✅ 名前空間	❌ 未対応
プロセス分離	⚠️ 部分的	✅ PID名前空間	❌ 未対応
GPU分離	❌	⚠️ cgroups	❌
セットアップ難易度	低（自動）	中（要設定）	N/A

⚠️ Warning

Windowsではサンドボックス機能が制限されています。Windowsユーザーは、承認ポリシーをRequest Reviewに設定し、破壊的コマンドをDenyリストに追加することで安全性を確保してください。WSL2環境であればLinux nsjailが利用可能です。

コンテキスト汚染

同一フォルダで複数のAntigravityエージェントを実行すると、「コンテキスト汚染」が発生し、予期しない動作の原因になります。

汚染が発生するパターン

同時編集の競合 — 2つのエージェントが同じファイルを同時に編集し、一方の変更が上書きされる
GEMINI.mdの相互干渉 — 異なるタスク用の指示が1つのGEMINI.mdに混在し、エージェントが混乱する
Git状態の不整合 — 一方のエージェントがコミットしている最中に、別のエージェントがファイルを変更
ロックファイルの競合 — package-lock.json や yarn.lock の同時更新による依存関係の破壊

対策

Worktreeの活用

Git Worktreeで作業ディレクトリを分離し、各エージェントが独立したファイルシステムで動作するようにします。git worktree add ../feature-branch feature-branch

タスク分割の明確化

ファイルの編集範囲が重複しないよう、エージェントごとに担当ディレクトリを明確に分けます。フロントエンドとバックエンドで分離するのが最も簡単です。

順次実行の徹底

並列実行のメリットがない場合は、1つずつ順番に実行します。特にデータベースマイグレーションやスキーマ変更は必ず順次実行してください。

自動実行の危険性

Antigravityの「Always Proceed」モードは生産性を飛躍的に向上させますが、破壊的コマンドが確認なしで実行されるリスクがあります。

過去に報告された事故パターン

本番DBの削除 — 環境変数の設定ミスで、テスト用と思って実行した DROP TABLE が本番データベースに対して実行された
git push --forceによる履歴消失 — リベース中にforceプッシュが自動承認され、他のメンバーの作業が消失
rm -rf の暴走 — パス変数の展開ミスで rm -rf / 相当のコマンドが実行されかけた（サンドボックスで防止）
秘密鍵のコミット — .env ファイルがgit addに含まれ、APIキーがパブリックリポジトリに公開された

安全な設定

settings.json - 推奨設定

{
  "permissions": {
    "deny": [
      "rm -rf",
      "git push --force",
      "DROP TABLE",
      "DELETE FROM",
      "git reset --hard"
    ]
  }
}

✅ Tip

Always Proceedモードを使う場合は、必ずPreToolUseフックで破壊的操作のブロックリストを設定してください。フックはAlways Proceedモードでも強制的に実行されるため、最後の砦として機能します。

事故事例: Turboモードでの「クリーンアップ」指示

09:00

曖昧な指示

開発者がAgent-drivenモード(Turbo)で「プロジェクトをクリーンアップして」と指示

09:01

ファイル特定と削除実行

エージェントが不要ファイルを特定し、rm -rfを実行

09:02

重要ファイルも削除

.envファイルと未コミットの設定ファイルも削除される

09:05

復旧不可能

開発者が気付くが、gitに未追跡のファイルは復旧不可

⚠️ 教訓

Turboモードでは「クリーンアップ」のような曖昧な指示が破壊的操作に繋がる。Request Reviewモードなら09:01の段階でrmコマンドの確認画面が表示され、事故を防げた。

GEMINI.mdの肥大化

GEMINI.mdはエージェントの「脳」として機能しますが、書きすぎると逆効果になります。指示ファイルの最適な長さは80〜120行です。

肥大化の症状

200行超 — エージェントが指示の一部を無視し始める。優先順位の判断が曖昧になる
300行超 — コンテキストウィンドウの大部分を指示ファイルが占有し、コードの分析能力が低下する
500行超 — 矛盾する指示が含まれる確率が高くなり、エージェントの動作が不安定になる

スリム化のテクニック

階層化する

プロジェクトルートのGEMINI.mdは全体方針のみ記述し、サブディレクトリごとにGEMINI.mdを分割します。src/GEMINI.md、tests/GEMINI.md のように分けることで、各ファイルを50行以内に抑えられます。

「やること」ではなく「やらないこと」を書く

ポジティブな指示（〜すること）よりネガティブな指示（〜しないこと）の方が効果的です。エージェントはデフォルトで合理的に動作するため、禁止事項を明記する方が効率的です。

定期的な棚卸し

月に1回、GEMINI.mdを見直し、古くなった指示や重複を削除します。/compact コマンドの出力からエージェントが実際に参照している部分を確認し、不要な指示を除去しましょう。

GEMINI.md - 理想的な構成例（80行）

# プロジェクト概要（5行）
# 技術スタック（10行）
# コーディング規約（15行）
# 禁止パターン（15行）
# テスト方針（10行）
# デプロイ手順（10行）
# よくある問題と対処法（15行）

整理チェックリスト

Step 1: 行数確認
120行を超えていたら整理が必要
Step 2: スキル化候補の特定
特定タスクのみに使うルール（デプロイ手順、DB操作等）をSkillに移動
Step 3: ネガティブ指示の効果確認
「〜しないこと」のルールが実際に守られているか確認。守られていないルールは表現を具体化
Step 4: 重複の排除
AGENTS.mdやSkillsと重複するルールを削除
Step 5: 定期棚卸し
月1回、チームレビューで古くなったルールを削除。PRテンプレートにGEMINI.mdレビュー項目を追加

モデル選択ミス

タスクに対して不適切なモデルを選択すると、品質低下やコスト増大を招きます。各モデルの特性を理解し、タスクに応じて使い分けましょう。

よくある選択ミス

ミスパターン	問題	正しい選択
Flashで複雑なリファクタリング	コード構造の理解が浅く、バグを混入	gemini-2.5-pro を使用
Proで単純なフォーマット修正	コスト過大、速度不足	gemini-2.5-flash で十分
全タスクに同一モデル	コスト最適化の機会損失	タスク別モデル切替
Flashでアーキテクチャ設計	設計の深さが不足、手戻り発生	gemini-2.5-pro で計画

モデル選択の指針

gemini-2.5-pro — 設計、リファクタリング、複雑なバグ修正、コードレビュー。「考える」タスクに最適
gemini-2.5-flash — 定型コード生成、テスト作成、ドキュメント生成、フォーマット修正。「作る」タスクに最適
gemini-2.0-flash — 単純な検索・置換、ファイル操作、ログ解析。「処理する」タスクに最適

📝 Note

モデル切替はGEMINI.mdに方針を記述するか、セッション中に明示的に指定できます。「計画フェーズはPro、実装フェーズはFlash」のようなルールを設定しておくと、自動的にコスト最適化が行われます。

← 前のページ

ワークフロー

プロフェッショナル環境構築