AIコーディングツールを使っていると、AGENTS.md と CLAUDE.md という2種類のファイルを見かけることがあります。

どちらも「AIエージェントにプロジェクトのルールや開発方針を伝えるためのMarkdownファイル」という点では似ていますが、対象とするAIツールや位置づけが異なります。

特にClaude Codeを使っている場合、

「AGENTS.mdとCLAUDE.mdはどちらを使えばいい？」
「AGENTS.mdを置けばClaude Codeも読んでくれる？」
「2つを併用するメリットは？」

と疑問に感じる方も多いでしょう。

結論からいうと、Claude Codeを中心に使うならCLAUDE.md、複数のAIコーディングエージェントで共通ルールを使いたいならAGENTS.mdが適しています。

この記事では、AGENTS.md と CLAUDE.md の違いから、Claude Codeでの併用方法、具体的な記述例まで詳しく解説します。

---

AGENTS.mdとCLAUDE.mdの違い

まず、両者の違いを簡単に整理してみましょう。

比較項目	AGENTS.md	CLAUDE.md
主な対象	複数のAIエージェント	Claude Code
位置づけ	ツール横断型の指示ファイル	Claude Codeの公式な指示・メモリファイル
Claude Codeでの自動読み込み	原則対象外	対象
主な用途	AIツール間で共通ルールを共有	Claude Codeにプロジェクト情報を伝える
記述内容	技術スタック、開発ルールなど	技術スタック、開発ルール、Claude固有の指示など
複数AIツール利用	◎	△
Claude Codeのみ利用	○	◎

Claude Codeの公式ドキュメントでは、Claude Codeが標準的に読むファイルはCLAUDE.mdであり、AGENTS.mdはそのままでは読み込まないと説明されています。既存のAGENTS.mdを利用したい場合は、CLAUDE.mdからインポートする方法などが案内されています。 (Claude)

---

AGENTS.mdとは？

AGENTS.mdは、AIコーディングエージェントにプロジェクトのルールや開発方針を伝えるためのファイルです。

例えば、以下のような情報を記載します。

# Project Instructions

## Project Overview

This project is a Python web application.

## Development Rules

- Use Python 3.12.
- Follow PEP 8.
- Write tests for new features.
- Do not modify production configuration without approval.

## Testing

Run:

pytest

AIエージェントがこのファイルをサポートしていれば、プロジェクトのルールを読み取ったうえでコード生成や修正を行えるようになります。

AGENTS.mdの特徴

AGENTS.mdの大きな特徴は、特定のAIツールだけに依存しないことを目的としている点です。

例えば、1つのプロジェクトで、

• Claude Code

• Codex

• Cursor

• GitHub Copilot

• その他のAIコーディングエージェント

などを使い分ける場合、共通する開発ルールを1つのファイルにまとめるという考え方ができます。

そのため、

「AIツールを変更しても、プロジェクトのルールはそのまま使いたい」

という場合に便利です。

---

CLAUDE.mdとは？

CLAUDE.mdは、Claude Codeにプロジェクト固有の情報や指示を伝えるためのMarkdownファイルです。

Anthropicの公式ドキュメントでは、CLAUDE.mdをプロジェクトのアーキテクチャ、コーディング規約、ビルドコマンド、開発ワークフローなどをClaude Codeに伝えるためのファイルとして説明しています。 (Claude)

例えば、次のような内容を記述できます。

# Project Instructions

## Project

This is a Django application.

## Python

- Use Python 3.12.
- Follow PEP 8.
- Use type hints where appropriate.

## Testing

Run:

pytest

## Important Rules

- Do not modify database migrations without checking existing migrations.
- Add tests when implementing new features.

Claude Codeはセッション開始時にCLAUDE.mdを読み込み、そこに書かれたプロジェクト情報をコンテキストとして利用します。 (Claude ヘルプセンター)

---

AGENTS.mdとCLAUDE.mdの最大の違い

両者の最大の違いは、**「誰に向けたファイルなのか」**です。

AGENTS.md

AIエージェント全般
      ↓
AGENTS.md
      ↓
プロジェクト共通ルール

CLAUDE.md

Claude Code
     ↓
CLAUDE.md
     ↓
Claude Code向けのルール

つまり、

AGENTS.md＝AIツール横断型

CLAUDE.md＝Claude Code中心

と考えると分かりやすいでしょう。

---

Claude CodeはAGENTS.mdを読む？

ここは非常に重要なポイントです。

Claude Codeは、AGENTS.mdをCLAUDE.mdと同じように自動で読み込むわけではありません。

Claude Codeの公式ドキュメントにも、

Claude Code reads CLAUDE.md, not AGENTS.md

という説明があります。 (Claude)

そのため、プロジェクトのルートに、

AGENTS.md

だけを置いて、

claude

