Antigravityのプロンプトの書き方｜AIエージェントが意図通りに動く指示設計のコツ

本記事を読めば、Antigravityへの指示の粒度・成果物・承認条件を整理でき、手戻りを2〜3回減らして開発作業を安定化できます。

AntigravityはAgent Manager/Editor、Planning/Fast modes、Artifacts、コード差分レビューを備えたエージェント型の開発環境です。AIzen株式会社はAIを組み込んだ業務アプリ開発やAI導入設計を支援する中で成果の差は指示設計に出ると考えています。プロンプトの書き方を整理します。

Antigravityで指示が意図通りに動かない原因

Antigravityは、作業を計画し、実装し、確認結果をArtifactsやコード差分として提示できる環境です。そのため、プロンプトも「質問」ではなく「作業依頼」として設計します。

意図通りに動かない原因の多くは、タスクの境界、成果物、確認方法が曖昧なまま依頼されていることです。

「やり方を聞く」と「やっておいて」の違い

Antigravityに「Reactでフォームを作る方法を教えて」と聞くと、一般的な説明やサンプルコードが返ってきます。一方で、「このリポジトリの問い合わせフォームに必須チェックを追加し、差分と確認手順を出してください」と依頼すると、エージェントは作業対象を調査し、変更案を作り、実装後の確認まで進めやすくなります。

前者は学習用の質問、後者は開発タスクの委任です。実装や修正が目的なら、プロンプトには「何を理解したいか」ではなく「何を完了してほしいか」を書きます。

曖昧な指示でエージェントが暴走する典型例

典型例は「診断ツールを作って」「管理画面をいい感じにして」「エラーを直して」のような依頼です。これだけでは、設問数、分岐条件、結果パターン、対象ファイル、表示形式、テスト方法が分かりません。

たとえば診断ツールなら、「設問は5問、各問4択、結果は3パターン、最後にメール相談CTAを表示、単一HTMLで出力」と指定します。ここまで書くと、不要な推測を減らせます。

プロンプト設計を構成する4つの要素

実務で使うプロンプトは、タスクの粒度、成果物の定義、承認ポイント、リトライ条件の4つで整理できます。この4つがそろうと、Agent ManagerやArtifactsを活かしやすくなります。

要素	書く内容	目的
タスクの粒度	作業範囲、対象ファイル	変更範囲を絞る
成果物の定義	コード差分、表、確認手順	出力形式をそろえる
承認ポイント	実装前、差分作成後、テスト前	人が判断する
リトライ条件	失敗時に変える条件	同じ失敗を避ける

タスクの粒度と成果物定義の書き方

Antigravityに任せる作業は、小さすぎると人が都度指示する手間が増え、大きすぎると確認が難しくなります。最初は「1画面」「1API」に絞るのが現実的です。

1回の指示で任せる範囲の絞り方

1回の指示では、目的と対象を一文で言える範囲に絞ります。「顧客管理を改善して」では広すぎますが、「顧客一覧にステータス絞り込みを追加して」なら対象が明確です。対象ディレクトリや変更してよいファイルも指定すると、差分レビューが楽になります。

複数工程を含む場合は、Planning modeで「まず実装計画だけ作成し、承認後にコード変更へ進む」と書きます。Fast modeは、文言修正や変数名変更など、影響が小さい作業に向いています。

期待する成果物の形式と内容の明示

成果物は、できるだけ形式まで指定します。「調査して」ではなく、「原因候補を表で3つ、確認コマンド、修正方針、影響範囲に分けて出してください」と書くと、レビューしやすい出力になります。

AntigravityはArtifactsやコード差分を扱えるため、実装前の計画、実装後のWalkthrough、ブラウザ確認結果をレビュー材料にできます。「差分を出す前に計画を提示」「完了後に確認手順を整理」と明示すると、チーム内でも流用しやすくなります。

関連ファイルや前提条件の提示

エージェントに任せるときは、関連ファイルや前提条件を最初に渡します。対象画面、API、既存コンポーネント、テストファイル、避けたい実装方針を明記します。「既存のButtonコンポーネントを使う」「新しい状態管理ライブラリは追加しない」といった制約があるだけで、出力品質は変わります。

AIzen株式会社の開発支援でも、プロンプト前に「触ってよい範囲」と「変えてはいけない範囲」を分ける運用を推奨しています。

承認ポイントとリトライ指示の書き方

Antigravityに作業を任せるほど、人間が確認するポイントを先に決めることが重要です。すべてを実行後に確認すると、方向性が違った場合の修正量が大きくなります。

中間レビューを挟む承認フロー

複雑な作業では、「調査」「計画」「実装」「確認」を分けます。「まず関連ファイルを調査し、変更計画を提示してください。承認までファイルは編集しないでください」と書くと、方針を調整してから実装に進めます。

承認フローを入れるべきなのは、複数ファイルにまたがる変更、DBスキーマやAPI仕様に影響する変更、顧客向け画面の挙動変更です。誤字修正やREADME追記のような軽微な作業では、Fast modeでも進めやすいです。

失敗時のリトライ条件と再実行指示

リトライ指示では、「何を変えて再実行するか」を明確にします。「もう一度やって」では、同じ前提で再実行される可能性があります。「テストが失敗した場合は、失敗ログを要約し、原因候補を2つに絞ってから、修正案を提示してください」と書きます。

ブラウザ確認が失敗した場合は、「スクリーンショット、コンソールエラー、再現手順をまとめ、コード変更前に原因仮説を出してください」と指定します。失敗後にすぐ修正させるのではなく、原因の整理を挟むことで、短時間で方向修正できます。

エージェントが暴走したときの停止指示

