Antigravity プロンプトエンジニアリング実践ガイド — AIエージェントの精度を引き上げる指示設計

プロンプトエンジニアリングがAntigravityの生産性を左右する

Antigravity はAIエージェントがコードを自律的に生成・編集する強力なIDEですが、その出力品質はプロンプト（指示）の書き方に大きく依存します。同じ機能を実装するにしても、曖昧な指示と構造化された指示では結果に大きな差が生まれます。

プロンプトエンジニアリングとは、AIに最適な出力を引き出すための指示設計技術です。Antigravity のエージェントは Gemini モデルをベースにしており、適切なプロンプトを与えることで、コード生成の精度、リファクタリングの質、デバッグの効率を飛躍的に向上させることができます。

基本原則：良いプロンプトの5つの要素

Antigravity のエージェントに効果的な指示を出すには、以下の5つの要素を意識しましょう。

1. コンテキスト（背景情報）

AIが現在の状況を正確に理解するための情報を提供します。

❌ 悪い例:
「ログイン機能を作って」

✅ 良い例:
「Next.js 16 App Router + TypeScript のプロジェクトで、
NextAuth.js v5 を使った Google OAuth ログイン機能を実装してください。
既存の src/app/layout.tsx にセッションプロバイダーを追加し、
src/app/login/page.tsx に新しいログインページを作成します。」

2. 具体的なゴール

期待する出力を明確に定義します。

❌ 悪い例:
「パフォーマンスを改善して」

✅ 良い例:
「商品一覧ページの初回ロード時間を短縮するため、
React.memo でコンポーネントのメモ化を適用し、
useMemo で価格計算のキャッシュを追加してください。
現在の ProductCard コンポーネントが毎レンダリングで
再計算しているのが問題です。」

3. 制約条件

守るべきルールや技術的な制約を明示します。

✅ 例:
「以下の制約を守ってください:
- 外部ライブラリの追加は不可（既存の依存関係のみ使用）
- Cloudflare Workers で動作すること（Node.js の fs モジュールは使えません）
- レスポンスは 50ms 以内に返すこと」

4. 出力形式

どのような形式で結果を返してほしいかを指定します。

✅ 例:
「TypeScript の型定義ファイル (.d.ts) として出力してください。
各型にはJSDocコメントで用途を説明し、
エクスポートは named export を使用してください。」

5. 参考例

期待する出力のサンプルを提示します。

✅ 例:
「以下のような形式のユーティリティ関数を作成してください:

// 既存の formatDate 関数（参考）
export function formatDate(date: Date, locale: string): string {
  return new Intl.DateTimeFormat(locale, {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  }).format(date);
}

同様のスタイルで formatCurrency 関数を実装してください。」

コード生成を精密にする構造化プロンプト

Antigravity でコードを生成する際、構造化されたプロンプトを使うと出力の品質が格段に上がります。以下のテンプレートを活用してください。

## タスク
[実装したい機能の概要]
 
## 技術スタック
- フレームワーク: [Next.js 16 / React / Vue.js など]
- 言語: [TypeScript / Python など]
- その他: [使用ライブラリ・ツール]
 
## 要件
1. [具体的な要件1]
2. [具体的な要件2]
3. [具体的な要件3]
 
## ファイル構成
- src/components/[ComponentName].tsx — UIコンポーネント
- src/hooks/use[HookName].ts — カスタムフック
- src/lib/[utilName].ts — ユーティリティ関数
 
## 制約
- [守るべきルール]
 
## 参考
[既存コードの該当部分や、期待する動作の説明]

実際にこのテンプレートを使った例を見てみましょう。

## タスク
商品検索機能をインクリメンタルサーチで実装する
 
## 技術スタック
- フレームワーク: Next.js 16 App Router
- 言語: TypeScript
- その他: Tailwind CSS, Cloudflare D1（データベース）
 
## 要件
1. 入力文字列で商品名と説明文をあいまい検索する
2. 300ms のデバウンスを適用する
3. 検索結果をハイライト表示する
4. 検索結果が0件の場合は代替候補を提示する
 
## ファイル構成
- src/components/SearchBar.tsx — 検索バーUI
- src/hooks/useProductSearch.ts — 検索ロジック
- src/app/api/search/route.ts — APIエンドポイント
 
## 制約
- Cloudflare Workers で動作すること
- D1 の FTS5 を活用すること
- 1リクエストあたり 100ms 以内のレスポンス
 
## 参考
既存の src/app/api/products/route.ts のクエリパターンを踏襲

このような構造化プロンプトを使うことで、Antigravity のエージェントは必要なファイルを正確に生成し、依存関係も適切に処理してくれます。

リファクタリングの精度を上げるプロンプト技法

リファクタリングでは「何を」「なぜ」「どのように」変更するかを明確にする点が肝心です。

Before/After パターン

現在のコードと期待する変更後の方向性を併記するテクニックです。

## 現在のコード（問題点）
- useEffect 内で複数の副作用が混在している
- エラーハンドリングが try-catch の中で console.log のみ
- 型定義が any になっている箇所が3つある
 
