monorepo構成で apps/web/AGENTS.md を編集して TypeScript の型ルールを書き足したのに、エージェントがルートの AGENTS.md に書いた古いルールを参照し続けて、コードレビューで指摘した内容と真逆の修正を返してくる——2014年から続けている個人アプリ開発にAntigravityを取り入れた当初、最初の1週間で何度もこの状況に遭遇しました。
問題は「AGENTS.mdが効いていない」のではなく、複数のAGENTS.mdが同時に読まれていて、どちらの指示が勝つかが文脈ごとに変わっていることでした。Google の Antigravity は AGENTS.md を階層的にマージしながら参照するため、書き方を整えないと「両方読まれているがどちらにも従っていない」ように見えてしまいます。この挙動を実機で追跡し、衝突パターンと回避策を整理しました。
Antigravity が複数の AGENTS.md をどう読み込むか
ファイル apps/web/components/Button.tsx をエージェントが編集する場面を想像してください。Antigravity はそのファイルから親方向にディレクトリを遡り、AGENTS.md を順に収集します。
apps/web/components/AGENTS.md（あれば最深部）apps/web/AGENTS.mdapps/AGENTS.mdAGENTS.md（リポジトリルート）
収集された AGENTS.md はコンテキストウィンドウに「リポジトリ全体ルール → 機能スコープ → ファイル直近スコープ」の順に追加され、後から追加されたものが視覚的に「近い」位置に置かれます。多くのケースで深い階層のルールが結果として優先されますが、ルートの指示が明示的・断定的に書かれていると、深い階層の控えめな表現が押し負ける現象が起きます。これが「ルートが勝ってしまう」典型例です。
実際にどちらが勝っているかを確認する診断手順
衝突を疑ったら、まず勝敗を可視化します。Antigravity のチャットで以下のようにエージェントに直接尋ねるのが最短です。
# 診断用プロンプト（コピーして貼り付け可）
今このファイル(apps/web/components/Button.tsx)を編集する際に、
どのAGENTS.mdから何の指示を読み取っていますか？
ファイルパスごとに、影響している規則を箇条書きで列挙してください。
規則同士で矛盾するものがあれば、どちらを優先するか理由付きで答えてください。返答に「ルートの〇〇というルール」「apps/web の△△というルール」が両方挙がり、しかも矛盾を自分で認識できていない場合、それが衝突の証拠です。私は最初、この一文を聞かずに「AGENTS.mdが読まれていない」と決めつけて時間を溶かしました。診断用プロンプトを定型化しておくと、迷う時間が大幅に減ります。
なお、Antigravity の管理画面 (Manager Surface) で「アクティブなコンテキスト」を開くと、現在のセッションで読み込まれている AGENTS.md の一覧が確認できます。並び順は読み込み順と一致するため、目視チェックも可能です。
衝突を避ける書き方:スコープを明示する
最も効くのは、AGENTS.md にスコープを明記する書き方です。ルートの AGENTS.md を「全体共通ルール」、子フォルダの AGENTS.md を「そのフォルダ限定の上書きルール」と役割分担します。
<!-- apps/web/AGENTS.md の冒頭に書く -->
## このファイルの適用範囲
このルールは `apps/web/` 配下のファイルにのみ適用されます。
ルートの AGENTS.md と矛盾する場合、本ファイルの記述を優先してください。
## 型ルール (apps/web 限定で上書き)
- 型推論で済む場面でも、export される関数には明示的な戻り値の型を必ず書いてください
- ルートの AGENTS.md にある「型注釈は必要最小限」というルールは、apps/web では無効ですポイントは「ルートのどのルールを上書きするか」を文章として書いてしまうことです。エージェントは指示が抽象的だと判断に迷うため、矛盾の解消方法を平文で書いておくと、両方の AGENTS.md を読んでも判断がぶれません。私はアプリ事業で運用している壁紙系・癒し系アプリそれぞれにAGENTS.mdを持つmonorepoでこの方式を導入し、エージェントの修正提案の的中率が体感で2倍ほど上がりました。
ルートが勝ってしまうケース:断定形のトーンを揃える
スコープを明記しても勝敗が逆転することがあります。原因のほとんどは「トーンの強弱」です。
- ルートに「絶対に〇〇すること」「禁止」など断定形が多いと、深い階層の「推奨」「望ましい」では押し負ける
- ルートに「すべての TypeScript ファイルで〜」のような全称量化があると、子フォルダの上書きが部分的にしか効かない
書き直すときは、子フォルダ側のトーンも断定形に揃えます。
<!-- 修正前: 弱い表現 -->
- なるべく any 型は避けることが望ましいです
<!-- 修正後: 断定形に統一 -->
- このフォルダ内では any 型を絶対に使わないでください。型定義が困難な場合は unknown と型ガードで対応してください子フォルダ側の語気を強めるのは「失礼」と感じる方もいますが、AGENTS.md は人間ではなくモデルが読む文書です。モデルにとって明確に伝わる表現を選ぶ方が、結果として衝突によるバグを減らせます。
それでも収まらないときの最終手段:統合 AGENTS.md
複数の AGENTS.md を並べても挙動が安定しない場合、最終手段として子フォルダの AGENTS.md を削除し、ルート AGENTS.md にスコープ別セクションをまとめる方法があります。
<!-- ルート AGENTS.md -->
# プロジェクト全体ルール
(共通の規約をここに書く)
# スコープ別ルール
## apps/web/ 配下の追加ルール
- このセクションは `apps/web/` 配下のファイル編集時のみ適用してください
- (固有ルール)
## apps/api/ 配下の追加ルール
- このセクションは `apps/api/` 配下のファイル編集時のみ適用してください
- (固有ルール)階層構造を捨てる代わりに、AGENTS.md の優先順位という変数自体を消すアプローチです。ファイルが大きくなる欠点はありますが、エージェントが「迷う余地」がなくなり、再現性が劇的に上がります。私が運営しているアプリ事業のリポジトリでは、最終的にこの統合方式を採用しています。
階層を活かしたいケースでは、agents.md が効いていない？Antigravity で起きる6つの症状と対処法 と組み合わせて、まずは「読まれているか」を確かめ、それから優先順位の調整に進むのが安全な順序です。マルチエージェント構成での AGENTS.md 設計に踏み込みたい方は AGENTS.md によるマルチエージェント設計 を参照してください。
AI と長く付き合うほど、設定ファイルの一行が後の生産性を大きく左右することを感じます。AGENTS.md の優先順位を整える作業は地味ですが、宮大工だった両祖父が「土台が傾いた家は何年経っても傾いたまま」と話していたのを思い出すたびに、設定ファイルの整備こそ最初に時間をかける価値があると感じています。同じ問題で詰まっている方の参考になれば幸いです。