CLAUDE.md と AGENTS.md ―2つのフォーマットの違い・書き方・ベストプラクティス

取り組みの背景

プロジェクト設定ファイルの標準化は、AI駆動開発の効率性を大きく左右します。特に AGENTS.md と CLAUDE.md の登場により、AIツールがプロジェクトの意図を正確に理解できるようになりました。

ここでこれら2つのフォーマットの違い、それぞれの書き方、そして複数AIツールとの共存パターンを実践的に解説します。

AGENTS.md とは―事実上の標準フォーマット

背景：Linux Foundation傘下での正式採択

2025年、Agentic AI Foundation（AAIF）は AGENTS.md をエコシステム標準として正式採択しました。現在、GitHub全体で 60,000以上のリポジトリ がこのフォーマットを採用しており、単なる「提案」ではなく「事実上の標準」となっています。

AGENTS.md の目的

AGENTS.md は、AIエージェントが自動でプロジェクトを理解し、正しく動作できるようにするためのメタデータ層 です。人間が書いたREADMEとは異なり、AIが機械的に解析し、実行可能な指示として活用することを想定しています。

対応ツール（2026年3月時点）

| ツール | AGENTS.md対応 | CLAUDE.md対応 | 優先順序 | |---|---|---|---| | Claude Code | ✓ Fallback | ✓ Primary | CLAUDE.md優先 | | Codex CLI | ✓ Full | ✓ なし | ディレクトリ階層走査 | | Cursor | ✓ Root only | ✓ なし | ルートのみ | | GitHub Copilot | ✗ 未実装 | ✗ 未実装 | プロンプトから推測 | | Gemini CLI | ✓ Full | ✓ なし | 両方対応 |

CLAUDE.md とは―Claude Code専用の最適化フォーマット

設計思想

CLAUDE.md は Claude Code（Anthropic公式CLI） のために最適化された設定ファイルです。AGENTS.mdよりも以下の点で異なります：

Claude特有の機能 に焦点（Cowork連携、記憶機能など）
より詳細なコンテキスト情報 をサポート
複数ファイル同時編集 時のルール定義
段階的実行（Step 0〜8） などの詳細フロー指定

構成例

---
# プロジェクト概要
## 技術スタック
## 最重要ルール
### 1. [ルール1]
### 2. [ルール2]
...
## 記事作成の完全ワークフロー

CLAUDE.md は 構造化セクション で、人間にも読みやすく、Claude Codeが解析しやすい形式になっています。

AGENTS.md と CLAUDE.md の違い

1. フォーマット構造

| 項目 | AGENTS.md | CLAUDE.md | |---|---|---| | 基本形式 | YAML + Markdown | 見出し + Markdown | | マシン可読性 | YAML パーサー前提 | テキスト行走査 + セクション抽出 | | 人間可読性 | 中程度（YAML 文法がある） | 高い（純粋なMarkdown） | | 拡張可能性 | YAMLスキーマで厳密 | セクション追加で自由 |

2. カバレッジ

AGENTS.md が得意な領域：

環境セットアップ（依存関係、バージョン指定）
テスト・ビルド・デプロイコマンド
ファイル構成の説明
禁止項目（触らないファイル、変更禁止ロジック）

CLAUDE.md が得意な領域：

段階的ワークフロー（Step 0 → Step 8）
Claude Code特有の機能（スケジュールタスク、Cowork連携）
プロジェクト運用マニュアル
トラブルシューティング辞典

3. 実行順序

AI ツール起動
    ↓
CLAUDE.md を検索（Claude Code の場合）
    ↓ [見つからない場合]
AGENTS.md を検索（フォールバック）
    ↓ [見つからない場合]
ディレクトリ階層走査（Codex CLI）
    ↓ [見つからない場合]
プロンプト履歴から推測（GitHub Copilot など）

効果的な書き方

AGENTS.md の書き方（実践例）

# agents.md
---
agents:
  - name: "Frontend Developer"
    role: "React/TypeScript開発"
    constraints:
      - "src/components/* のみ編集可能"
      - "API呼び出しは src/services/* に集約"
      - "スタイルは Tailwind CSS のみ使用"
    verification:
      - "npm test が全て pass"
      - "npm run lint がエラーゼロ"
      - "型チェック: tsc --noEmit"
 
  - name: "Backend Developer"
    role: "Node.js API開発"
    constraints:
      - "src/api/* のみ編集可能"
      - "データベーススキーマ変更は禁止"
    verification:
      - "npm run test:api"
      - "curl http://localhost:3001/health"
 
technology_stack:
  - "React 19 + TypeScript 5"
  - "Node.js 20 + Express"
  - "PostgreSQL 15"
  - "Docker Compose"
 
build:
  frontend: "npm run build:web"
  backend: "npm run build:api"
  test: "npm test"
  deploy: "docker-compose up -d"
 
prohibitions:
  - "node_modules を直接編集"
  - "package.json の勝手な変更"
  - ".env.local を Git コミット"
  - "マイグレーションの巻き戻し"
---

CLAUDE.md の書き方（実践例）

# MyProject — CLAUDE.md
 
このファイルは MyProject の Claude Code 用設定ファイルです。
 
## 最重要ルール
 