と起動すれば、当然にClaude CodeがAGENTS.mdをプロジェクト指示として利用してくれる、と考えるのは避けたほうがよいでしょう。

---

AGENTS.mdをClaude Codeで利用する方法

すでにプロジェクトでAGENTS.mdを使っている場合、Claude Codeでもその内容を利用する方法があります。

代表的なのが、CLAUDE.mdからAGENTS.mdをインポートする方法です。

例えば、

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.

というCLAUDE.mdを作成します。

すると、共通ルールはAGENTS.mdにまとめながら、Claude Code固有のルールだけをCLAUDE.mdに追加できます。Anthropicの公式ドキュメントでも、この方法が案内されています。 (Claude)

---

AGENTS.mdとCLAUDE.mdを併用する構成

複数のAIコーディングツールを利用するなら、次のような構成が便利です。

project/
├── AGENTS.md
├── CLAUDE.md
├── src/
├── tests/
├── package.json
└── README.md

AGENTS.md

# Project Instructions

## Project

This is a Next.js application.

## Development Rules

- Use TypeScript.
- Use ESLint.
- Write tests for new functionality.
- Do not introduce unnecessary dependencies.

## Testing

Run:

npm test

CLAUDE.md

@AGENTS.md

## Claude Code

- Explain the implementation before making major changes.
- Use plan mode for large refactoring.
- Do not modify production configuration without approval.

この構成なら、

AGENTS.md

→ AIエージェント共通のルール

CLAUDE.md

→ Claude Code固有のルール

という役割分担ができます。

---

CLAUDE.mdに何を書くべき？

Claude Codeを利用する場合、CLAUDE.mdには「毎回Claudeに説明するのが面倒な情報」を記載すると便利です。

例えば以下のような情報です。

1. プロジェクト概要

## Project

This is an e-commerce application built with Django.

2. 技術スタック

## Tech Stack

- Python 3.12
- Django
- PostgreSQL
- Redis
- Docker

3. テスト方法

## Testing

Run:

pytest

4. コーディング規約

## Coding Style

- Use type hints.
- Follow PEP 8.
- Keep functions small.

5. 禁止事項

## Restrictions

- Do not change database schema without approval.
- Do not add dependencies unless necessary.

Claude Code公式でも、ビルドコマンド、テストコマンド、プロジェクト構造、コーディング規約などはCLAUDE.mdに適した情報として説明されています。 (Claude)

---

AGENTS.mdには何を書くべき？

AGENTS.mdには、AIツールが変わっても維持したいルールを書くとよいでしょう。

例えば、

# AGENTS.md

## Project

Python backend application.

## Development Rules

- Use Python 3.12.
- Follow PEP 8.
- Add tests for new functionality.
- Do not commit secrets.
- Do not modify production data directly.

## Testing

pytest

## Formatting

ruff format .
ruff check .

このように、Claude Code固有の機能には依存しない内容にするのがポイントです。

---

AGENTS.mdとCLAUDE.md、どちらを使えばいい？

用途によって選ぶと分かりやすいです。

Claude Codeだけを使う場合

CLAUDE.mdがおすすめです。

Claude Code
    ↓
CLAUDE.md

Claude Codeの標準的な仕組みに沿って設定できるため、シンプルです。

---

複数のAIコーディングツールを使う場合

AGENTS.mdを共通ルールとして利用する方法がおすすめです。

             ┌→ Claude Code
AGENTS.md ───┼→ Codex
             ├→ Cursor
             └→ その他のAIエージェント

ただし、各ツールのAGENTS.md対応状況や読み込み仕様は異なるため、利用するツールのドキュメントを確認する必要があります。

---

Claude Code固有の設定も必要な場合

AGENTS.md＋CLAUDE.mdの併用がおすすめです。

AGENTS.md
   │
   │ 共通ルール
   ↓
CLAUDE.md
   │
   │ Claude Code固有ルール
   ↓
Claude Code

この構成なら、共通ルールを重複して書く必要がありません。

---

CLAUDE.mdとAGENTS.mdを両方作るメリット

両方を利用する最大のメリットは、共通ルールとツール固有ルールを分離できることです。

例えば、

AGENTS.md

・Pythonのバージョン
・コーディング規約
・テスト方法
・ディレクトリ構成
・禁止事項

CLAUDE.md

・Claude Code固有の指示
・Claude Codeでの作業方法
・Claudeに求める回答形式
・Claude Code特有のワークフロー

という分担ができます。

これによって、複数のAIツールを利用してもプロジェクトの基本ルールを統一できます。

---

CLAUDE.mdを長くしすぎないことも重要

CLAUDE.mdは便利ですが、何でも書けばよいわけではありません。

Claude Codeの公式情報でも、CLAUDE.mdはセッションのコンテキストに影響するため、重要な情報を簡潔に記載することが推奨されています。 (Claude)

例えば、

# Bad

## History

