AntigravityでAGENTS.mdが反映されないときの切り分けと対処

Antigravityでエージェントに大きめの作業を任せ始めると、最初にぶつかる壁の一つがAGENTS.mdです。リポジトリ直下に置いてルールを書いたはずなのに、エージェントは平然と禁止したライブラリを足しに行きますし、文字数制限も守ってくれません。私もAntigravityを業務で使い始めた当初、「AGENTS.mdを読んでいないのでは？」と何度も疑った瞬間があります。

私自身、Antigravityで個人開発プロジェクトのセッションを100本以上回す中で、AGENTS.mdが効かないときの典型パターンが見えてきました。症状別の切り分け方をまとめています。アプリ事業を2014年から続けてきた中で、AdMobの収益最適化や癒し系/壁紙アプリの自動化パイプラインにもAntigravityのエージェントを組み込んでおり、ルール統制の重要性は身をもって感じてきた領域です。

まず確認する: AGENTS.mdは「読まれている」か

最初の判定はとても単純で、エージェントが本当にAGENTS.mdを読み込めているかを確認します。チャットで次の一行を投げてみてください。

AGENTS.mdの中で、私が「絶対に避けて」と書いている事項を3つ箇条書きで挙げてください。本文を引用してください。

ここで具体的な禁止事項が返ってこない、あるいは見当違いの内容が返ってくる場合、ファイルそのものが読まれていません。読まれていれば、引用付きで答えが返ります。

「読まれていない」が確定したら、次の3つを順に疑います。

原因A: 配置場所が違う

AntigravityのAGENTS.mdは、現在開いているワークスペースのルートに置く必要があります。monorepoのサブパッケージで作業しているとき、リポジトリのルートにAGENTS.mdがあってもサブパッケージのワークスペースを開いていればそちらは読まれない、というケースが多発します。

確認手順は次の通りです。

# 現在のワークスペースのルートを特定
pwd
 
# そのディレクトリ直下にAGENTS.mdがあるか
ls -la AGENTS.md
 
# サブディレクトリに重複していないか
find . -maxdepth 3 -name "AGENTS.md"

サブパッケージのワークスペースを単独で開いている場合は、サブパッケージ側にもAGENTS.mdを置きます。monorepo全体を開いている場合はルートのみで構いません。

原因B: ファイルが大きすぎてコンテキストに乗らない

これはAntigravityの利用者で最も見落とされがちな原因です。AGENTS.mdが3000行を超えてくると、エージェントがコンテキスト確保のためにファイルの一部だけを読んで打ち切る挙動になります。前半に書いた重要ルールが読まれず、後半の細かい記述だけが残る、といった偏りが出ます。

私のルールは「AGENTS.mdは200行以内、絶対に守ってほしい禁止事項は冒頭20行以内」です。膨らんできたら次のように分割します。

project/
├── AGENTS.md              # 全エージェント共通の絶対ルール（200行以内）
├── .agent/
│   ├── style.md           # コーディングスタイル
│   ├── testing.md         # テスト方針
│   └── deploy.md          # デプロイ手順

そしてAGENTS.mdの冒頭に「詳細は.agent/配下を参照」と書いておきます。Antigravityのエージェントは指示があれば追加ファイルを開きに行きますので、トップだけ薄く保つのが実用的です。

原因C: チャット履歴がルールを上書きしている

長時間の会話でAGENTS.mdの内容が会話履歴に押し出されているケースです。会話の途中で「やっぱりこのライブラリ使っていいよ」と一度許可してしまうと、その後のretryでもAGENTS.mdの禁止より直前の許可が優先されます。

対処は2つあります。

第一に、許可を変更したいときはAGENTS.mdそのものを書き換えてからセッションを切ることです。会話の中で許可するのではなく、ルールファイルを直接更新します。

第二に、長く続いたセッションが暴走し始めたら新しいセッションで仕切り直すことです。同じワークスペースで新規セッションを始めると、AGENTS.mdが先頭に再読込されます。私の感覚では50往復を超えた会話は仕切り直したほうが結果が安定します。

効くAGENTS.mdの書き方

最後に、私が実際に使っているAGENTS.mdの骨格を共有します。Antigravityで複数のアプリ事業（壁紙アプリ、瞑想アプリ、AdMob連携の自動化ツール群）を並行運用してきた中で、削っては足してを繰り返し、最終的にこの形に収れんしました。

# AGENTS.md
 
## 絶対禁止
- 新しいnpmパッケージの追加は提案のみ。実行禁止
- package.jsonのversion変更禁止
- .envファイルの読み書き禁止
 
## 必須確認
- テスト追加時は既存のtests/配下のテストが全てpassすることを実行ログで示すこと
- DB schema変更を含む場合は理由を1段落で説明してから実行すること
 
## スタイル
- TypeScript strictモードに違反しないこと
- async/awaitを使い、Promise.thenは使わないこと
 
詳細は .agent/ 配下を参照してください。

ポイントは「絶対禁止」と「必須確認」を冒頭に置き、命令形で短く書くことです。「〜してください」より「〜禁止」「〜必須」のほうがエージェントの遵守率が体感で2割ほど高くなります。

AGENTS.mdが効くようになると、Antigravityのエージェントは一気に頼れる相棒に変わります。同じ症状で詰まっている方の参考になれば幸いです。