プロジェクトのコーディング規約を丁寧に書いた。命名規則も、エラーハンドリングのパターンも、テストフレームワークの指定も。なのに、Antigravity のエージェントはまたいつも通りのコードを生成してくる——。
これ、私も何度も経験しました。agents.md は Antigravity を自分のプロジェクトに最適化できる非常に強力な機能なのですが、「書いたけど効かない」という状況になりやすい落とし穴が複数あります。
今回は、よく起きる6つの症状と、それぞれの原因・確認方法・解決策を紹介します。
症状1: agents.md 自体が全く読み込まれていない
最初に疑うのは、ファイルの場所と名前です。
agents.md はプロジェクトのルートディレクトリに置く必要があります。サブディレクトリに入れてしまったり、ファイル名が agent.md（複数形の「s」が欠けている）になっているケースは意外と多いです。
確認手順はこうです。
# プロジェクトのルートにいる状態で確認
ls -la | grep -i agentこのコマンドで agents.md が表示されなければ、置き場所の問題です。
また、Antigravity の設定画面から「Context」セクションを確認すると、現在のセッションで認識しているコンテキストファイルの一覧が見られます。ここに agents.md が表示されていなければ、ファイルがロードされていません。
エージェント自身に「現在参照しているシステムプロンプトを教えてください」と聞いてみるのも効果的です。agents.md の内容が返ってこない場合は、確実に読み込まれていないと判断できます。
agents.md の正しい書き方については AGENTS.md 完全ガイド も参考になります。
症状2: 最初は守られていたのに、途中から無視される
長いセッションで特によく起きます。原因は、コンテキストウィンドウの圧迫です。
Antigravity のエージェントは、コンテキストウィンドウに収まる情報しか参照できません。会話が長くなり、コードや説明が積み重なると、agents.md の内容がウィンドウの外に押し出されてしまいます。この状態では、エージェントが「agents.md が存在しない」のと同じ状況になります。
対処法はシンプルで、agents.md を短くすることです。
長ければよいというものではなく、エージェントがセッションごとに読み直すことを前提に、「絶対に守ってほしいルールだけ」を残すのが正しいアプローチです。詳細な説明や背景情報は別のドキュメントに分けて、agents.md には核心だけを書いてください。
また、セッション中に /reset コマンドを使ってコンテキストをリセットし、agents.md を再読み込みさせる方法も有効です。1つのタスクが終わったら新しいセッションを開始する習慣をつけると、この問題はかなり改善されます。
症状3: 特定のタスクでだけルールが適用されない
「コードスタイルは守られているのに、テスト生成のときだけ従わない」というケースがあります。
たいていの場合、agents.md の記述が曖昧すぎることが原因です。
# ❌ 曖昧で効きにくい記述
- テストは適切に書いてください
- 良いコードを書くこと
# ✅ 具体的で効きやすい記述
- テストには Vitest を使用してください（Jest は禁止）
- describe/it ブロック構造を必ず使用してください
- モックには vi.mock() を使用し、jest.mock() は禁止です
- テスト名は日本語で記述してください「適切に」「正しく」「良い感じに」といった抽象的な表現は、エージェントにとって判断の根拠になりません。何を使い、何を禁止するかを具体的に明示してください。
症状4: 読まれているのに実装に反映されない
エージェントが agents.md を参照していることは確認できているのに、出力に反映されないケースがあります。
よくある原因はルール同士の競合です。agents.md に「TypeScript の any 型は禁止」と書いていても、エージェントが参照しているライブラリのサンプルコードが any を多用していると、そちらに引きずられてしまいます。
また、「とにかく動くコードを早く書いて」という指示を出すと、agents.md のルールよりも「速さ」が優先されることがあります。エージェントはプロンプトの直接指示を agents.md の設定より優先する傾向があります。
対処法として有効なのは、プロンプト内で「agents.md のルールに従って」と明示することです。競合が疑われる場合は、agents.md の該当ルールをコピーしてプロンプトに直接貼り付けてしまうのが確実です。インライン指示は、ファイルレベルのコンテキストよりも強く働きます。
症状5: マルチエージェント構成でサブエージェントが従わない
Manager-Worker パターンで開発をしているとき、Manager エージェントは agents.md を参照していても、タスク実行中に生成されるサブエージェント（Worker）にはルールが引き継がれていないことがあります。
解決策は、Manager のプロンプトで agents.md の重要ルールを明示的に Worker に伝えることです。
## agents.md に追記する例（Manager 向け）
### サブエージェントへの引き継ぎルール
以下のルールをサブエージェントの指示に必ず含めてください:
- コードはすべて TypeScript で記述すること
- エラーハンドリングは必ず try-catch を使うこと
- ファイル名は kebab-case を使うこと
- console.log を本番コードに残さないことこのようにしておくと、Manager がサブエージェントを生成するたびに、ルールが自動的に伝達されます。マルチエージェントの基本設計については Antigravity マルチエージェント入門ガイド も参考にしてみてください。
症状6: Antigravity のアップデート後から突然効かなくなった
これはまれですが、バージョンアップによって agents.md の解析仕様が変更されることがあります。アップデート後に突然効かなくなった場合は、まず公式のリリースノートで agents.md 関連の変更がないか確認してください。
それとあわせて、次の点も確認してみてください。
- YAML フロントマターが agents.md の先頭に入っていないか（不要です。あると誤動作の原因になります）
#で始まるセクション見出しの数が極端に多くないか- ファイルのエンコーディングが UTF-8 になっているか（特に Windows 環境では注意）
バージョン関連の問題が疑われるときは、agents.md を最小限の内容（3〜5行）に絞り込んでテストし、少しずつルールを追加していく方法が原因の特定に有効です。
「半分に減らす」から始めてみてください
agents.md のトラブルは、場所の問題・長さの問題・曖昧な記述の3つに収束することがほとんどです。
まず試してほしいのは、現在の agents.md を半分の量に絞ること。「これがないと困る」というルールだけを残してみてください。エージェントへの伝わり方が格段に改善されることが多いです。
カスタムルールをより体系的に管理したい場合は、Antigravity カスタムルール＆プロジェクト設定 完全実践ガイド に詳しい設定方法がまとまっています。