AGENTS.md、Cursorのルール、Copilotの指示ファイルを重複なく管理する方法

まず、各ツールが何を読むかを確認する

分担を決める前提として、公式ドキュメントで確認できた範囲を整理します(2026年10月27日時点で閲覧した内容です)。

• Cursor:.cursor/rules に置く Project Rules は .mdc 形式で、alwaysApply・globs・description のメタデータで適用条件を決めます。プレーンな .md はメタデータがないため無視される、と書かれています。別の選択肢として AGENTS.md もあり、サブディレクトリに置くと、より具体的な(深い階層の)指示が優先されます(Cursor Rules)。
• GitHub Copilot:リポジトリ全体向けの .github/copilot-instructions.md、パス別の .github/instructions/NAME.instructions.md(applyTo に glob を書く)、エージェント向けの AGENTS.md があります。AGENTS.md は、ディレクトリツリー上で最も近いものが優先されると説明されています(リポジトリ指示の追加)。
• Claude Code:CLAUDE.md が基本で、リポジトリの AGENTS.md を代わりに読むこともできます(How Claude remembers your project)。

注意したいのは、ツールごとに優先順位の決まり方が違う点です。たとえば GitHub.com の Copilot Chat では、個人指示 > パス固有 > リポジトリ全体 > エージェント指示 > 組織指示の順とされ、機能や環境によって対応状況も変わります(Copilotのカスタム指示)。Cursor は Team Rules → Project Rules → User Rules の順です。同じ項目を複数の層に書くと、ツールごとに勝つ側が変わります。重複を避ける理由はこの点にあります。

分担表:何をどこに置くか

次の表は編集上の提案です。判断基準は「そのツール以外では意味を持たないか」です。

• ビルド・テスト・lint のコマンド、置き場(元)：AGENTS.md、他ツールでの扱い：書かない
• ディレクトリ構成、命名規則、コミット規約、置き場(元)：AGENTS.md、他ツールでの扱い：書かない
• やってはいけない操作(本番設定の変更など)、置き場(元)：AGENTS.md、他ツールでの扱い：書かない
• サブフォルダ固有の注意(例:frontend/のみ)、置き場(元)：サブフォルダの AGENTS.md、他ツールでの扱い：書かない
• 拡張子・パスで条件付きに適用する指示、置き場(元)：Cursor は .cursor/rules/*.mdc、Copilot は .github/instructions/*.instructions.md、他ツールでの扱い：適用条件の記法がツール固有なので、各ツール側に置く
• 「このルールは手動で呼んだときだけ使う」等の適用タイプ、置き場(元)：.cursor/rules/*.mdc、他ツールでの扱い：Cursor 固有
• Copilot のコードレビュー向けの観点、置き場(元)：.github/copilot-instructions.md、他ツールでの扱い：Copilot 固有に限定して短く書く
• CLAUDE.md、置き場(元)：@AGENTS.md を取り込む1行+Claude固有の補足のみ、他ツールでの扱い：本文は書かない

ポイントは2つです。

1. 本文を持つのは AGENTS.md だけにします。他のファイルは「条件(globs / applyTo)」と、その条件で追加したい差分だけを持ちます。
2. 同じ文を別の言い方で書くのも重複とみなします。コマンドや規約は、1か所にしか存在しない状態にします。

ファイルの構成例(説明用の例)

repo/
├─ AGENTS.md                         # 共通の本文
├─ CLAUDE.md                         # @AGENTS.md の取り込み+Claude固有メモ
├─ .cursor/rules/
│   └─ frontend-tsx.mdc              # *.tsx のときだけ追加する指示
└─ .github/
    ├─ copilot-instructions.md       # Copilot固有(レビュー観点など)だけ
    └─ instructions/
        └─ python-tests.instructions.md   # applyTo: "tests/**/*.py"

CLAUDE.md の中身は次のようにします。@ファイル名 による取り込みは Claude Code のメモリ機能の記法ですが、AGENTS.md と CLAUDE.md が両方ある場合にどちらが読まれるかは、お使いのバージョンの公式ページで確認してください。

