Antigravity v1.20.3（2026年3月5日リリース）で、静かに、しかし確実に開発体験を変える機能が追加されました。それが AGENTS.mdのサポート です。
これまでGEMINI.mdでプロジェクトのルールを記述していた方には馴染みのある概念かもしれませんが、AGENTS.mdには独自の設計思想があります。今回は、この機能を実際のプロジェクトで使い始めて気づいた変化をお伝えします。
AGENTS.mdとは何か
AGENTS.mdは、プロジェクトのルートに置くMarkdownファイルで、Antigravityのエージェントに対して「このプロジェクトではこう動いてほしい」という指示を事前に与えられる仕組みです。
従来のGEMINI.mdとの最大の違いは、エージェントの行動パターンに特化している点です。GEMINI.mdがコーディングスタイルや言語設定など「何を作るか」の文脈を担うとすれば、AGENTS.mdは「どう動くか」という行動指針を定義します。
具体的には、こういったことが記述できます。
- タスクに取り組む前に確認すべき事項
- 変更を加える際に守るべきファイルやディレクトリのルール
- エラーが発生したときの対処方針
- 外部APIやサービスへのアクセス方法のガイドライン
- テストの実行タイミングと基準
実際に書いてみたAGENTS.md
私がNext.js + Cloudflare Workersのプロジェクトで使っているAGENTS.mdの一部を紹介します。
# プロジェクト概要
このリポジトリはNext.js 16 (App Router) + Cloudflare Workers構成です。
## エージェントへの指示
### 変更前に必ず確認すること
- src/generated/ 配下のファイルは手動で編集しない（generate-content.mjsが自動生成）
- content/articles/ 配下のMDXを追加・変更した後は必ずnode scripts/generate-content.mjsを実行する
### 禁止事項
- node_modules/ への直接書き込み
- .env.local の内容をログ出力・コミットしない
- Worker バンドルが 62MiB を超えるような変更を行わない
### エラー対応方針
- ビルドエラーが発生した場合、まずpackage.jsonのscriptsを確認する
- TypeScriptエラーは自動修正を試みる前に原因を特定して報告する
### テスト
- コード変更後はnpm run typecheck を必ず実行するたったこれだけで、エージェントが「あ、このプロジェクトはこういうルールがあるんだ」と理解した上で動いてくれるようになります。
使ってみて感じた変化
作業を始めるたびに同じ説明をしなくてよくなった
これが一番大きな変化です。以前は会話を開始するたびに「このプロジェクトはCloudflare Workers上で動いているので、fs系のAPIは使えません」とか「generate-content.mjsを実行しないと記事一覧が更新されません」と説明していました。AGENTS.mdに書いておくと、こういった前提知識をエージェントが最初から持った状態でタスクに取り組んでくれます。
間違いが減った
プロジェクト固有のルールをエージェントが把握しているので、「なぜかいつもやってしまうミス」が自然と減りました。特に「src/generated/のファイルを直接編集してしまう」問題は、AGENTS.mdに明示してから一度も起きていません。
チームでの共有が楽になった
AGENTS.mdはリポジトリにコミットするファイルなので、チームメンバーやコントリビューターも同じルールでエージェントを使えます。「新しい人が加わるたびにプロジェクトのお作法を教える」コストが下がりそうです。
GEMINI.mdとの使い分け
両方のファイルが存在する場合、Antigravityは両方を読み込みます。私の整理では以下のように使い分けています。
GEMINI.md（コンテキストと好み）
- コーディングスタイル（Tabか空白か、など）
- 使用言語・フレームワークのバージョン
- プロジェクトのアーキテクチャ概要
- 技術的な制約の背景説明
AGENTS.md（行動ルール）
- 実行してよいコマンドと禁止コマンド
- ファイル変更の前後に行うべき操作
- エラー時の対応フロー
- 品質チェックの基準
この2つを組み合わせることで、エージェントは「何を作るか」と「どう動くか」の両方を理解した状態でタスクをこなしてくれます。
AGENTS.mdを書くときのコツ
実際に何度か書き直して気づいたコツを共有します。
具体的なコマンドを書く
「テストを実行してから変更する」ではなく、「変更後はnpm run typecheck && npm run buildを実行する」のように、実際に打つコマンドを書いた方がエージェントは正確に動きます。
禁止事項は理由と一緒に書く
「XXXは禁止」だけでなく「XXXはYYYという問題が発生するため禁止」と書くと、エージェントが似たような状況で類推して判断できます。
長くなりすぎない
あれもこれも書きたくなりますが、ファイルが長くなりすぎるとエージェントが重要な部分を見落とすことがあります。本当に重要なルールだけに絞り、200行以内を目安にしています。
定期的に見直す
プロジェクトが成長するにつれてルールも変わります。月に一度くらい「このルールはまだ有効か？」と見直すことで、AGENTS.mdが形骸化するのを防げます。
まとめ
AGENTS.mdは地味な機能に見えて、日々の開発効率に大きく影響します。「同じ説明を繰り返している」「エージェントがプロジェクト固有のルールを知らないせいでミスが起きる」と感じている方は、ぜひ試してみてください。
v1.20.3での追加は、AntigravityチームがIDEとしての成熟度をひとつ上げた証拠だと思っています。GEMINI.mdとAGENTS.md、この二枚のカードをうまく使いこなすことで、AIエージェントとの協働がより洗練されたものになるはずです。