AIコーディングエージェントにプロジェクトのルールを伝えるファイルとして、CLAUDE.mdとAGENTS.mdの2つが定着した。どちらもMarkdownで書くシンプルなファイルだが、設計思想が違う。
この記事では、両者の違いを実際のコード例とともに整理し、どう使い分けるべきかを解説する。
CLAUDE.md — Claude Code専用の最適化ファイル
CLAUDE.mdはAnthropicが公式にサポートするClaude Code専用の設定ファイルだ。リポジトリのルートに置くと、Claude Codeがセッション開始時に自動で読み込む。
最大の特徴は階層構造にある。
~/.claude/CLAUDE.md— ユーザーレベル（全プロジェクト共通）- プロジェクトルートの
CLAUDE.md— リポジトリ全体 - サブディレクトリの
CLAUDE.md— 特定パッケージ向け
Claude Codeはこれらをマージして解釈する。モノレポでフロントエンドとバックエンドで異なるルールを適用したい場合に強い。
# CLAUDE.md（プロジェクトルート）
## プロジェクト概要
Next.js 15 + TypeScript のモノレポ。pnpm workspaces使用。
## 共通ルール
- TypeScript strict mode、anyは使わない
- テストはVitestで書く
- コミットメッセージはConventional Commits準拠
## コマンド
- `pnpm dev` -- 開発サーバー起動
- `pnpm test` -- テスト実行
- `pnpm lint` -- ESLint実行Claude Code固有の機能（Hooks、Permission、sub-agent委譲など）を細かく制御できるのもCLAUDE.mdならではだ。Next.js（138K stars）、LangChain（128K stars）、Excalidraw（118K stars）など大規模OSSでも採用されている。
AGENTS.md — マルチツール時代の共通規格
AGENTS.mdはLinux Foundation傘下のAgentic AI Foundationが管理するオープンフォーマットだ。Claude Code、OpenAI Codex CLI、GitHub Copilot、Cursor、Kilo Codeなど複数のAIツールが読み込みに対応している。
「どのエージェントでも同じルールを読めるようにする」という発想で設計されており、チーム内でツールが統一されていない環境で真価を発揮する。
# AGENTS.md
## Build & Test
- `go test ./...` -- 全テスト実行
- `go vet ./...` -- 静的解析
- `make build` -- ビルド
## Architecture
マイクロサービス構成。各サービスは /services 配下に配置。
共通ライブラリは /pkg に集約。
## Coding Standards
- Go idioms準拠（短い変数名、error wrapping）
- テストは _test.go ファイルにtable-driven testで書く
- vendor/ 配下は変更禁止
## Git Workflow
- feature branchからmainへPR
- CIが通るまでマージ禁止n8n（178K stars）、awesome-go（167K stars）、LangFlow（145K stars）、llama.cpp（97K stars）など、特にGo/Rustエコシステムで採用が多い。
主な違い
対応ツール
- CLAUDE.md: Claude Codeのみ（ファーストクラスサポート）
- AGENTS.md: Claude Code、Codex CLI、Copilot、Cursor、Kilo Code、Factory等
ユーザーレベル設定
- CLAUDE.md: あり（
~/.claude/CLAUDE.mdで全プロジェクトに適用） - AGENTS.md: なし（リポジトリ単位のみ）
ツール固有機能の制御
- CLAUDE.md: Claude CodeのHooks、Permission設定、sub-agent制御が可能
- AGENTS.md: ツール非依存のため、特定ツールの固有機能は制御できない
エコシステムの成熟度
- CLAUDE.md: Anthropic公式ドキュメント充実。500以上の公開事例
- AGENTS.md: Linux Foundation管理の仕様書あり。GitHub Blogでベストプラクティス公開済み。300以上の公開事例、急速に増加中
設計思想
- CLAUDE.md: Claudeの能力を最大限引き出すための専用チューニング
- AGENTS.md: どのエージェントでも動く汎用的なプロジェクトマニュアル
同じリポジトリに共存できる
重要なポイントとして、CLAUDE.mdとAGENTS.mdは同じリポジトリに共存できる。Claude Codeは両方を読み込む。
実用的なパターンはこうだ。
my-project/
AGENTS.md # 全ツール共通のルール（ビルド手順、コード規約、アーキテクチャ）
CLAUDE.md # Claude固有の指示（権限制御、ワークフロー固有設定）
packages/
frontend/
AGENTS.md # フロントエンド固有の共通ルール
backend/
AGENTS.md # バックエンド固有の共通ルールAGENTS.mdにプロジェクトの共通知識を書き、CLAUDE.mdにはClaude Code固有の設定だけを書く。これなら二重管理にならず、他ツールのユーザーもプロジェクトルールを受け取れる。
移行のコツ
既にCLAUDE.mdを運用しているプロジェクトでAGENTS.mdを追加する場合の手順。
CLAUDE.mdの内容をツール非依存な部分とClaude固有の部分に分類する- ツール非依存な部分（ビルドコマンド、コード規約、アーキテクチャ説明）を
AGENTS.mdに移す CLAUDE.mdにはClaude固有の指示のみ残すCLAUDE.mdの冒頭でAGENTS.mdの存在に言及する必要はない（Claude Codeは自動で両方読む）
逆にAGENTS.mdしかないプロジェクトでClaude Codeの活用を強化したい場合は、Claude固有の指示だけを書いたCLAUDE.mdを追加すればいい。
結論 — どう使い分けるか
- チーム全員がClaude Codeを使っている —
CLAUDE.mdだけで十分。Claude固有機能をフル活用できる - チーム内でツールが混在している —
AGENTS.mdをベースにし、必要ならCLAUDE.mdを追加 - OSSプロジェクトのメンテナ —
AGENTS.mdで広くカバーし、Claude Codeユーザーが多いならCLAUDE.mdも併設 - 個人開発でClaude Codeがメイン —
CLAUDE.mdを軸に。将来ツールを変える可能性があるならAGENTS.mdも書いておく
2026年の現実として、AIコーディングツールは乱立している。1つのファイルで全ツールを完璧にカバーすることはできない。だがAGENTS.mdとCLAUDE.mdの併用で、汎用性と最適化の両立はできる。
まずは自分のメインツールに合わせたファイルを1つ書くところから始めよう。
The Prompt Shelfでは、実際のプロジェクトで使われているAIコーディングルールを収集・公開しています。