Claude Code、Codex、Cursorを同じプロジェクトで使い分けていると、ツールごとに違うルールファイルを開き、同じ内容を書き直したり、「このツールではここを読んで」と説明したりする場面が出てきます。保存済みの字幕で確認できた範囲では、Cursorは当初.mdcというファイルでルールを持ち、CodexはAGENTS.md、Claude CodeはCLAUDE.mdと、ファイルが分かれていた経緯が語られています。Claude CodeがAGENTS.mdを読めるようになったことで、共通のルールを1か所にまとめる選択肢が現実味を帯びてきました。
とはいえ、AGENTS.mdを一つのファイルに何でも書けばよいわけではありません。字幕では、AIの失敗のたびに追記を続けるとファイルが大きくなり、かえって性能が落ちると言われていることが紹介されています。なお、Cursorの公式ドキュメントではルールを500行未満に保つことがベストプラクティスとされ、Claude Codeの開発元の公式ドキュメントにある先頭200行または25KBという上限は自動メモリ機能のMEMORY.mdに適用されるもので、CLAUDE.mdやAGENTS.md一般の上限ではない点も押さえておきます。本記事では、置き場所の決め方、書く項目と書かない項目、増えすぎたときの目次化、Claude Codeで読み込ませるまでの手順を、確認できた字幕の範囲をもとに整理します。
AGENTS.mdは、なぜ今さら話題になるのか
Cursorの.mdcから始まったルールファイル
保存済み字幕で確認できた範囲では、話し手は2023年頃からCursorを使い始め、その動きを調整するために「ルール」という考え方が生まれたと説明しています。当初は.mdcという専用のファイルにルールを書く必要がありました。ここが、ツールごとにルールの書き方が分かれる出発点です。
Claude CodeはCLAUDE.md、CodexはAGENTS.mdだった
その後にCodexやClaude Codeが加わり、別々のファイルを持つ状態が続きます。字幕では、Codexは以前からAGENTS.mdの一択、Claude CodeはCLAUDE.md、Cursorは.mdcという形で、同じ目的のルールが別々の名前で管理されていたと語られています。ツールを切り替えるたびに、同じ内容を書き直す手間が生じていました。
| ツール | 当初のルールファイル | 保存済み字幕で語られた現在の扱い |
|---|---|---|
| Cursor | .mdc | AGENTS.mdとCLAUDE.mdも読み込めるようになり、公式ドキュメントではこの2つが案内されていると紹介 |
| Codex | AGENTS.md | 以前からAGENTS.mdを使う形で、大きな変更はないと説明 |
| Claude Code | CLAUDE.md | AGENTS.mdに対応。ただしCLAUDE.mdまたはCLAUDE.local.mdがある場合は、AGENTS.mdを既定では読まないと説明 |
同じファイルを複数ツールが読む状態で何が変わるか
CursorとCodexはAGENTS.mdを読み、Claude CodeもAGENTS.mdに対応しました。ただし、Claude CodeがAGENTS.mdを既定で読むのは、公式ドキュメントに記載のとおり、CLAUDE.mdとCLAUDE.local.mdが存在しない場合です（設定で読み込むよう構成した場合を除く）。字幕では、これまでシンボリックリンクや「ここを読んで」という指示でしのいでいた設定が要らなくなると説明されています。ただし置き場所と優先順位には注意が必要で、細かい対応条件は執筆時点の各ツールの公式ドキュメントで確認してください。
置き場所は、ルートか、フォルダか
保存済み字幕で確認できた範囲では、AGENTS.mdはプロジェクトの一番上に置くのが基本で、そこに書いたルールは配下のフォルダ全体に適用されると説明されています。まず全体の共通ルールを最上位に置き、必要な範囲だけを絞る順で考えると整理しやすくなります。
プロジェクトの一番上に置く場合
複数のツールを同じプロジェクトで使うなら、最上位のAGENTS.mdが共通の入口になります。字幕では、以前はCLAUDE.mdも同じ場所に別途置く必要があったものが、AGENTS.md1本で済むようになったと語られています。リポジトリ全体の方針や禁止操作はここに書きます。
| 置き場所 | 適用される範囲 | 内容の例 |
|---|---|---|
| プロジェクト直下 | 配下のフォルダ全体 | コミット前のテスト実行、.envを読まない |
| marketing/ の中 | marketing/ とその配下 | 記事の文体、公開前の確認項目 |
| src/ の中 | src/ とその配下 | 命名規則、設定ファイルの扱い |
サブフォルダに置いて適用範囲を絞る場合
全体に同じルールを当てると、別の仕事のファイルまで縛ってしまいます。字幕では、マーケティングの作業をするときだけルールを適用したい場合、そのフォルダの中にAGENTS.mdを置く方法が紹介されていました。上位と下位のファイルが両方あるときの優先関係は、ツールごとに公式ドキュメントで確認します。
既存のCLAUDE.mdがあるときの注意
/initで作られるファイルとの関係
Claude Codeは、何もない状態で/initを実行するとCLAUDE.mdを作ります。字幕では、CLAUDE.mdとAGENTS.mdが両方あるとCLAUDE.mdが読まれ、AGENTS.mdは読まれないと説明されていました。既存のCLAUDE.mdを残したままでは、共通ルールとして使われない可能性があります。
名前を変えて読み込ませる手順
字幕で紹介されていたのは、/initで作ったCLAUDE.mdの名前をAGENTS.mdへ変える方法です。変更後にClaude Codeを起動し直し、AGENTS.mdを読み込んだ旨の表示が出るかを確かめます。読み込み条件は変わる可能性があるため、作業時点の公式ドキュメントも確認してください。
書くことと、書かないこと
AGENTS.mdは、書けば書くほど賢くなるわけではありません。保存済み字幕で確認できた範囲では、AIの失敗のたびに追記を重ねるとファイルが肥大化し、かえって性能が劣化すると説明されています。何を書き、何を書かないかを先に決めておくことが、ルールを長持ちさせます。
触ってよい場所・触ってはいけない場所
まず書くのは、AIに触らせてよい範囲と、触らせたくない範囲です。字幕では、作業対象のフォルダと、AIの成果物を置く専用フォルダを分ける例が紹介されていました。人間が書いたものを残す場所と、AIが出力してよい場所を分けると、混ざったときに原因を追いやすくなります。
禁止する操作と、作業の終わりに確かめること
次は、やってほしくない操作と、作業の終わりに確かめることです。字幕の例では、ノートの移動にmvコマンドではなくアプリのCLIを使うよう指示していました。タイトル変更でリンクが壊れるのを防ぐためです。テストの実行や差分の確認など、終わりに確かめる項目も並べておきます。
フォルダ特有の落とし穴
三つ目は、そのフォルダ特有の落とし穴です。字幕では、ノートの移動やタイトル変更でリンクが壊れやすいこと、AIの出力が人間用の領域に流れ込むとノイズになることが挙げられていました。一般論より、この場所で実際に起きた失敗を短く書くほうが役立ちます。
書かなくてよい情報
フォルダ構成そのもの
フォルダの一覧は書かなくてよいと説明されています。AIエージェントは自分で見れば分かるからです。話し手も以前は書いていたが、不要になったと振り返っていました。
長い説明と、よく変わる情報
長い説明や、よく変わる情報も同じです。行数の目安として、字幕ではCursorの公式ドキュメントが500行未満、Codexは目次のように書くことが挙げられていました。Claude Codeの開発元の公式ドキュメントにある先頭200行または25KBという上限は自動メモリ機能のMEMORY.mdに適用されるもので、CLAUDE.mdやAGENTS.md一般の上限ではありません。いずれも案内で、絶対の基準ではありません。話し手のファイルは50行ほどだったと語られています。
| 項目 | 書く・書かない | 理由 |
|---|---|---|
| 触ってよい場所・触ってはいけない場所 | 書く | AIが作業範囲を判断できず、人間の領域まで書き換えるため |
| 禁止する操作 | 書く | ノート移動でリンクが壊れるなど、後から戻しにくいため |
| 作業の終わりに確かめること | 書く | テスト実行や差分確認を、AIの自己判断に任せきりにしないため |
| フォルダ特有の落とし穴 | 書く | 一般論では防げない失敗が、その場所で起きるため |
| フォルダ構成の一覧 | 書かない | AIが自分で見て把握できるため |
| 長い説明・よく変わる情報 | 書かない | 行数が増えて性能が落ち、内容も古くなりやすいため |
増えすぎたAGENTS.mdを、目次として使う
AGENTS.mdが行数の目安に近づいてきたら、内容を削るより先に、置き場所を分ける方法があります。保存済み字幕で確認できた範囲では、CodexはAGENTS.mdを目次のように書き、詳しい内容は別ファイルへ案内する形が大事だと説明されていました。
見出しと参照先だけを残す
目次に切り替えるときは、よく使う結論だけをAGENTS.mdに残し、長い手順や背景は別ファイルへ移します。字幕では、話し手のファイルが50行ほどで、「デザイン基盤はここを見てください」「スキルはここを見てね」といった参照の行を並べていると紹介されていました。見出しの下に、移した先のファイル名を1行で添える形です。
- AGENTS.md：見出しと参照先だけを置く
- conduct.md：行動ルールの詳細
- design.md：デザインの基準
- skills.md：スキルの一覧
参照先の名前は、開いた人がそのまま辿れるものにします。曖昧だと、AIも人も結局探し直すことになります。
詳細ファイルとの分け方
分ける単位は、話題ごとが扱いやすいです。行動ルール、デザインの基準、使うスキルの一覧のように、読む場面や更新する頻度が違うものを別ファイルにします。よく変わる情報をAGENTS.mdの外へ出しておけば、目次側を触らずに更新できます。
ただし、参照先のファイルを各ツールが自動で読み込むかどうかは、保存済み字幕では確認できませんでした。運用を始める前に公式ドキュメントで確かめ、必要ならAGENTS.mdに「このファイルを読む」と明記します。
作りながら育てるための運用
AGENTS.mdは、一度作って終わりではありません。同じ失敗に追記を重ねてファイルが長くなったなら、増やし方と見直すタイミングを決め直す出番です。保存済み字幕で確認できた範囲では、話し手は最低限のルールで始め、必要が生じたら足していく形がよいと話していました。
失敗のたびに追記すると、なぜ増えるのか
AIが同じ失敗をしたとき、その場でAGENTS.mdに一行足すのは自然な反応です。ただし字幕では、失敗のたびに追記を繰り返すとファイルが肥大化し、かえって性能が劣化するといわれていると紹介されていました。一度きりの取りこぼしまで規則にすると、例外や補足が積み上がり、本当に守ってほしいルールが埋もれます。
- 同じ失敗が繰り返しているか、一度きりかを見分ける
- 既存のルールで防げた失敗か、抜けている観点かを確かめる
- 追記するなら、似た行を増やさず既存の項目へ統合する
点検のタイミングを決める
増え続けないように、点検する日を先に決めておきます。たとえば、作業の大きな区切り、月に一度の振り返り、新しいフォルダを追加したときです。点検では、使われていない行、重複した指示、古くなった手順を探し、必要なら別ファイルへ移します。
- 作成：最低限のルールで始める
- 運用：失敗と判断を記録する
- 点検：重複と古い記述を探す
- 整理：統合・削除・別ファイルへ移動
点検のたびに全部を書き直す必要はありません。最初から完璧を目指さず、必要になったルールを足していく形で十分です。追記した日と見直した日を残しておくと、次に触るときの判断がしやすくなります。
