CLAUDE.md vs CONVENTIONS.md vs AGENTS.md: 2026年版 決定版比較ガイド

3つのファイル。表面上はどれも同じ仕事をする——AIツールにコードベースの作法を伝える。だが選択を間違えると、エージェントがルールを無視したり、重複設定が乖離したり、3つのAIツールのうち1つしかルールを読まなかったりする。

これは2026年現在の CLAUDE.md・CONVENTIONS.md・AGENTS.md の決定版比較だ。各フォーマットの実態、対応ツール、弱点、移行方法をすべて解説する。

クイックリファレンス

CLAUDE.md とは何か

CLAUDE.md は Claude Code 向けの Anthropic ネイティブ設定フォーマットだ。リポジトリルート（およびオプションでサブディレクトリ）に置く Markdown ファイルで、Claude がセッション開始時に必ず読み込む。コードベース用の永続システムプロンプトだと思えばいい——変数の命名から手を触れてはいけないディレクトリまで、Claude の挙動すべてに影響する。

フォーマットは意図的にシンプルだ。スキーマ不要の標準 Markdown、見出し単位で整理する。だが Claude Code はその上にいくつかの高度な機能を乗せている。

階層ロード。 リポジトリルートに CLAUDE.md を置き、src/frontend/ にも、packages/api/ にも置ける。Claude は作業場所に基づいてそれらをロード・マージする。packages/api/CLAUDE.md のルールはそのサブツリーでルートを上書きする。

インポートシステム。 @path/to/file 構文で他のファイルのコンテンツを取り込める。モノレポで特に重要で、ルートの CLAUDE.md が @packages/frontend/conventions.md と @packages/backend/rules.md からインポートすることでコンテンツの重複を避けられる。

# Project

3パッケージのモノレポ。

@packages/frontend/CLAUDE.md
@packages/backend/CLAUDE.md
@packages/infra/CLAUDE.md

ユーザーレベルとローカルオーバーライド。 ~/.claude/CLAUDE.md でユーザー全体の設定を指定。CLAUDE.local.md はデフォルトで gitignore される——バージョン管理に載せたくないマシン固有のルールを書く場所だ。チームの設定を汚染せずに個人的なテスト詳細度やログ形式を設定できる。

名前付きサブエージェント定義。 CLAUDE.md（または AGENTS.md）内で名前付きエージェントを定義できる——独自のシステムプロンプト、ツール権限、モデル設定を持つ特化 Claude インスタンスだ。

## agents

### code-reviewer
prompt: |
  セキュリティとパフォーマンスに特化したコードレビュアーです。
  eval()、innerHTML代入、パラメータなしSQLを検出してください。
  具体的でアクション可能なコメントのみ返してください。
tools: [read_file, search_files]
model: claude-opus-4-5

CLAUDE.md の強み

• Claude Code との最深統合——全高度機能を活用できる
• インポートシステムで大規模リポジトリの設定乖離を防ぐ
• 階層ロードでモノレポ設定が外科的に行える
• ローカルオーバーライドで個人設定をチーム設定から分離
• 豊富な実績（Next.js・Deno・LangChain が CLAUDE.md を同梱）

CLAUDE.md の弱み

• Claude Code 専用。Cursor は部分的に読むが全機能を活用しない。他のツールは完全に無視する。
• インポート構文が Anthropic 固有——他のツールに転用できない
• 公式の lint・バリデーションツールがない
• 複数の AI コーディングツールを使うチームは追加設定ファイルが必要

CONVENTIONS.md とは何か

CONVENTIONS.md は Windsurf の Cascade AI から生まれた。Windsurf 向けのネイティブ設定ファイルで、Claude Code にとっての CLAUDE.md と同じ役割を果たす——Cascade がプロジェクトの規約を理解するための永続コンテキストファイルだ。

フォーマットは CLAUDE.md とほぼ同一で、スキーマ不要の Markdown、見出し単位で整理する。主な構造的違いは、CONVENTIONS.md が通常単一ファイルで階層ロードシステムを持たないことだ。

典型的な CONVENTIONS.md:

# Project Conventions

## Tech Stack
- Framework: SvelteKit with TypeScript
- Styling: CSS Modules（Tailwindなし）
- Testing: Vitest + Playwright
- Package manager: pnpm

## 命名規則
- コンポーネント: PascalCase（Button.svelte、button.svelteではない）
- ユーティリティ: camelCase（formatDate.ts）
- 定数: SCREAMING_SNAKE_CASE
- ストア: Store サフィックス（cartStore.ts）

## 立ち入り禁止
- src/lib/generated/ は変更しない（Prisma自動生成）
- tsconfig.json の strict 設定は変更しない

CONVENTIONS.md の強み

• Windsurf/Cascade 専用——そのエコシステムで最良の結果が出る
• CLAUDE.md を知っていれば書き方が自明
• 単一ファイル構成はほとんどのプロジェクトで機能する

CONVENTIONS.md の弱み

• Windsurf/Cascade 専用。Claude Code と OpenAI Codex は無視する。
• 階層ロードなし、インポートなし
• サブエージェントサポートなし
• コミュニティが小さい（代替手段と比べて約8Kリポ）

CONVENTIONS.md が有効なケース

Windsurf 一択でいく予定のチームなら CONVENTIONS.md で Cascade パフォーマンスを最大化できる。ただし実際には Windsurf ユーザーの多くがクロスツール互換性のため AGENTS.md も管理している。両方持つのが安全だ。

AGENTS.md とは何か

AGENTS.md は Linux Foundation 傘下の Agentic AI Foundation が管理するオープン・ツール非依存の標準だ。目標は、どの AI コーディングツールも読める単一ファイル——ツールごとに別々の設定を管理する必要をなくすこと。