意図しない範囲まで作業が広がった場合は、早めに停止します。停止指示は「作業を止めて、これまでに変更したファイル、変更理由、未完了タスクを一覧にしてください」と書きます。差分と状態を整理させるのが大切です。

再開するときは、前回の指示をそのまま繰り返さず、「対象をこのファイルだけに限定」「新規ファイル作成は禁止」「既存テストを壊さない範囲で修正」など、制約を追加します。

GEMINI.mdでグローバル指示を整える方法

毎回のプロンプトに同じルールを書くと、入力が長くなり、指示漏れも起きます。よく使う開発ルールや出力形式は、グローバル指示やワークスペースルールとして分離します。

Google Codelabでは、RulesとWorkflowsをグローバルまたはワークスペース単位で扱えると説明されています。~/.gemini/GEMINI.md は、そのうちグローバルルールを置く場所として案内されており、実務上は共通の作法を記録するルールファイルとして扱うと理解しやすいです。

~/.gemini/GEMINI.md の役割と書き方

~/.gemini/GEMINI.md には、個人環境で常に守ってほしい基本方針を書きます。日本語で回答する、実装前に対象ファイルを確認する、破壊的なコマンドは実行前に確認する、未確認事項を最後に出す、といったルールです。

ただし、業務固有の詳細を詰め込みすぎると、別プロジェクトで不要な制約になります。グローバルには全案件で共通する考え方を置き、固有ルールはワークスペース側に分けます。

言語・思考プロセス・出力フォーマットの統一

チームでAntigravityを使う場合、出力フォーマットの統一が重要です。レビュー担当者が毎回違う形式の結果を読むと、確認工数が増えます。調査結果は「結論、根拠、変更候補、リスク、次の作業」、コード変更後は「変更ファイル、確認結果、残課題」と決めます。

思考プロセスについては、詳細な内部推論より、判断に必要な根拠を要約させるほうが実務向きです。「なぜそのファイルを変更するのか」「未確認の前提は何か」を短く出す形式にすると、レビューで使いやすくなります。

プロジェクト共通ルールのチーム共有

プロジェクト共通ルールには、命名規則、ディレクトリ構成、テスト実行方法、PR作成時の観点、禁止したい変更を含めます。たとえば、「UIコンポーネントは既存のdesign-system配下を優先」「APIレスポンスの型は既存schemaを変更しない」「テストは変更対象に近いものだけ実行」といった内容です。

このルールは、開発者だけでなくPMやレビュー担当も読める文章にします。AIzen株式会社では、「AIへ渡す共通ルール」と「人が承認する基準」を分けて文書化することを推奨しています。

失敗例から学ぶプロンプトの書き直し方

プロンプトは一度で完成させるものではなく、実行結果を見ながら書き直すものです。失敗した出力を「AIが悪い」で終わらせず、どの情報が足りなかったのかを分解します。

抽象的な依頼で動かなかった指示の修正

抽象的な依頼は、目的、入力、出力、制約を足すだけで実用的になります。「診断ツールを作って」は、「マーケ担当者がLPに埋め込む診断ツールを、単一HTMLで作成してください。設問は5問、各問4択、結果は3種類、最後に相談CTAを表示します。CSSとJavaScriptは同一ファイル内に含めてください」と書き直します。

このように書くと、エージェントは画面、ロジック、成果物形式を判断できます。「サンプル回答で結果A/B/Cが出ることを確認してください」と加えると、動作確認まで任せやすくなります。

出力品質が安定しない指示の見直し

出力品質が安定しない場合は、プロンプトに評価基準がありません。「きれいにして」「読みやすくして」では解釈が分かれます。UIなら、既存コンポーネント、余白、レスポンシブ対応を指定します。文章なら、対象読者、文字数、見出し維持、禁止語、表の有無を指定します。

弊社エンジニアからのコメント：

Antigravityに「エラーを直して」とだけ依頼すると、再現条件を確認せずに周辺コードを広く変更することがあります。実務では「再現手順と該当ログを整理し、原因候補を2つまでに絞り、承認後に最小差分で修正」と書くほうが安定します。

品質を安定させるには、依頼の最後に「既存テストが通る」「ブラウザで3パターン確認する」など、レビュー可能な完了条件を置きます。

プロジェクト規模・業務カテゴリ別の指示テンプレ

小規模な修正では、対象ファイル、変更内容、確認方法を短く書きます。例として、「src/components/ContactForm.tsx の電話番号バリデーションを修正し、空欄は許可、入力がある場合はハイフンあり・なしを許可してください。関連テストを実行し、差分と確認結果をまとめてください」と書きます。

中規模以上の機能追加では、いきなり実装させず、まず計画を出させます。「対象機能、変更候補ファイル、データフロー、テスト方針、リスクを実装前に提示。承認後にファイル編集へ進む」と書きます。マーケティングなら出力形式とCTA、管理部門なら入力項目と承認条件、開発部門なら変更範囲とテスト条件を入れます。

まとめ

Antigravityのプロンプトは、便利な定型文を覚えるより、タスクをどう委任するかを設計するほうが重要です。意図通りに動かすには、タスクの粒度、成果物の定義、承認ポイント、リトライ条件を最初にそろえます。

Planning modeでは実装前の計画とArtifactsをレビューし、Fast modeでは影響の小さい作業を素早く進める、という使い分けが有効です。~/.gemini/GEMINI.md やワークスペースルールには、言語、出力形式、確認手順を整理しておくと、チーム内の指示品質もそろえやすくなります。

AIzen株式会社では、AIを組み込んだ業務アプリ開発に加え、エージェント型開発環境を前提にしたプロンプト設計、レビュー基準、チーム運用ルールの整備まで支援しています。AIに任せる範囲を広げたい場合は、開発フローの整理からご相談いただけます。