2021年にこのプロジェクトは開始され、
2022年に機能Aを追加し、
2023年には機能Bを追加し……

のような情報は、AIが毎回知る必要がなければ不要です。

一方、

# Good

## Commands

npm run dev
npm test
npm run lint

## Rules

- Use TypeScript.
- Do not modify generated files.
- Add tests for new features.

のように、AIが実際に開発するときに必要な情報を優先します。

---

CLAUDE.mdにはすべてのルールを書く必要はない

Claude Codeには、CLAUDE.md以外にも、Rules、Skills、Subagents、Hooksなど、用途に応じた仕組みがあります。

Anthropicは、CLAUDE.mdを常時必要なプロジェクト情報、Rulesを特定の制約、Skillsを再利用可能な手順などに使い分ける考え方を示しています。 (Claude)

そのため、

CLAUDE.md
↓
プロジェクト全体の基本情報

Rules
↓
特定ファイル・ディレクトリのルール

Skills
↓
繰り返し利用する手順

Hooks
↓
決まった処理の自動化

というように整理すると、AIへの指示が管理しやすくなります。

---

AGENTS.mdとCLAUDE.mdの使い分け【結論】

ここまでの内容をまとめると、次のようになります。

利用環境	おすすめ
Claude Codeだけ	CLAUDE.md
複数AIエージェント	AGENTS.md
複数AI＋Claude Code固有設定	両方
Claude Code固有のルール	CLAUDE.md
AIツール共通のルール	AGENTS.md
プロジェクトの基本情報	どちらでも可
Claude Codeに確実に読み込ませたい	CLAUDE.md

特に覚えておきたいのは、

AGENTS.mdとCLAUDE.mdは、ファイルの中身が大きく違うというより「想定するAIツールの範囲」が違う

という点です。

Claude Codeを中心に開発するなら、まずCLAUDE.mdを使えば問題ありません。

一方、Claude Codeだけでなく複数のAIエージェントを利用するプロジェクトでは、AGENTS.mdに共通ルールを集約し、CLAUDE.mdからAGENTS.mdを読み込む構成が有力です。 (Claude)

---

AGENTS.md・CLAUDE.mdに関するよくある質問

AGENTS.mdとCLAUDE.mdは同じものですか？

同じではありません。

どちらもAIエージェントへの指示を書くMarkdownファイルですが、CLAUDE.mdはClaude Code向け、AGENTS.mdは複数のAIエージェントで共有する用途に向いています。

---

Claude CodeはAGENTS.mdを自動で読み込みますか？

標準ではCLAUDE.mdが対象で、AGENTS.mdをそのまま同じように扱うわけではありません。既存のAGENTS.mdを使う場合は、CLAUDE.mdから@AGENTS.mdとしてインポートする方法があります。 (Claude)

---

AGENTS.mdとCLAUDE.mdの両方を作っても問題ありませんか？

問題ありません。

むしろ、複数のAIコーディングツールを利用するプロジェクトでは、

• AGENTS.md＝共通ルール

• CLAUDE.md＝Claude Code固有ルール

という使い分けが有効です。

---

CLAUDE.mdはどこに置けばいいですか？

プロジェクトルートに置く方法が基本です。

また、Claude Codeではユーザー単位の~/.claude/CLAUDE.mdや、サブディレクトリのCLAUDE.mdなど、スコープに応じた配置も利用できます。 (Claude)

---

CLAUDE.mdは日本語で書いてもいいですか？

はい。

Markdownファイルなので日本語で記述できます。

例えば、

# 開発ルール

- Python 3.12を使用する
- 新機能にはテストを追加する
- 本番環境の設定を勝手に変更しない

のように記述できます。

---

まとめ

AGENTS.mdとCLAUDE.mdは、どちらもAIによるコーディングを効率化するための重要な設定ファイルです。

ポイントを整理すると、

• CLAUDE.mdはClaude Code向け

• AGENTS.mdはAIエージェント横断で利用するための共通ルールとして便利

• Claude Codeは標準ではCLAUDE.mdを読み込む

• AGENTS.mdをClaude Codeで利用する場合は@AGENTS.mdによるインポートなどが使える

• Claude CodeだけならCLAUDE.mdから始めればよい

• 複数のAIコーディングツールを使うならAGENTS.md＋CLAUDE.mdの分離が有効

• AIへの指示は必要な情報に絞り、ファイルを肥大化させないことが重要

特にClaude Codeをこれから本格的に利用するのであれば、まずはプロジェクトルートにCLAUDE.mdを作成し、「毎回Claudeに説明していること」を記録するところから始めるとよいでしょう。

Anthropic公式ドキュメントでも、CLAUDE.mdはプロジェクトのルールやアーキテクチャ、開発コマンドなどをClaudeに伝えるための仕組みとして位置づけられています。 (Claude)

Claude Code公式ドキュメント：Memory（CLAUDE.md）