## 期待する変更
1. useEffect を責務ごとに分割する（データ取得 / イベント登録 / クリーンアップ）
2. エラーハンドリングを統一されたパターンに置き換える
   - カスタムエラー型を定義する
   - ユーザーに表示するエラーメッセージを設定する
3. any を適切な型に置き換える（推論可能な箇所は推論に任せる）
 
## 変更しないでほしい部分
- コンポーネントの外部API（props の型）は維持する
- テストファイルは変更しない（リファクタ後にテストが通ることを確認）

スコープを限定する指示

大規模なリファクタリングでは、一度に全部を変えようとせず、スコープを明確に限定します。

「src/components/Dashboard/ ディレクトリ内のコンポーネントのみを対象に、
以下のリファクタリングを実施してください:
1. クラスコンポーネントを関数コンポーネント + Hooks に変換
2. PropTypes を TypeScript の interface に置き換え
3. 各コンポーネントの変更後、既存の .test.tsx が通ることを確認

他のディレクトリには一切触れないでください。」

デバッグ効率を最大化するプロンプト設計

バグの調査や修正を依頼する際、状況を正確に伝えるプロンプトがデバッグ時間を大幅に短縮します。

## バグの内容
商品一覧ページで「次へ」ボタンをクリックすると、
2ページ目ではなく1ページ目が再表示される
 
## 再現手順
1. /products にアクセスする
2. 商品が20件表示される（正常）
3. 「次へ」ボタンをクリックする
4. URL は /products?page=2 に変わるが、表示は1ページ目のまま
 
## 期待する動作
2ページ目の商品（21〜40件目）が表示される
 
## 確認済みの情報
- API レスポンス: /api/products?page=2 は正しいデータを返している
- ブラウザの Network タブで確認済み
- useState の page 変数は正しく更新されている（React DevTools で確認）
 
## 疑わしい箇所
src/hooks/useProducts.ts の useEffect の依存配列に
page が含まれていない可能性がある

このように「症状」「再現手順」「期待する動作」「調査済み情報」を整理して伝えることで、エージェントは無駄な探索をせずに原因箇所に直行できます。

AGENTS.md を活用したプロジェクトレベルのプロンプト設計

Antigravity では AGENTS.md ファイルを使って、プロジェクト全体に適用されるプロンプトを定義できます。これにより、毎回同じ制約条件を書く必要がなくなります。

# AGENTS.md
 
## コーディング規約
- TypeScript の strict モードを使用する
- 関数は arrow function で統一する
- コンポーネントは named export を使用する
- インポート順序: React → 外部ライブラリ → 内部モジュール → 型定義
 
## エラーハンドリング
- API エラーは AppError クラスで統一する
- ユーザー向けメッセージは i18n キーで管理する
 
## テスト
- 新規コードには必ずユニットテストを追加する
- テストファイルは同一ディレクトリに .test.ts(x) として配置する
 
## デプロイ環境
- ランタイム: Cloudflare Workers（Node.js API の一部が使用不可）
- データベース: Cloudflare D1（SQLite 互換）
- KVストア: Cloudflare KV

AGENTS.md に共通ルールを書いておくことで、個別のプロンプトではタスク固有の指示に集中できます。AGENTS.md について詳しく知りたい方は、AGENTS.md によるマルチエージェント設計ガイドもご覧ください。

実践テクニック：段階的プロンプト戦略

複雑な機能を一度に実装しようとすると、エージェントが混乱して品質が低下することがあります。段階的にプロンプトを分割する戦略が有効です。

ステップ1: 設計レビュー

「以下の要件で認証システムを実装したいと考えています。
まだコードは書かないでください。
実装方針とファイル構成の提案をお願いします。

要件: NextAuth.js v5 + Google OAuth + Cloudflare KV セッション管理」

ステップ2: 型定義から始める

「提案いただいた設計に基づいて、まず型定義ファイルを作成してください。
- src/types/auth.ts — 認証関連の型
- src/types/session.ts — セッション関連の型
実装はまだ不要です。」

ステップ3: コア実装

「型定義を使って、認証のコアロジックを実装してください。
- src/lib/auth.ts — NextAuth 設定
- src/lib/session.ts — KV セッション管理
テストも同時に作成してください。」

ステップ4: UI統合

「認証ロジックをUIに統合してください。
- src/components/LoginButton.tsx
- src/app/login/page.tsx
- src/middleware.ts（認証ガード）」

この段階的アプローチにより、各ステップでレビューと修正が可能になり、最終的な品質が大幅に向上します。

全体を振り返って

Antigravity のプロンプトエンジニアリングは、AIエージェントの能力を最大限に引き出すための重要なスキルです。コンテキスト・ゴール・制約・出力形式・参考例の5要素を意識した構造化プロンプトを使うことで、コード生成の精度が大幅に向上します。

さらに本格的なエージェント活用テクニックを深めたい方は、Antigravity 実践テクニック集【後編】で上級者向けのワークフローも紹介しています。