### 1. 常に TypeScript を使用する
デフォルトで JavaScript は禁止。例外: モノリシック設定ファイル（webpack.config.js等）のみ。
 
### 2. テストファイルは src/tests/ に集約
- ❌ src/components/Button.test.tsx
- ✓ src/tests/Button.test.tsx
 
### 3. スタイル定義は CSS Modules のみ
Tailwind CSS の直接記述は禁止。理由: scoped styling により名前衝突を防止。
 
## Step 0〜8 ワークフロー
 
### Step 0: 環境準備
```bash
git clone [github.com](https://github.com/user/myproject.git)
cd myproject
npm install --prefer-offline

Step 1: 型チェック

tsc --noEmit

Step 2: テスト実行

npm test -- --coverage

Step 3: コード作成

...

Step 4: Lint + Format

npm run lint:fix

...

よくあるミス＆対処法

ミス1: CSS-in-JS ライブラリの混用

❌ styled-components と CSS Modules の混用 ✓ CSS Modules のみ使用

ミス2: 外部ライブラリの過度な追加

❌ npm install lodash moment 等の大型ユーティリティ ✓ 既存の依存関係の中で実装

...


---

## ベストプラクティス

### パターン1: 小～中規模プロジェクト（< 10万LoC）

✓ AGENTS.md を作成（60,000リポジトリの標準に準拠） ✓ CLAUDE.md は不要


**利点：**
- Codex CLI、Cursor、Gemini CLI などマルチAIツール対応
- 標準フォーマットのため、新しいメンバーも容易に理解
- ツール更新で自動対応される可能性が高い

### パターン2: Claude Code 中心の大規模プロジェクト

✓ CLAUDE.md を作成（詳細なワークフロー） ✓ AGENTS.md も併置（フォールバック用）


**構成例：**

project/ ├── CLAUDE.md ← Claude Code の詳細設定 ├── agents.md ← 他ツール用（AGENTS.md） ├── README.md ← 人間向けドキュメント ├── src/ ├── tests/ └── docs/


### パターン3: 複数AIツール + 複数チームメンバー

✓ AGENTS.md を基本とし、複数ロール定義 ✓ CLAUDE.md で Claude Code 固有のワークフロー ✓ .cursorrules / .copilot-instructions も併用


**効果：**
- GitHub Copilot（.copilot-instructions）
- Cursor（.cursorrules）
- Claude Code（CLAUDE.md）
- Codex CLI（AGENTS.md）

が各自のフォーマットで指示を受け取れる

---

## 重要なセクション構成

AGENTS.md / CLAUDE.md 両方で **必ず含めるべき5つのセクション：**

### 1. プロジェクト概要 / 技術スタック
```markdown
## プロジェクト概要
- 目的:
- 対象ユーザー:
- コアアーキテクチャ:

## 技術スタック
- フロントエンド: React 19 + TypeScript
- バックエンド: Node.js 20 + Express
- データベース: PostgreSQL 15
- インフラ: Docker Compose + GitHub Actions

2. ビルド・テスト・実行コマンド

## コマンドリファレンス
```bash
npm install           # 依存関係のインストール
npm run dev          # ローカル開発サーバー起動
npm test             # 全テスト実行
npm run build        # 本番ビルド
npm run lint:fix     # Lint + 自動修正


### 3. コーディング規約 / 設計方針
```markdown
## コーディング規約
- TypeScript 厳密モード（strict: true）
- 命名規則: camelCase（変数・関数）、PascalCase（型・コンポーネント）
- ファイルサイズ上限: 300行（超過時は分割）

4. テスト指示

## テスト指示
- カバレッジ: 80% 以上必須
- テストフレームワーク: Vitest
- E2E: Playwright（src/tests/e2e/）

5. 禁止事項（Prohibitions）

## 禁止事項（AIが絶対に行わない）
- node_modules 内のファイル直接編集
- .env ファイルのコミット
- データベーススキーマの自動作成
- 依存関係のメジャーバージョン更新（事前承認なし）

実践例：段階的な追加方法

初期版（最小限）：

5〜10個の最重要ルール を書く

成長段階（運用開始後）：

よくあるエラー / ミスパターンを追加
→ 各エラーの対処法を記載

成熟段階（6ヶ月以降）：

複数ロール定義（Frontend / Backend / QA）
ステップ・バイ・ステップのワークフロー
詳細なトラブルシューティング辞典（30〜50項目）

まとめ

| 項目 | AGENTS.md | CLAUDE.md | |---|---|---| | 採用すべき場面 | マルチAIツール / 標準化重視 | Claude Code 中心 / 詳細ワークフロー | | 対応ツール数 | 4+ | 1（ただし最適化） | | 学習コスト | 中程度 | 低い | | 導入難度 | 低い（YAMLテンプレートあり） | 中程度（独自セクション多数） | | 60,000リポジトリの採用実績 | ✓ 採用 | ✗ Claude Lab専用 |

最終的な推奨：

新規プロジェクト → AGENTS.md から開始
既存プロジェクト → AGENTS.md を後付け + CLAUDE.md で詳細化
Claude Code 専用 → CLAUDE.md + AGENTS.md フォールバック

これにより、AIツールの進化に対応でき、かつ人間にも読みやすいドキュメントを維持できます。