agents-md

agents-md

AGENTS.md のリポジトリ単位の整備：作成、測定、内容の監査、ハーネスのミラーとの照合を行います。正本は1つで、ハーネスに依存せず、フロントマターもありません。

.github/copilot-instructions.md の作成と Copilot のコードレビュー設定は、/github-copilot-repo-instructions（インストールされている場合）で行います。このスキルが確認するのは、そのファイルが AGENTS.md のミラーとして一致しているかどうかだけです。Copilot 固有の内容や applyTo のパスルールは記述しません。

個人用またはマシン全体に適用される指示ファイル（ユーザー自身の ~/.claude/CLAUDE.md、個人用の Copilot 指示など）は対象外です。このスキルが扱うのは、リポジトリにコミットされたファイルのみです。

---

AGENTS.md の整備が重要な理由

AGENTS.md は、必須フィールドのない、ベンダー中立のプレーンな Markdown 規約です（agents.md）。ハーネスごとに、適用されるファイルを読み込むタイミングは異なります。読み込まれたテキストはコンテキストを消費するため、指示は簡潔に保ち、コマンドは最新の状態にしてください。読み込まれたコンテキストを課金対象のトークン数と同一視したり、すべてのファイルが毎回読み込まれると仮定したりしないでください。

有効性を示す証拠は一様ではありません。タスクの成功率向上が保証されていることを根拠にするのではなく、エージェントの行動に役立つリポジトリのルールを残してください。読み込み動作については references/harness-matrix.md を、調査の限界については references/content-checklist.md を参照してください。

---

プロトコル

1. 指示ファイルを一覧表示する

ルートとネストされたディレクトリにあるファイルを、リポジトリ相対パスで一覧表示します。

find . -maxdepth 4 \( -name AGENTS.md -o -name CLAUDE.md -o -name CLAUDE.local.md \
  -o -name GEMINI.md -o -path '*/.github/copilot-instructions.md' -o -path '*/.cursor/rules*' \) \
  -not -path '*/node_modules/*'

各ハーネスが読み込むファイルの範囲、優先順位、上限はそれぞれ異なります。あるファイルの有無が別のファイルの有無と同じ意味だと決めつける前に、references/harness-matrix.md を読んでください。最も近いファイルが優先されるのが一般的です（agents.md の仕様、Codex、Copilot、Cursor）。ただし、Claude Code の動作条件は異なります。作業対象ファイルより上の階層に CLAUDE.md／CLAUDE.local.md がない場合にのみ AGENTS.md を読み込むか、CLAUDE.md 内で明示的に @AGENTS.md をインポートした場合に読み込みます。

2. 測定する

python3 "$AGENTS_MD_CHECK" [path/to/AGENTS.md]

読み込まれた SKILL.md のディレクトリを基準に AGENTS_MD_CHECK を解決します（scripts/agents_md_check.py）。その際、先にシンボリックリンクを解決してください。対象リポジトリ内でスキルが skills/agents-md/ にあると決めつけないでください。

バイト数、行数、見出しの一覧、近くの justfile に照らして確認した参照先の just <recipe>、リポジトリ相対パスで参照されているすべてのパス、さらに CLAUDE.md、.github/copilot-instructions.md、GEMINI.md のミラー状態を報告します。約200行を超えるファイルには、可読性に関する注意をソフト警告として表示します。また、このスクリプトは、リポジトリのルートからチェック対象ファイルのディレクトリまでにある AGENTS.md のチェーンの合計サイズも計算します。チェーンが32 KiBを超えると、ただちに失敗します。OpenAI Codex は、このチェーンをルートから順に連結します。結合サイズが project_doc_max_bytes（デフォルトで32 KiB）に達するとファイルの追加を停止するため、作業ディレクトリに最も近いファイルから読み込み対象外になります（https://developers.openai.com/codex/guides/agents-md/）。

ルートの特定とスキップ規則は Codex に準拠します。

• ルートは、チェック対象ファイルと同じディレクトリ、またはその上位にある .git を含む最も近いディレクトリです。.git がない場合、各チェーンはチェック対象ファイルだけで構成され、レポートでは「リポジトリルート」の代わりに「ファイルのディレクトリ」と表示されます。
• 各ディレクトリでは、AGENTS.override.md があればそれを使用し、なければ AGENTS.md を使用します。
• サイズはディスク上の生のバイト数で計算されるため、CRLF の改行コードもすべてカウントされます。
• ドットディレクトリ、node_modules、リンク切れのシンボリックリンク、および独自の .git を持つサブディレクトリ（ネストされたプロジェクトルート）は走査をスキップします。

終了コード：チェーンが上限を超えず、ミラーに不一致がなく、参照されているすべてのレシピとパスが存在する場合は0です。上限超過、不一致（ミラーの差異、レシピまたはパスの欠落）がある場合、またはファイルが存在しない場合は1です。

--json は次のフィールドを出力します：path、bytes、chain_bytes、chain_dir（最大のチェーンの最も深いディレクトリ。ルートからの相対パス）、root_marker（.git のルートが見つかった場合は true）、lines、byte_cap、cap_breach、near_cap、line_warn、headings、justfile、referenced_just_recipes、missing_recipes、referenced_paths、missing_paths、mirrors、diverged_mirrors、drift。

3. 内容の監査

AGENTS.md に記載されているすべてのコマンドとパスを、記憶ではなく実際のリポジトリと照合して確認します。