@AGENTS.md

## Claude Code 固有
- 作業前に計画を提示すること

Cursor の条件付きルールは、本文を書かず差分だけにします。

---
description: TSXコンポーネントを編集するときの追加指示
globs: "**/*.tsx"
alwaysApply: false
---
- コンポーネントの共通方針は AGENTS.md に従う
- このファイルには TSX 固有の指示だけを書く

Copilot のパス別指示も同様に、applyTo に条件を書き、差分だけを置きます。

---
applyTo: "tests/**/*.py"
---
- テストの追加方針は AGENTS.md に従う
- ここには pytest 固有の補足だけを書く

食い違いを防ぐ運用ルール

構成より大事なのは、更新の入口を1つにすることです。

• 指示を変えるときは、まず AGENTS.md を直す。ツール側のファイルを先に直さない。
• ツール側のファイルに規約や手順の文を足したくなったら、「本当にそのツール固有か」を自問する。固有でなければ AGENTS.md に移す。
• ツール固有ファイルは短く保つ。Cursor は個々のルールを500行以下にするよう案内しています。長くなるほど、共通の内容が紛れ込みます。
• 機能ごとに AGENTS.md を読むかを確認する。Copilot は、使う機能(チャット、コードレビュー、エージェント)や環境で対応が異なる場合があります。読まれない機能が重要なら、その機能向けの短い要点だけを copilot-instructions.md に置き、「元は AGENTS.md」と運用表に記録します。これは意図した例外の重複です。

更新時の確認手順

指示ファイルを変更するプルリクエストごとに、次の順で確認します。

1. 変更したファイルを一覧にする(AGENTS.md、CLAUDE.md、.cursor/rules/、.github/ 配下)。
2. 変更が共通事項なら、AGENTS.md だけが変わっているか確認する。ツール側のファイルに同じ内容を足していたら削る。
3. ツール固有の変更なら、AGENTS.md の内容と矛盾する文がないか確認する。
4. 次のAI向け依頼文で、重複と矛盾の候補を洗い出す。
5. 洗い出した候補を人が判断する。AI の指摘が正しいとは限らないので、元の置き場の表に照らして残す側を決める。
6. 実際にツールで確かめる。各ツールのチャットに「このリポジトリのテスト実行コマンドは?」のように、共通事項を聞く質問を1つずつ投げ、回答が一致するか見る。指示が必ず守られる保証はない、と公式ドキュメントにも書かれているため、この確認は省かないでください。

AIに渡す監査依頼文(未実行の例)

以下のファイルを比較し、指示の重複と矛盾を洗い出してください。
- AGENTS.md
- CLAUDE.md
- .cursor/rules/*.mdc
- .github/copilot-instructions.md
- .github/instructions/*.instructions.md

ルール:
1. AGENTS.md が共通事項の元です。他のファイルに同じ意味の文があれば「重複」として報告する。
2. AGENTS.md と他ファイルで内容が食い違う場合は「矛盾」として、両方の該当行を引用する。
3. ツール固有ファイルのうち、固有性のない文は「AGENTS.mdへ移動候補」として挙げる。
4. ファイルを書き換えない。表形式(種別/ファイル/該当行/理由)で出力する。
5. 判断に迷うものは「要確認」とする。

渡す情報はリポジトリ内の指示ファイルだけにします。APIキーや社内URLが書かれている場合は、ダミー値に置き換えてから渡してください。

運用開始時に一度だけやること

既に複数のファイルが存在する場合は、全部を一度に統合せず、次の順に進めます。

1. 現状のファイルをすべて AGENTS.md に貼り、AIに「共通事項を抽出して」と依頼する。
2. 抽出結果を人が読み、分担表のどこに属するかを決める。
3. ツール側のファイルから共通部分を削り、条件と差分だけにする。
4. 上の確認手順の6を実施して、各ツールの挙動を確かめる。

ツールの仕様は更新されるため、特に Copilot の対応機能と Claude Code の読み込み条件は、運用表に「確認日」を書き、定期的に公式ページで見直すことをおすすめします。