フォーマットは標準 Markdown。トップレベルのコンテンツはプロジェクトを説明し、名前付きセクションでサブエージェントを定義する（Claude Code・OpenCode が対応）。

# AGENTS.md

## プロジェクト概要
Go 1.22 REST API、PostgreSQL 16バックエンド。認証はJWT。

## コマンド
- ビルド: `go build ./...`
- テスト: `go test ./... -race -cover`
- Lint: `golangci-lint run --fix`

## コーディング規約
- テーブル駆動テストをソース横の _test.go に
- エラーラッピング: `fmt.Errorf("context: %w", err)`

## 立ち入り禁止
- `migrations/` — Atlas マイグレーション専用
- `vendor/` — `go mod vendor` 後にコミット

2026年現在のツール対応状況:

AGENTS.md の強み

• 最広範なツールカバレッジ——1ファイルで複数ツールに対応
• Linux Foundation 管理のオープン標準——ベンダーロックインなし
• 60,000+ リポジトリが採用——実証済みパターンが豊富
• 異種 AI ツール環境のチームに最適なデフォルト

AGENTS.md の弱み

• 階層ロードなし（CLAUDE.md の機能は Claude Code のみ）
• 「AGENTS.md サポート」の意味がツールによって異なる
• インポートシステムなし——大型設定が肥大化しやすい
• 両方ある場合 Claude Code は CLAUDE.md を優先——AGENTS.md はフォールバック

実世界の意思決定マトリクス

CLAUDE.md を選ぶケース

チームが Claude Code 一択で、フル機能を活用したい場合。インポートシステム・階層ロード・ローカルオーバーライドが、ツール固有フォーマットを正当化する。複雑なディレクトリ構造のプロジェクトでは特に有効: 6パッケージのモノレポが、巨大なルート設定1本ではなく外科的なパッケージ別ルールを持てる。

AGENTS.md を選ぶケース

チームが複数の AI コーディングツールを使う場合。Claude Code 使用者・Cursor 使用者・CI で OpenAI Codex を使う環境が混在するなら、全員が読めるフォーマットが必要だ。将来のツール移行も見据えるなら、AGENTS.md が設定の持ち運びを保証する。

すべて使うケース

Windsurf ユーザーがいるマルチツール環境。AGENTS.md を正規ソースとして管理し、CLAUDE.md で Claude Code 固有機能を追加、CONVENTIONS.md で Windsurf を最適化する。複数ファイルに聞こえるが、共通セクション（ビルドコマンド・立ち入り禁止ディレクトリ）を AGENTS.md に一元化して他がインポートすれば重複は最小化できる。

マイグレーションパターン

CLAUDE.md から AGENTS.md へ

ほとんどのコンテンツは直接転用できる。転用できない要素:

1. インポート文（@path/to/file）——コンテンツをインライン展開するか削除する
2. サブディレクトリの階層 CLAUDE.md——ルートの AGENTS.md 1本に統合するか、ディレクトリ別に AGENTS.md を維持する
3. ユーザーレベルの設定——個人の dotfile に移す

AGENTS.md から CLAUDE.md へ

全コンテンツがそのまま転用できる。Claude Code はネイティブで AGENTS.md を読む。移行は追加であり削除ではない: インポート・階層ルール・ユーザーレベルオーバーライドを活用する余地が生まれる。

Step 1: AGENTS.md を CLAUDE.md にそのまま複製する
Step 2: ディレクトリ別ルールをサブディレクトリの CLAUDE.md に移す
Step 3: 個人設定を CLAUDE.local.md（gitignore済み）に移す
Step 4: パッケージ間の重複ルールをインポートで排除する

CLAUDE.md と AGENTS.md を並行運用する

AGENTS.md を正規ソースとして、CLAUDE.md でインポートする方法がベスト:

# CLAUDE.md
# Claude Code 固有設定。共通ルールは AGENTS.md に。
# このファイルは Claude Code 固有機能（インポート・サブエージェント・パススコープ）を追加する。

@AGENTS.md

## Claude 固有設定

### サブエージェント
[Claude サブエージェント定義...]

AGENTS.md の変更が常に正規ソースとして扱われ、CLAUDE.md に自動的にインポートされる。

避けるべきアンチパターン

コンテンツが重複した3ファイルを独立管理する。 CLAUDE.md・AGENTS.md・CONVENTIONS.md のビルドコマンドが全部違う内容だと、ツールごとに異なる情報を受け取るエージェントが生まれる。

AGENTS.md 内で CLAUDE.md インポート構文を使う。 @path/to/file は Claude Code 固有。AGENTS.md を読むツールはそれをリテラル文字列として出力する。

コミット済み CLAUDE.md にユーザー設定を書く。 ログ詳細度・テスト出力形式・個人コードスタイルは CLAUDE.local.md に。コミットするとチーム全員に強制される。

空のスタブファイル。 空の AGENTS.md はないよりも悪い——ツールはそれを読んで有用な情報を得られず、デフォルトより悪い挙動を示すことがある。

まとめ

2026年の実用的なデフォルト:

• 単一ツール（Claude Code）: CLAUDE.md のみ、フル機能を活用
• 単一ツール（Windsurf）: CONVENTIONS.md + 移植性のための AGENTS.md
• 複数 AI ツール: AGENTS.md を正規ソース、CLAUDE.md でインポートして拡張
• 既存フォーマットからの移行: AGENTS.md → CLAUDE.md は簡単、CLAUDE.md → AGENTS.md はインポートのインライン展開が必要

フォーマットの選択よりもコンテンツの質が重要だ。丁寧に書かれた AGENTS.md は中身の薄い CLAUDE.md に勝つ。

関連記事: AGENTS.md vs CLAUDE.md の2択比較 と CLAUDE.md テンプレート10選 も参照してほしい。