「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」公式ガイド

結論 役割が違うので分けたほうがよい