CLAUDE.md・AGENTS.md・GEMINI.md の違いと共通化テクニック:3 ツール併用でも二重管理しない

Claude Code、Codex、Gemini CLI を併用すると、それぞれが読むコンテキストファイル(CLAUDE.md、AGENTS.md、GEMINI.md)を用意することになります。同じ内容を 3 か所に書くと、更新のたびにずれていきます。

この記事では、3 つのファイルの仕組みの違いを整理したうえで、1 つの原本から 3 つのツールに読ませる構成を紹介します。

3 つのファイルの比較

項目	CLAUDE.md(Claude Code)	AGENTS.md(Codex ほか)	GEMINI.md(Gemini CLI)
ユーザー共通	~/.claude/CLAUDE.md	~/.codex/AGENTS.md	~/.gemini/GEMINI.md
プロジェクト	ルートの CLAUDE.md / .claude/CLAUDE.md	ルートの AGENTS.md	ルートの GEMINI.md
個人用(Git 管理外)	CLAUDE.local.md	-(.gitignore で運用)	-(.gitignore で運用)
サブディレクトリ	対応(該当ディレクトリ作業時に読み込み)	対応(深い階層が優先)	対応
他ファイルの取り込み	@path インポート記法	-(パスを書いて読ませる)	-(パスを書いて読ませる)
ファイル名の変更	不可	不可	settings.json の contextFileName で可
雛形生成	/init	/init	/init
読み込み確認	/memory	/status	/memory show

役割はどれも「エージェントへの前提説明」で、書くべき内容(コマンド、規約、変更禁止、進め方)も同じです。違いは読み込みの仕組みだけなので、共通化の余地が大きいです。

方法 1:AGENTS.md を原本にして CLAUDE.md からインポートする

AGENTS.md は複数ツールが採用する共通形式なので、原本に向いています。Claude Code は @ インポート記法で他のファイルを取り込めます。

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code 固有
- 3 ファイル以上の変更は Plan Mode で方針を提示してから着手する
- レビューは code-reviewer サブエージェントを使う

これで、Claude Code は AGENTS.md の内容と固有の指示の両方を読みます。

方法 2:Gemini CLI に AGENTS.md を読ませる

Gemini CLI は、読み込むファイル名を設定で変更できます。

{
  "contextFileName": ["AGENTS.md", "GEMINI.md"]
}

~/.gemini/settings.json(ユーザー)または .gemini/settings.json(プロジェクト)に書きます。配列で複数指定できる場合は、AGENTS.md を共通、GEMINI.md を固有の指示として両方読ませます。単一の文字列しか受け付けないバージョンでは "contextFileName": "AGENTS.md" とし、固有の指示は AGENTS.md 内に「Gemini CLI 向け」のセクションとして書きます。

方法 3:シンボリックリンク

インポートや設定変更ができない場合の最後の手段です。

ln -s AGENTS.md GEMINI.md

Git はシンボリックリンクを管理できますが、Windows 環境のメンバーがいると扱いに差が出ます。方法 1・2 で済むなら、そちらを優先してください。

推奨構成

リポジトリ/
├── AGENTS.md            # 原本。共通のコマンド・規約・変更禁止・進め方
├── CLAUDE.md            # @AGENTS.md + Claude Code 固有
├── .gemini/
│   └── settings.json    # contextFileName で AGENTS.md を指定(+ 固有は GEMINI.md)
├── GEMINI.md            # Gemini CLI 固有(任意)
└── docs/
    └── architecture.md  # 長い文書は分離し、原本からパスで参照

原本の AGENTS.md には、ツール名に依存しない書き方をします。

# プロジェクト概要
(1〜2 行)

## コマンド
- テスト: `pnpm test`
- Lint / 型チェック: `pnpm lint && pnpm typecheck`

## 規約
- ...

## 変更禁止
- ...

## 作業の進め方
- 変更前に関連テストを読む
- 複数ファイルにまたがる変更は方針を先に提示する
- テストが通らない状態で完了報告をしない

## 参照
- アーキテクチャ: docs/architecture.md

「Plan Mode を使う」「サブエージェントを使う」のようなツール固有の機能名は、各ツールのファイル側に書きます。

ツール固有に書くべき内容の例

ツール	固有の指示の例
Claude Code	Plan Mode の利用条件、使うサブエージェント名、スキル名
Codex	推奨プロファイル名、codex exec での実行条件
Gemini CLI	チェックポイント機能の利用、/memory add で記憶させる内容

各ファイルの書き方の詳細は、CLAUDE.md の書き方、Codex CLI のセットアップと AGENTS.md の書き方、Gemini CLI のインストールと GEMINI.md の書き方 を参照してください。

サブディレクトリでの運用

3 ツールともサブディレクトリのファイルに対応しています。モノレポでは、ルートに全体方針、各パッケージに固有ルールを置きます。このときも原本は各階層の AGENTS.md にし、CLAUDE.md は @AGENTS.md の 1 行だけにしておくと管理が楽です。

まとめ

• 3 つのファイルは役割も書く内容も同じ。違いは読み込みの仕組みだけ
• AGENTS.md を原本にし、CLAUDE.md は @AGENTS.md でインポート、Gemini CLI は contextFileName で読ませる
• ツール固有の機能名(Plan Mode、プロファイル名など)は各ツールのファイルに書く
• コピーによる同期は避け、ツール側の参照の仕組みを使う