Antigravity でエージェントをセットアップして作業を任せてみたものの、「指示した内容と全然違うことをしている」「途中でタスクを勘違いして変な方向に進んでしまう」という経験はありませんか？これはコードのバグではなく、多くの場合エージェントへの「指示の与え方」に改善の余地がある場合です。
ここではAntigravity のエージェントが期待通りに動かない時の典型的な原因と、その解決策を丁寧に解説します。
エージェントが「誤解」する主な原因
エージェントが指示通りに動かない時、原因は大きく5つのカテゴリに分けられます。
① 指示が曖昧すぎる 「いい感じに修正して」「最適化してほしい」のような曖昧な指示は、エージェントが解釈の余地を広く持ちすぎてしまいます。
② タスクの粒度が大きすぎる 「アプリ全体をリファクタリングして」のような大きすぎるタスクは、エージェントがどこから手をつければいいか迷い、意図しない部分まで変更してしまうことがあります。
③ 前提情報が不足している エージェントはあなたのプロジェクトのコンテキストや制約を常に把握しているわけではありません。「なぜそれをするのか」「何を避けるべきか」の情報がないと、最適でない選択をしてしまいます。
④ agents.md の設定が不十分
Antigravity の agents.md ファイルは、エージェントに対してプロジェクト全体のコンテキストを提供するための重要なファイルです。ここが不足していると、エージェントは毎回ゼロから判断を下すことになります。
⑤ Planning モードと Fast モードの選択ミス 複雑なタスクに Fast モードを使ったり、単純なタスクに Planning モードを使ったりすると、エージェントの動作が期待と乖離します。
改善策1：agents.md を充実させる
agents.md はプロジェクトルートに配置するファイルで、エージェントが作業する際の「行動指針」を定義します。このファイルが充実しているかどうかで、エージェントの動作品質が大きく変わります。
効果的な agents.md の基本構成
# Project: [プロジェクト名]
## プロジェクト概要
[何を作るプロジェクトか、技術スタックを明記]
## 守るべきルール
- [絶対に変更してはいけないファイル・ディレクトリ]
- [必ず従うべきコーディング規約]
- [使ってはいけないライブラリ・パターン]
## タスク実行の原則
- 変更は最小限に留め、関係のないファイルは触らない
- 変更前に現状のコードを把握してから作業を始める
- テストが存在する場合は必ず実行して壊れていないことを確認する
- 不明な点があれば確認してから作業する（推測で進めない）
## プロジェクト固有の重要情報
- 本番環境: [環境情報]
- テスト方法: [テストコマンド]
- デプロイ手順: [デプロイコマンド]よくある漏れ
変更してはいけないファイルや依存関係の制約を明記していない場合、エージェントが意図せず重要なファイルを変更してしまうことがあります。また「確認してから進む」というルールが明示されていないと、エージェントが曖昧な状況で独断で進めてしまいます。
改善策2：タスクを適切な粒度に分割する
エージェントへの指示は、1〜2のアクションで完結できる粒度が最適です。大きなタスクは複数の小さなステップに分割してから依頼しましょう。
粒度が大きすぎる指示の例
「ユーザー認証システムを実装してください」
適切な粒度に分割した例
ステップ1: 「src/auth/ ディレクトリを作成し、AuthContext.tsx を作成してください。Google ログインとメールアドレスログインの2種類に対応する基本的なコンテキストを実装します。」
ステップ2: 「src/hooks/useAuth.ts を作成し、ログイン・ログアウト・ユーザー情報取得の3つのメソッドを持つカスタムフックを実装してください。」
ステップ3:（ステップ2の結果を確認してから）「src/components/LoginForm.tsx を作成し、前のステップで作成した useAuth フックを使ったログインフォームコンポーネントを実装してください。」
改善策3：指示に「制約」と「背景」を含める
良い指示には「何をしてほしいか」だけでなく「なぜするのか」「何をしてはいけないか」が含まれています。
改善前の指示
「パフォーマンスを改善してください」
改善後の指示
「ユーザーから画像読み込みが遅いという報告があります。src/components/ImageGallery.tsx の画像遅延読み込みを実装してください。react-lazyload または Intersection Observer API を使用し、サードパーティライブラリの追加は最小限にしてください。既存のテスト（ImageGallery.test.tsx）は壊さないでください。」
この改善後の指示には、問題の背景（ユーザーの報告）、変更対象ファイルの特定、使用すべき技術の指定、制約（テストを壊さない）が含まれています。
改善策4：Checkpoint を活用して早期に方向を確認する
Antigravity の Checkpoint 機能を使うと、エージェントが大きな変更を加える前に状態を保存・確認できます。
エージェントに作業を依頼する際に「まず計画だけを教えてください。実際の変更は確認後に行ってください」という一文を加えることで、エージェントが最初に方針を確認してから実作業に入るようになります。
万が一エージェントが意図と違う方向に進んでしまった場合も、Checkpoint から復元することで元の状態に戻せます。
改善策5：Planning モードを適切に使う
複雑な判断を伴うタスク（設計の決定、複数ファイルにまたがるリファクタリング、新機能の実装方針の決定）では Planning モードを使いましょう。
Planning モードではエージェントがアクションを実行する前に計画を立て、人間が確認できます。Fast モードは反復的なタスク（テストの追加、ドキュメントの更新、簡単なバグ修正）に向いています。
行き詰まった時のリセット方法
エージェントが完全に意図と違う方向に進んでしまった時は、以下の順番で対処してください。
まず Ctrl+C（または Stop ボタン）でエージェントを停止します。次に Checkpoint から直前の安定状態に戻します。そして agents.md を見直して、今回の問題を防ぐためのルールを追加します。最後に、タスクをより小さく・具体的に分割して再度依頼します。
全体を振り返って
エージェントが思い通りに動かない時、多くの場合は指示の明確さと agents.md の充実度が鍵を握っています。焦らず以下の改善を積み重ねていきましょう。
曖昧な言葉を使わず具体的な対象・方法・制約を指示に含めることが大切です。タスクを小さく分割して確認しながら進めることで誤解を防げます。agents.md にプロジェクト固有のルールを蓄積すると次第にエージェントの精度が上がります。Planning モードで方針を確認してから Fast モードで実行する流れが安定します。
最初はうまくいかないことも多いですが、使えば使うほど「自分のプロジェクトに合ったエージェントの使い方」が見えてきます。ぜひ試してみてください。