「CLAUDE.mdは書いたけど、AGENTS.mdって何？同じものじゃないの？」
このQiitaに「CLAUDE.mdをチーム憲法にしたら」という記事を出してから、よく頂く質問です。私自身、最初は同じものと思っていました。しかしAGENTS.mdが2026年に入ってから採用が爆発的に伸び、agents.md規格はLinux FoundationのAgentic AI Foundation配下で管理されるオープン標準になりました。
GitHubでAGENTS.mdを含むリポジトリは6万を超え、AGENTS.md整備済みのプロジェクトではエージェント生成バグが35-55%減というベンチマーク結果も出ています。
本記事では、CLAUDE.mdとAGENTS.mdの違いを整理し、2ファイルを役割で分ける実践設計を共有します。
結論 役割が違うので分けたほうがよい
最初に結論です。
| ファイル | 主な読み手 | 1リポに何個 | 役割 |
|---|---|---|---|
| CLAUDE.md | Claude Code | 1 | Claude Code固有の設定・癖 |
| AGENTS.md | 任意のAIエージェント | 1 | プロジェクト共通のインデックス |
CLAUDE.mdはClaude Code専用です。AGENTS.mdはツール非依存のオープン標準で、Codex CLI、GitHub Copilot、Cursor、Windsurf、Amp、Devinなどが2026年時点でネイティブに対応しています。
つまり、CLAUDE.mdを書いてもCursorは読みません。AGENTS.mdを書いても（2026年5月時点では）Claude Codeはネイティブには読みません。役割が違うので、両方書くのが現実解です。
2026年5月時点でClaude CodeのAGENTS.md対応はpendingです。最新はagents.mdで確認できます。Anthropicは公式にAGENTS.mdサポート予定を表明していますが、リリース時期は未定です。
なぜ私は2ファイル運用を選んだか
「両方書くのは二重管理では？」と思うかもしれません。私もそう思っていました。しかし1ヶ月運用してみて、明確に役割を分けたほうがメンテしやすいと実感しています。
失敗例 全部CLAUDE.mdに書いた
最初の私の運用です。CLAUDE.mdに何でも書きました。
# CLAUDE.md（旧）
- ECサイトのバックエンド、FastAPI + PostgreSQL
- ディレクトリ構成: app/, tests/, scripts/...
- API追加の手順
- テスト作成のベストプラクティス
- DB移行の手順
- TypeScript strict mode
- PRはsquash merge
- Claude Codeが使うべきツール優先度
- Claude Codeでスラッシュコマンドを使うときの癖
- ...
3,000行を超えました。Claude Codeは毎回これを読みます。コンテキストを圧迫し、肝心の指示が薄まります。CursorとClaude Codeを併用したら、Cursor側で同じ情報を参照したくても、Cursorは.cursor/rules/しか見ません。
改善後 2ファイルに分けた
# AGENTS.md（プロジェクト共通、500文字以下）
## Overview
ECサイトのバックエンド。FastAPI + PostgreSQL。
## Structure
- `app/` → FastAPIアプリ
- `tests/` → テスト
- `scripts/` → 運用スクリプト
- `harness/skills/` → タスク別スキル
## Key Skills
- API追加 → harness/skills/add-api-endpoint.md
- テスト作成 → harness/skills/write-tests.md
- DB移行 → harness/skills/db-migration.md
## Constraints
- TypeScript strict mode
- テストカバレッジ80%以上必須
- PRはsquash merge
# CLAUDE.md（Claude Code固有のみ、200文字程度）
## Tools
- Read/Edit/Write優先、Bashは最後の手段
- Grep/Globでファイル検索（findは禁止）
## Slash Commands
- /testは pytest -xvs を実行
- /lintは ruff check のみ
## See Also
- プロジェクト共通指示は AGENTS.md を参照
CLAUDE.mdは「Claude Code固有の癖と道具の使い方」だけ。プロジェクト共通の情報はAGENTS.mdに集約。これでCursor/Codex/Windsurf/Devinとも共通の指示が回るようになりました。
AGENTS.mdは「インデックス」に徹する
AGENTS.mdの設計で最も重要なのは、巨大なドキュメントにしないことです。Anthropicの公式ガイドも、agents.mdの公式仕様も、口を揃えてこう言います。
「AGENTS.mdは目次。詳細はスキルファイルへ」
私の運用は次のとおりです。
プロジェクトルート/
├── AGENTS.md # 500文字以下のインデックス
├── CLAUDE.md # Claude Code固有の200文字
└── harness/skills/
├── add-api-endpoint.md # 各300-500文字
├── write-tests.md
├── db-migration.md
└── pr-template.md
AGENTS.mdに書くのは「何が、どこにあるか」だけ。詳細手順は各スキルファイルに分ける。エージェントは必要なときだけスキルファイルを読みます（lazy load）。
| ファイル | 目安サイズ | 役割 |
|---|---|---|
| AGENTS.md | 500字以下 | インデックス・憲法 |
| CLAUDE.md | 200字以下 | Claude Code固有 |
| スキルファイル | 各300-500字 | 詳細手順 |
| ルールファイル | 各200-300字 | 部分的な制約 |
サイズの上限を意識的に設けています。これを超えたら、スキルファイルへの分割を検討します。
スキルファイルの設計テンプレート
スキルファイルは「いつ・どう使うか」が明確なほうがエージェントの判断精度が上がります。私のテンプレートはこんな構造です。
# harness/skills/add-api-endpoint.md
## When to use
新しいAPIエンドポイントを追加するとき
## Steps
1. `app/routers/`に新しいルーターファイルを作成
2. Pydanticモデルを`app/schemas/`に定義
3. ビジネスロジックを`app/services/`に実装
4. テストを`tests/routers/`に作成
5. `app/main.py`にルーターを登録
## Constraints
- 1ルーターファイル = 1リソース
- レスポンスモデルは必ず定義
- エラーハンドリングはHTTPExceptionを使用
## Examples
→ app/routers/users.py を参考にすること
When to useが冒頭にあるのが大事です。エージェントは「このスキルを今読むべきか」をここで判断します。曖昧だと無駄に読み込み、コンテキストを浪費します。
CLAUDE.mdは「Claude固有の癖」を書く場所
CLAUDE.mdに残すのは、Claude Code特有の設定だけです。私が今書いている内容はこんな感じです。
# CLAUDE.md
## Tool Priority
- Read/Edit/Write優先、Bashは最後の手段
- Grep/Globでファイル検索（findは禁止）
- TodoWriteは3ステップ以上で必須
## Slash Commands
- /testは pytest -xvs を実行
- /lintは ruff check のみ
- /reviewは PR descriptionを生成
## Claude Code Quirks
- thinking blocksは長考タスクのみ使う
- 並列ツール呼び出しは独立タスクのみ
## Cross-reference
- プロジェクト共通指示は AGENTS.md を参照
200文字程度に収めています。「Claude Codeを使う私たち固有の合意事項」だけです。これ以外はAGENTS.mdとスキルファイルに置くのが原則です。
「禁止事項」は理由を添えて書く
両ファイルに共通する設計原則として、禁止事項には必ず理由を書くのが効きます。
## Forbidden
- `any`型の使用禁止
→ 型安全性を担保するため。型不明な箇所は unknown + 型ガードで対応
- console.logを本番コードに残さない
→ ログはloggerを使う。デバッグ用は必ずdev環境で削除
- 直接SQLを書かない
→ ORM(SQLAlchemy)を経由する。Raw SQLが必要なら理由をコメントで明記
理由なき禁止は人間も守りたくないですし、エージェントも未知のケースで判断を誤ります。「なぜダメか」を書くことで、エージェントがエッジケースでも正しい方向に判断できます。
「書く→使う→改善する」サイクルを回す
AGENTS.mdは一度書いて終わりではありません。私の運用サイクルはこうです。
1. AGENTS.md / スキルファイルを書く
2. エージェントに作業させる
3. 間違えた箇所を特定する
4. 間違えた原因を分析する
5. 制約をスキルファイルに追加する
6. 2に戻る
エージェントが「あれ？このプロジェクトではimportエイリアスを@/にしてるのに、相対パス使った」と間違えたら、スキルファイルに「Use @/ alias for imports, never relative paths」と一行追記します。
Louis Bouchardの言葉を借りると、「モデルがバカだ」と言うのをやめよう。「自分のシステムがこの失敗を許容した」と言おう。間違いはAGENTS.md改善のシグナルです。
ツール別の対応状況（2026年5月）
各エージェントツールのAGENTS.md対応状況をまとめます。
| ツール | AGENTS.md | 固有ファイル |
|---|---|---|
| Codex CLI | ◎ ネイティブ | - |
| GitHub Copilot | ◎ ネイティブ | .github/copilot-instructions.md |
| Cursor | ◎ ネイティブ | .cursor/rules/ |
| Windsurf | ◎ ネイティブ |
.windsurfrules（旧） |
| Amp | ◎ ネイティブ | - |
| Devin | ◎ ネイティブ | - |
| Claude Code | △ pending | CLAUDE.md |
| Gemini CLI | × | GEMINI.md |
主要ツールの大半がAGENTS.md対応済みです。Cursor/Windsurfの旧固有ファイル（.cursorrules等）はAGENTS.md対応後はオプショナル扱いに変わってきています。
私の運用方針はこうです。
## 2026年5月時点の私の方針
1. AGENTS.md を「正本」として管理（プロジェクト共通）
2. CLAUDE.md は Claude Code 固有のみ、AGENTS.md を参照
3. GEMINI.md は AGENTS.md のシンボリックリンクで運用
4. .cursor/rules/ は段階的にAGENTS.mdに統合
Claude CodeのAGENTS.md対応がリリースされたら、CLAUDE.mdは固有設定のみに縮小し、AGENTS.mdが正本として一元化される未来を見据えています。
L1チームに薦める導入手順
私が顧客に推奨する3ステップ導入プランです。チーム成熟度がL1（個人エージェント運用）であっても、1日で着手できます。
## Day 1: 棚卸し
1. 既存のCLAUDE.md / .cursorrules / READMEから「プロジェクト共通の情報」を抽出
2. AGENTS.md（500文字以下）を新規作成
3. 詳細手順は harness/skills/ 配下のファイルに分割
## Day 2: 整備
4. CLAUDE.md を Claude Code 固有のみに縮小
5. スキルファイルに「When to use」と「Constraints」を追記
## Day 3: 運用
6. エージェントに作業させ、間違いを記録
7. スキルファイルに制約を追加（最低5回サイクルを回す）
3日でAGENTS.md運用が立ち上がります。重要なのは「完璧を目指さない」こと。雑でもAGENTS.mdを置き、サイクルを回しながら改善するのが効率的です。
まとめ
CLAUDE.mdとAGENTS.mdは役割が違うので分けて書くのが2026年時点の現実解です。
- CLAUDE.md: Claude Code固有の癖、200字以下
- AGENTS.md: プロジェクト共通のインデックス、500字以下、ツール非依存
- スキルファイル: 詳細手順、各300-500字、lazy load
AGENTS.mdは6万リポジトリ以上に広がり、エージェント生成バグを35-55%削減する効果が報告されています。Claude CodeのAGENTS.md対応がリリースされたら、CLAUDE.mdの役割はさらに小さくなり、AGENTS.mdが事実上の標準になるでしょう。
あなたのプロジェクトのCLAUDE.mdは何行ありますか。3,000行を超えているなら、AGENTS.mdへの分離を今週始める価値があります。
ハーネスエンジニアリングの体系的な解説は、Zenn Book「ハーネスエンジニアリングガイド」の第11章で扱っています。L1〜L4のチーム成熟度モデルと合わせて読むと、AGENTS.md/CLAUDE.mdの役割がより明確になります。
https://zenn.dev/kenimo49/books/harness-engineering-guide
参考
- agents.md（公式仕様）（Linux Foundation Agentic AI Foundation）
- AGENTS.md Guide (2026): Copilot, Cursor & More
- CLAUDE.md, AGENTS.md & Copilot Instructions（DeployHQ）
- Keep your AGENTS.md in sync（Kaushik Gopal）
- Anthropic「Claude Code Best Practices」公式ガイド