Antigravity のエージェントが「完了」と言うのにファイルが変わらない：5つの原因と診断手順

エージェントが「変更しました」と答えを返しました。チャットの内容を見ると確かに差分が表示されています。なのにエディタでファイルを開いてみると、コードは一行も変わっていない――。

Antigravity を使い始めた人がはじめてぶつかる落とし穴のひとつが、このエージェントの「幽霊変更」問題です。エラーメッセージも出ず、エージェント自身は成功したと思っています。でもファイルは変わっていません。どこが問題なのか見当がつかず、同じプロンプトを何度も繰り返して時間を無駄にした経験がある人も多いはずです。

この問題が起きる代表的な5つの原因と、5分以内に犯人を特定するための診断フローを順番にご紹介します。

原因パターン1：エージェントが「計画」だけして実行していない

最もよくある原因です。Antigravity の Planning Mode（計画モード）が有効になっているとき、エージェントは変更の手順を提案しますが、実際にはファイルを書き換えません。チャット欄に表示される差分はあくまで「こう変えるつもりです」という提案であり、ファイルへの書き込みはユーザーが明示的に許可するか、Fast Mode で実行しなければ行われません。

確認方法： Antigravity の右上にある現在のモード表示を見てください。「Plan」と表示されている場合はこれが原因です。

修正： モードを Fast Mode に切り替えるか、計画を承認した後に「apply the changes」と指示します。または Settings → Agent → Default Mode を Fast に設定しておくと、意図せず計画モードで止まることを防げます。

// ❌ 計画モードでのやりとり（変更は実行されない）
You: "Add error handling to the fetchUser function"
Agent: "I'll add try-catch to fetchUser. Here's the plan: ..."

// ✅ 変更を実行させる
You: "Add error handling to the fetchUser function and apply the changes"
Agent: [実際にファイルを編集]

原因パターン2：ファイルパスの不一致

エージェントが正しいコードを生成しても、それを「誤ったファイルパス」に書き込もうとして失敗することがあります。とくにモノレポやネストが深いディレクトリ構成のプロジェクトで発生しやすい問題です。

エージェントは src/utils/auth.ts を編集しようとしているが、実際のファイルは apps/web/src/utils/auth.ts にある、というケースです。パスが存在しない場合はエラーになりますが、似た名前のファイルが別の場所にある場合は、そちらが誤って書き換わることさえあります。

確認方法： Antigravity のアクションパネル（右側のサイドバー）を開き、エージェントが最後に操作しようとしたファイルパスを確認します。ターミナルでも確認できます：

# 最近変更されたファイルを確認（過去5分）
find . -name "*.ts" -newer package.json -not -path "*/node_modules/*" 2>/dev/null

修正： プロジェクトルートに AGENTS.md（または rules.md）を置き、ディレクトリ構成を明示しておくと大幅に改善します：

# Project Structure
- Web app: apps/web/src/
- Server: apps/api/src/
- Shared: packages/shared/src/
Always use full paths from project root.

原因パターン3：ファイルの書き込み権限エラー

エージェントがファイルを書き換えようとしたが、OS レベルの権限でブロックされているケースです。特に macOS の場合、フルディスクアクセスが許可されていないと、特定のフォルダへの書き込みが拒否されることがあります。

確認方法： Antigravity のログを確認します：

# macOS: Antigravity のログを確認
cat ~/Library/Logs/Antigravity/antigravity.log | grep -i "permission\|EACCES\|EPERM" | tail -20

EACCES または EPERM が出ていれば権限の問題です。

修正：

macOS: システム設定 → プライバシーとセキュリティ → フルディスクアクセス → Antigravity を追加
ファイル自体が読み取り専用になっている場合：chmod 644 path/to/file
.gitattributes で保護されている場合は設定を確認

原因パターン4：エディタのバッファが古いキャッシュを表示している

Antigravity がファイルを書き換えたにも関わらず、エディタが変更前のバージョンを表示し続けているケースです。VS Code などの外部エディタで同じファイルを開いていると、このキャッシュのズレが発生することがあります。

確認方法： ターミナルから直接ファイルの内容を確認します：

# ターミナルでファイルを直接確認（エディタのキャッシュを経由しない）
cat src/utils/auth.ts | grep -n "try\|catch\|error"

エージェントが追加したはずのコードがターミナルでは見えるのに、エディタに表示されていない場合はキャッシュが原因です。

修正： エディタで対象ファイルを閉じて再度開くか、VS Code なら Cmd+Shift+P → Revert File を実行します。Antigravity の組み込みエディタで作業していれば、この問題は発生しません。

原因パターン5：Git の管理外ファイルへの書き込み

.gitignore に含まれているファイルや、Git 管理外のディレクトリへの書き込みが意図せず行われていて、差分として見えないことがあります。あるいは逆に、エージェントが変更後に git checkout や git stash 相当の操作を行って変更を戻してしまうこともあります。

確認方法：

# 変更の状態を確認
git status
git diff
git stash list  # スタッシュに意図せず積まれていないか確認

修正： スタッシュに変更が入っていた場合は git stash pop で取り出します。エージェントへの指示に「do not run any git commands」と明示するのも有効です。

5分で特定できる診断フロー

原因が複数考えられるときは、以下の順番で確認するのが最も効率的です：

Step 1（30秒）: 現在のモードを確認 → Planning Mode ならば Fast Mode に切り替えて再実行

Step 2（1分）: アクションパネルで最後に操作したファイルパスを確認 → 期待するパスと一致しているか

Step 3（1分）: ターミナルで cat コマンドを使ってファイルを直接確認 → エディタのキャッシュを排除

Step 4（1分）: git status と git stash list を確認 → Git 側での変更消失を排除

Step 5（1分）: ログファイルで権限エラーを検索 → EACCES / EPERM が出ていれば権限設定を修正

この順番で進めると、大半のケースで Step 1 か Step 2 で解決します。Step 5 まで到達することは稀です。

再発を防ぐための設定と習慣

根本的な対策として、以下の設定と習慣を取り入れると同じ問題の繰り返しを防げます。

AGENTS.md でディレクトリ構成を明示する： プロジェクトルートにエージェントへの指示書を置くことで、パス不一致の発生を大幅に抑えられます。

変更後に必ず確認コマンドを習慣化する： 大きな変更を指示したあとは、エージェントに「show me the current content of the changed files」と確認させると安全です。

Planning Mode の使いどころを明確にする： Planning Mode は複数ファイルにまたがる大規模な変更の前に使うもので、日常的な小さい修正には Fast Mode が向いています。Settings でデフォルトモードを自分のワークフローに合わせて設定しておきましょう。

ログを常に確認できる状態にする： Antigravity の Output パネルを常時表示しておくと、エラーに早く気づけます。View → Output → Antigravity で開いたままにしておくのがおすすめです。

「Antigravity の使い方・エージェント操作」をより体系的に学ぶには、Google の公式 Antigravity ドキュメントが参考になります。

今日の最初のアクションは、自分のプロジェクトのルートに AGENTS.md を作ることです。たった数行でエージェントのパス迷子問題の大半を防ぐことができます。