• バッククォートで囲まれたすべての just <recipe> が justfile に存在することを確認します。スクリプトで検査できます。FAIL missing just recipes という行が表示された場合は、スクリプトの不具合ではなく、古いコマンドとして扱います。
• バッククォートで囲まれたリポジトリ相対パスがすべて存在することを確認します。FAIL missing referenced paths についても同様に扱います。
• 品質ゲート、規約、「変更禁止」の境界が、理想論ではなく、プロジェクトの実際の CI とレビュー手順に沿っていることを確認します。
• PR とコミットのルールを明記し、暗示にとどめないようにします。

references/content-checklist.md に従って、次のアンチパターンを指摘し、削除します。 物語調の履歴、README の重複、シークレットやトークン、個人ごとの好み、実行できなくなったコマンド。

4. ミラー戦略

正規の AGENTS.md は必ず 1 つだけにします。各ミラーについて、次のようにします。

• CLAUDE.md：存在しないか、@AGENTS.md のみを記載します（Claude Code のインポート — https://code.claude.com/docs/en/memory）。内容を重複して記載しないでください。
• .github/copilot-instructions.md：存在しない（Copilot は AGENTS.md を直接読み込みます）か、簡潔な参照のみを記載します。ユーザーが Copilot 固有の内容（パスごとの applyTo ルール、コードレビューの設定）を希望する場合は、/github-copilot-repo-instructions に案内してください。このファイルをここで作成しないでください。
• GEMINI.md：存在しないか、CLAUDE.md と同じパターンで簡潔な参照のみを記載します。

チェック用スクリプトで diverged と判定されたミラーはドリフトとして報告し、参照のみの内容にまとめるか、削除することを提案します。

5. ネストされた AGENTS.md

モノレポまたは複数パッケージの構成では、独自のルールが必要な各パッケージにネストされた AGENTS.md を配置します。Codex、Claude Code、Cursor、Gemini CLI、Copilot CLI は、ネストされたファイルをすべての親ファイルとともに読み込みます。どのハーネスも、ルートファイルをネストされたファイルで置き換えることはありません。競合がある場合に限り、より近いファイルのルールが優先されます。各ハーネスの詳細については references/harness-matrix.md を参照してください。

• ネストされたファイルには、そのサブツリー固有の差分だけを記載します。独自のコマンド、境界、例外を記載してください。両方のファイルが読み込まれる際、ルートのルールをコピーするとコンテキストが重複し、内容が乖離する可能性があります。
• ルートルールに対する各例外を明記し、置き換えるルートルールも示します。VS Code は、ハーネス間で優先順位の規則が統一されていないと警告します。
• ルートからリーフまでの各チェーンを、Codex の上限である 32 KiB 未満に保ちます。Codex は最も近いファイルから順に読み込み対象から除外します。
• Claude Code は、そのディレクトリに独自の CLAUDE.md がない場合に限り、ネストされた AGENTS.md を読み込みます。

6. 削減または書き直し

必ず、現在のファイルとの差分として変更案を提示します。その後は作業を止め、AGENTS.md またはミラーを書き込む前に、明示的な承認を求めてください。差分を省略する依頼（「差分を見せなくてよい」）があっても、この手順は省略できず、承認にもなりません。提示した差分についてユーザーが承認してから書き込んでください。

git commit や git push は絶対に実行しないでください。変更は作業ツリーに残してください。コミットはユーザーが行います。

新しいファイルを作成する場合は、assets/AGENTS.md.template をひな形として使用します。編集せずにそのまま貼り付ける定型文として使ってはいけません。各セクションには、このリポジトリの実際のコマンドと境界を反映してください。

7. 検証

python3 "$AGENTS_MD_CHECK" --self-test
python3 "$AGENTS_MD_CHECK"

どちらのコマンドも終了コード 0 で終了する必要があります。監査で変更または追加したコマンドは、完了を報告する前に再実行してください。

---

ルール

• ディレクトリのスコープごとに、正規の AGENTS.md は 1 つだけにします。ミラーはそのファイルを参照するものであり、内容を重複して記載しません。
• コマンドやパスを捏造してはいけません。バッククォートで囲まれた just <recipe> と、参照されているすべてのパスが実在する必要があります。チェック用スクリプトで検証されるため、実行を省略しないでください。
• 説明文、README の重複、シークレット、個人ごとの好みを追加してはいけません。全項目については references/content-checklist.md を参照してください。
• .github/copilot-instructions.md には、短い参照以外の内容を書いてはいけません。その作成は /github-copilot-repo-instructions の担当です。
• 個人用またはマシン全体に適用される指示ファイルには手を加えないでください。
• 既存の AGENTS.md またはミラーを上書きする前に、差分を提示し、明示的な承認を得てください。差分を省略するよう求められても、それは承認ではありません。
• git commit、git push、その他の公開コマンドを実行してはいけません。変更は作業ツリーに残してください。

参考資料

• references/harness-matrix.md — どのハーネスがどのファイルを読み込むかを、優先順位、サイズ上限、引用元とともに記載しています。
• references/content-checklist.md — AGENTS.md に記載する内容と記載しない内容を示しています。ハーネスの動作に関する記述には引用元を付け、リストはこのスキルのガイダンスとして示しています。
• assets/AGENTS.md.template — セクション分けされた簡潔な開始用テンプレートです。