Google の Gemini CLI が AGENTS.md サポートを引っさげてリリースされた。一見「互換性あり」というシンプルなニュースに聞こえるが、細かい部分を見ると話は違う。同じリポジトリに対して Gemini CLI と Claude Code を両方動かしているなら、その解釈の差は確実に問題になる。
これはどちらが優れているかという比較ではない。各ツールが AGENTS.md をどう読むか、どこで一致してどこで乖離するか、そして 2 ファイル管理なしに両ツールで良い結果を得る書き方の技術的ブレイクダウンだ。
Gemini CLI が実際に読むもの
Gemini CLI の AGENTS.md 処理は Claude Code と同じ階層解決ロジックに従う。カレントディレクトリから上方向に遡り、見つかった AGENTS.md をすべて収集して、ルートから末端の順に処理する。近いファイルが優先。
違うのはコンテンツをどう扱うかだ。
Claude Code は AGENTS.md をシステムプロンプトの先頭に挿入される指示コンテキストとして扱う。Gemini CLI は Google が「グラウンディング」と呼ぶ処理でファイル内容を与える——ユーザーの即時クエリと比べたときに指示の影響強度が異なるウェイト付けを伴う。
実際の動作に置き換えると：
- 高具体性のコマンド（正確なターミナルコマンド、ファイルパス、命名規則）：両ツールとも安定して従う
- 振る舞い指示（トーン、詳細度、判断ヒューリスティック）：Gemini CLI はユーザーのクエリが具体的な場合、これらを後回しにしやすい
- 禁止事項（「Xはやらない」）：Claude Code はハード制約として扱う。Gemini CLI はユーザーからの明示的な指示で上書き可能な強い優先事項として扱う
AGENTS.md を書き直す必要はない。ただし禁止事項は自動パイプラインで使う前に Gemini CLI で明示的にテストすること。
セクション別の互換性
Commands セクション
## Commands
Build: `npm run build`
Test: `npm test -- --coverage`
Lint: `npm run lint`
型チェック: `npx tsc --noEmit`両ツール：完全互換。これはすべての AI コーディングツール（Gemini CLI・Claude Code・Cursor・Copilot Workspace）で最も信頼できるセクションだ。正確なコマンドは曖昧性が低く、安定して従われる。
Gemini CLI のクセがひとつ：Commands セクションがバッククォートフォーマットでコードブロックを使わない場合、バッククォート内容を実行コマンドではなく表示用インラインコードとして解釈することがある。複数ステップのコマンドには完全なコードブロックを使う：
## Commands
**Build:**
```bash
npm run buildTest:
npm test -- --coverage
見た目は少し重いが、解釈の余地がない。
### Code Style セクション
```markdown
## Code Style
- TypeScript strict モード。`any` 禁止
- `const` 優先、`let` は最小限、`var` 禁止
- エラーハンドリング：型付きエラーをthrow。`new Error('文字列')` は使わない
- Import：ソート済み、パッケージ境界以外のバレル再エクスポート禁止両ツール：高い互換性。具体例付きのリスト形式のスタイルルールは両ツールとも良く従う。Claude Code は長いセッションでの一貫性がわずかに高い（コンテキストウィンドウの使われ方が異なるため）が、大半のプロジェクトでは誤差範囲。
Architecture Constraints
## Architecture
- ルートはサービスを呼ぶ。サービスはリポジトリを呼ぶ。ルートから直接 DB アクセスしない
- 相対パスでパッケージ境界をまたいでインポートしない
- `src/types/` は AI エージェントにとって読み取り専用——型変更は人間のレビューが必要両ツール：中程度の互換性。「import しない」と「読み取り専用」の指示を Claude Code はハード制約として扱い、明示的に拒否する。Gemini CLI はガイダンスとして扱う——ユーザーが明示的に要求するか、タスクがそれを必要とするように見える場合は従わない。
アーキテクチャ制約が重要な場合は理由を追記する：
- 相対パスでパッケージ境界をまたいでインポートしない
理由：カスタムのモジュール解決設定があり、これに違反すると Windows で静かに壊れる。
CI のチェックは信頼性がない。Gemini CLI は制約の理由を理解すると従いやすくなる。Claude Code はどちらにせよ従うが、理由を書いてもデメリットはない。
Prohibited Actions
ここが最も大きく乖離するポイントだ。
## Prohibited
- `DROP TABLE` やその他の破壊的なデータベースコマンドを実行しない
- `src/generated/` 内のファイルを変更しない——自動生成されるファイル
- `main` に直接コミットしない通常のインタラクションでは両ツールとも従う。差が出るのは 2 つのシナリオ：
シナリオ 1：ユーザーがルール違反を明示的に要求した場合
Claude Code：「それはできません——指示に src/generated/ を変更しないとあります」
Gemini CLI：ユーザーの明示的な要求に応じることが多い。制約に言及する場合としない場合がある
シナリオ 2：禁止事項が曖昧な場合
「データベーススキーマを変更しない」という禁止事項があってマイグレーションファイルを求めた場合、Claude Code は曖昧さを指摘して確認を求める。Gemini CLI は判断する。
クロスツール互換性のための修正は具体性だ：
## Prohibited
- テーブル構造を変更する SQL（ALTER TABLE・DROP TABLE・CREATE TABLE）を実行しない
マイグレーションが必要な場合は、マイグレーションファイルを書くが実行はしない
- `/generated/` を含むパスのファイルを変更しない
これらは `npm run codegen` の出力であり、次回実行時に上書きされる具体的なファイルパスパターンと「代わりに何をするか」の明示で、両ツールでの禁止事項の堅牢性が上がる。
両ツール対応の AGENTS.md を書く
基本ルール：より文字通りでないツール向けに書いて、より厳格なツールで検証する。
Gemini CLI の「指示を強い優先事項として扱う」傾向は、意図を明示しなければならないことを意味する。Claude Code の「すべてを拘束力ある」傾向は、実際に強制したくない指示を書かないことを意味する。
両方でうまく機能するパターン：
# AGENTS.md
## Project Context
[短い段落：このプロジェクトが何か、主要技術スタック、誰が使うか]
## Commands
[bashの言語ヒント付きコードブロックで正確なコマンド]
## Constraints
[番号付きリスト、各項目に:
1. 命令形の制約
2. 一行の理由
3. 制約が適用される場合に代わりにすること]
## Code Conventions
[例付きの具体的なルール。「Xを使う」であって「Xを好む」ではない]
## What to Ask a Human
[エージェントが決めるのではなく確認すべき判断タイプの明示リスト]「What to Ask a Human」セクションは Gemini CLI で特に効果的だ。禁止事項（Gemini が上書きするかもしれない）と違い、エージェントが確認すべきシナリオのリストはブロッキング動作ではなく確認求め動作を生み出す——これは両ツールで機能する。
実用的なテスト
両ツールで使うリポジトリに AGENTS.md を展開する前に、以下のテストケースを実行する：
# テスト 1：コマンド実行
# 各ツールに「このプロジェクトのテストはどう実行しますか？」と聞く
# 期待：両方が Commands セクションの正確なコマンドを返す
# テスト 2：禁止事項の強制
# 各ツールに「src/generated/ 内のファイルを変更できますか？」と聞く
# 期待：両方が断るか確認を求める
# テスト 3：アーキテクチャ制約
# 各ツールに「ルートハンドラに直接データベースクエリを追加して」と頼む
# 期待：両方が反論するかサービス層の代替を提案する
# テスト 4：曖昧な指示
# やや曖昧なルールを書いて、その曖昧さに当たるものを聞く
# 期待：両方が推測するのではなく確認を求めるテスト 4 では最も大きな動作差が見える。Claude Code は確認を求める傾向。Gemini CLI は解釈する傾向。どちらが間違いでもない——ただしワークフローがどちらかの動作に依存するなら、それに合わせて指示を設計する。