AIコーディングエージェント向けに、リポジトリのルールを書いた指示ファイルを置く運用が広がっています。AGENTS.md（Codexなど複数のエージェントが参照する共通仕様の指示ファイル）やCLAUDE.md（Claude Codeが読む独自形式の指示ファイル）をどちらか一方にするか、両方置くか迷っている方に向けて、実データに基づく判断材料を整理します。
2026年11月2日にShanto氏らの研究チームがarXivに投稿したプレプリント（査読前論文）は、GitHubの公開データセットAIDev（エージェントが作成したプルリクエストの収集データ）から抽出した1,000リポジトリ、3,387件の指示ファイルを分析しています。AGENTS.md、CLAUDE.md、copilot-instructions.md、.cursorrulesの4形式が対象です。査読前のため数値は「最初の手がかり」として扱う必要がありますが、実運用の傾向を知るには十分な規模のデータです。
どんな場面で判断が必要になるか
新しくAIエージェントをプロジェクトに導入するとき、指示ファイルをどの形式で用意するかは最初に決めることになります。すでにCLAUDE.mdがある状態でCodexやCopilotも使い始める場合、AGENTS.mdを追加するかどうかも同じ論点です。
星の数が多い人気リポジトリほど指示ファイルを持つ比率が高く、調査では上位半分の66.2%が少なくとも1つの指示ファイルを持っていました（下位半分は50.2%）。さらに人気リポジトリの42.2%は複数形式を併用しています。つまり併用は決して珍しい運用ではなく、プロジェクトが育つにつれて直面しやすい選択だと言えます。
判断軸1: 使うエージェントがどのファイルを読むか
最初に確認すべきは、利用するエージェントごとのファイル読み込み仕様です。Claude Codeは両方のファイルが存在する場合、デフォルトではCLAUDE.mdしか読みません（CLAUDE.md内で@AGENTS.mdをインポート指定しない限り）。一方でCodexはAGENTS.mdを読みます。
この仕様差は見落とされがちですが、実務への影響は小さくありません。AGENTS.mdとCLAUDE.mdを両方置いているリポジトリは調査対象の中で231件と最多の組み合わせでしたが、両ファイルの内容が食い違っていれば、ClaudeとCodexがそれぞれ違う指示を読んで動くことになります。
判断軸2: 内容の重複をどう検知するか
調査では386組のセクション（同じ話題を扱う箇所）を比較し、32.6%が「同じ内容を別の言葉で」、51.3%が「互いを補完する内容」、16.1%が「食い違う指示」だったと報告しています。完全な矛盾はゼロでしたが、16%という数字は無視できる水準ではありません。
ここで重要なのが検知手法です。見出し単位の一致率（median overlap、中央値での重なり度合い）は0.273と低い一方、カテゴリ単位（ビルド手順、テスト方針などの分類）で見ると0.929まで上がります。これは「同じ内容なのに見出しの書き方が違う」ケースが大半であることを示しています。
単純なdiffコマンドでファイルを比較しても、見出しの表現が違うだけで差分として検出されてしまい、実質的に同じ内容を見落とすか、逆に些細な表現差を過剰に問題視してしまいます。比較はカテゴリ単位（ビルド/テスト/スタイル/構造など)で行う方が実態に近づきます。
判断軸3: 更新・保守の体制が組めるか
指示ファイルは「書いたら終わり」になりやすい傾向があります。調査対象の40.4%は記録上1回しか更新されておらず、Copilot用の指示ファイルに限ると47.7%、CLAUDE.mdでも34.4%が1回のみでした。形式を問わず編集者の中央値は1人です。
複数形式を併用すると、更新すべきファイルが増える分だけ保守コストも増えます。1人のメンテナーが片方だけ更新し、もう片方が古いまま放置されるリスクは、ファイル数が増えるほど高まると考えてよいでしょう。
判断軸4: 記載すべき項目が揃っているか
形式の選択と同じくらい重要なのが中身です。調査によると、やって良いこと・悪いことの記載（Do's and don'ts）は81.2%のファイルに存在しますが、以下の4項目は半数を大きく下回っています。
| 不足しがちな項目 | 記載率 | 書くべき内容 |
|---|---|---|
| Gitとプルリクエストの規約 | 43.8% | ブランチ命名、コミット形式、PRに必要な情報 |
| セキュリティと秘密情報 | 29.9% | 秘密情報の保管場所、出力・コミット禁止のファイル、人間の承認が要るコマンド |
| ファイル更新のタイミング | 26.6% | 更新トリガー(ビルド変更・テスト追加・規約変更)と担当者 |
| 所有者・連絡先 | 18.8% | ディレクトリ別の担当チーム、リスクの高い変更の相談先 |
特にセキュリティと秘密情報の項目は、記載率が3割未満にもかかわらず、エージェントの暴走を防ぐ実質的な防波堤になります。どの形式を選ぶにしても、この項目だけは最優先で埋めておく価値があります。
ケース別の推奨
単一エージェント（Claude Codeのみ、またはCodexのみ）で運用しているなら、使っているエージェントが読む形式を1つだけ整備すれば十分です。ファイルを増やすほど保守負担が増えるため、実際に読まれない形式を置く理由はありません。
複数エージェントを併用しているなら、AGENTS.mdを単一の真実の情報源（single source of truth）にして、CLAUDE.mdの先頭に@AGENTS.mdのインポート行を置き、その下にClaude固有の差分だけを書く構成が合理的です。これにより内容を二重管理せずに済みます。
チームでAI生成の指示ファイルをテンプレートから自動生成する場合は、生成結果をそのまま採用せず必ず人がレビューしてください。調査のテスト生成では、テンプレート導入でカテゴリ網羅率が18.7%から82.8%に上がった一方、開発者の意図を完全に保持できたセクションは19.4%にとどまっています。自動生成は出発点にはなりますが完成品にはなりません。
あえて見送るべき条件
利用エージェントが1種類で、今後も増える見込みが薄いプロジェクトでは、複数形式の併用は見送って構いません。管理対象が増えるだけで、読まれないファイルが放置されるリスクの方が大きくなります。
また、指示ファイルを更新する担当者を決められない状態での新規導入も一旦保留すべきです。調査が示す通り、多くのファイルは1回書かれて以降更新されません。更新担当を決めずに作っても同じ運命をたどる可能性が高いです。
確認すべきことと次の一歩
まず、現在使っているエージェント（Claude Code、Codex、Copilotなど）が実際にどのファイルを読むのか、各ツールの公式ドキュメントで確認してください。これが形式選択の出発点です。
複数の指示ファイルがすでに存在する場合は、diffによる行単位比較ではなく、ビルド・テスト・スタイル・構造などのカテゴリ単位で内容を突き合わせ、食い違いがないか洗い出してください。
最後に、セキュリティと秘密情報の章がファイルにあるか確認し、なければ最優先で追記してください。記載率が3割に満たない項目だからこそ、整備するだけで他プロジェクトとの差がつきます。