一行でいうと
CLAUDE.mdが長くなったら、.claude/rules/に分けて必要なときだけ読ませます。Claude Code以外のツールとも約束事を1つにそろえたいときは、AGENTS.mdを使います。
なぜ必要になったのか
以前のレッスンで、CLAUDE.mdの判断基準を学びました。「この一行を消したら、Claudeは間違えるか」です。
この基準で書き足していくと、あるところで別の問題にぶつかります。プロジェクトの種類が増えるほど、CLAUDE.mdに書きたいことも増えるからです。
フロントエンドの作法、バックエンドの作法、デプロイの手順、特定のディレクトリだけの注意事項。全部を1つのファイルに集めると、CLAUDE.mdは長くなります。長くなったCLAUDE.mdは毎回全文が読み込まれるので、フロントエンドの作業をしているときにもバックエンドの注意事項が文脈に乗ります。前々回学んだContext Rotの理屈からいえば、これは信号を薄める方向の変化です。
もう1つ、別の理由で困ることがあります。チームやプロジェクトによっては、Claude Code以外のAIコーディングツールも使います。ツールごとに別の指示ファイルを書いて保守すると、片方だけ直して片方を直し忘れるということが起きます。
この2つの困りごとに、それぞれ答える仕組みがあります。ファイルを分けて条件付きで読ませる.claude/rules/と、複数のツールで1つの指示ファイルを共有する AGENTS.md です。
仕組み: .claude/rules/
.claude/rules/は、CLAUDE.mdの内容を複数のMarkdownファイルに分割して置いておく場所です。
分け方には2種類あります。何も指定しなければ、CLAUDE.mdと同じ扱いで、セッションの開始時に常に読み込まれます。ここに、フロントマターでpathsというフィールドを書くと、指定したパターンに一致するファイルをClaudeが触るときだけ、本文が文脈に入るようになります。
paths指定の有無で何が変わるか
CLAUDE.mdと同じ優先度で、セッション開始時に毎回読み込まれる。
全プロジェクト共通の約束事に向く。
指定したglobパターンに一致するファイルを、Claudeが読み書きするときだけ本文が文脈に入る。
特定の領域だけの作法に向く。
書き方は、ファイルの先頭にYAMLフロントマターを置くだけです。
---
paths:
- "src/api/**/*.ts"
---
# API開発のルール
...
pathsには、glob パターンのリストか、カンマ区切りの文字列を書きます。1つのファイルに複数パターンを並べてもかまいません。
ここで押さえておきたいのは、pathsはClaude Codeが読み取る唯一のフィールドだという点です。他に何かフィールドを足しても、エラーにはならず、ただ無視されます。フロントマターに凝った設定を書き込んでも効果はありません。
使いどころは、プロジェクトの一部にだけ効かせたい約束事です。フロントエンドのコンポーネント規約、特定のAPIディレクトリの作法、テストファイルだけの書き方といったものを、それぞれ別ファイルに切り出せます。CLAUDE.md本体には、プロジェクト全体に共通する話だけを残せます。
仕組み: AGENTS.md
AGENTS.mdは、Claude Code専用のファイルではありません。複数のAIコーディングツールが同じ形式で読めるように広まっている、指示ファイルの共通の置き場です。
Claude Codeも、これを直接読みます。ただし条件があります。
Claude Code v2.1.277以降であること。それより前のバージョンでは直接読まない
作業ディレクトリかその上位に、CLAUDE.mdやCLAUDE.local.mdが1つも無いこと。あれば既定ではCLAUDE.md側だけが読まれる
Project instructionsの選び方で挙動が変わる。既定値のclaude-md-or-agents-mdは「CLAUDE.mdが無ければAGENTS.md」という意味
/configのProject instructionsという項目には、この読み方を選ぶ選択肢があります。既定はclaude-md-or-agents-mdで、CLAUDE.mdがあればそちらだけ、無ければAGENTS.mdを読むという振り分けです。これをclaude-md-and-agents-mdに変えると、両方を読み込みます。この場合、各ディレクトリのCLAUDE.mdが先に読まれ、AGENTS.mdはそのあとに続きます。
つまり、CLAUDE.mdが既にあるプロジェクトでは、何もしなければAGENTS.mdは既定では読まれません。ここが誤解しやすいところです。
読まないときの取り込み方: @AGENTS.md
Claude CodeがAGENTS.mdを直接読まない場面は、いくつかあります。バージョンが古いとき、そしてプロジェクトに既にCLAUDE.mdがあって設定を変えていないとき。この2つがよくあるケースです。
こういうときのために、公式ドキュメントは1つの書き方を勧めています。CLAUDE.mdの中に、@AGENTS.mdというインポート行を1行足すやり方です。
@AGENTS.md
## Claude Code
src/billing/ 配下の変更はPlanモードを使う
こう書いておくと、Claudeはまず@AGENTS.mdでAGENTS.mdの中身を読み、そのあとに続く行を読みます。AGENTS.mdを、ツール共通の1つの正本として保ち続けられる書き方です。Claude Code固有の指示は、その下に別枠で足せます。
視点
1つの正本を、全員が読む
AGENTS.mdを共通の本体にして、各ツール固有の細かい指示だけをそれぞれの読み込み方式で足す。これが、複数のAIツールを併用するときに崩れにくい構成です。
よくある誤解と罠
罠1: 両方に同じことを書いて、食い違う
CLAUDE.mdとAGENTS.mdを両方持つプロジェクトで、同じ内容を両方に書いてしまうことがあります。片方だけ更新すると、そこから食い違いが始まります。
対策は、共通の約束事はAGENTS.md側に一本化し、CLAUDE.mdからは@AGENTS.mdで読み込む形にすることです。Claude Code固有の指示だけをCLAUDE.md側に残せば、二重管理そのものが起きません。
罠2: 読まれていないのに、書き続ける
.claude/rules/にファイルを増やしても、pathsの書き方を間違えていれば、狙った場面で読み込まれません。フロントマターのpaths以外のフィールド名を書いても、エラーは出ずに黙って無視されるからです。
書いた内容が本当に効いているかは、/memoryで確かめられます。ユーザー・プロジェクト両方のスコープのCLAUDE.md、CLAUDE.local.md、その他のメモリファイルの場所が一覧で出るので、狙ったファイルが認識されているかをここで確認します。書きっぱなしにせず、一度は/memoryを開いて、読まれているはずのファイルが本当にリストに載っているかを見ておくとよいです。
罠3: AGENTS.mdがあるのに、CLAUDE.mdだけ読まれ続ける
前述のとおり、CLAUDE.mdが既にあるプロジェクトでは、既定の設定のままではAGENTS.mdは読まれません。「AGENTS.mdに書いたのに反映されない」と感じたら、まず/configのProject instructionsの値を確認します。
使いどころ
CLAUDE.md単体と、分割後の運用
プロジェクトが小さいうちは、これで十分。
全部が毎回読み込まれるので、見落としが起きにくい。
領域ごとの作法を.claude/rules/のpathsで出し分け、他ツールとの共通部分はAGENTS.mdへ一本化。
必要な場面でだけ、必要な指示が文脈に乗る。
分けるタイミングの目安は、CLAUDE.mdの中に「このディレクトリのときだけ」という前置きが増えてきたときです。前置きが増えたら、その部分を.claude/rules/に切り出す合図だと考えます。
他のAIツールと一緒にプロジェクトを触るようになったら、次はAGENTS.mdを検討する番です。ツールが増えるたびに指示ファイルを増やすのではなく、共通部分を1つにまとめておくと、あとで食い違いを探す手間が減ります。
今日のまとめ
- CLAUDE.mdが長くなったら、
.claude/rules/にファイルを分け、pathsフロントマターで特定のファイルを触るときだけ読ませられる - AGENTS.mdはClaude Code専用ではなく、複数のツールが共有する指示ファイル。CLAUDE.mdが無いときに限り、Claude Codeも直接読む
- 読まれない場面では、CLAUDE.mdに
@AGENTS.mdと1行書いて取り込む。効いているかは/memoryで確認する
次は、失敗したときに戻れる仕組み、Checkpointsです。