github-copilot-repo-instructions

github-copilot-repo-instructions

リポジトリ単位の Copilot ガイダンス。.github/ 内の Markdown ファイルを GitHub Copilot がリポジトリに対する各リクエストで読み込みます。

このスキルの対象は、リポジトリ単位の指示ファイルの作成と監査のみです。個人（ユーザーごと）の Copilot 指示は対象外です。これはユーザー 1 人の github.com の Chat セッションに適用され、 リポジトリの外に置かれます。以下のファイルレイアウト表に記載されている内容を超える AGENTS.md の内容や構成については、agents-md スキルを使用してください。

---

ファイルレイアウト

ファイル	適用範囲	Frontmatter	備考
.github/copilot-instructions.md	リポジトリ全体、すべてのリクエスト	なし	単一ファイルです。2 ページ以内にしてください。
.github/instructions/<name>.instructions.md	パスの glob	必須（applyTo）	複数ファイルを使用できます。ファイル名は .instructions.md で終わる必要があります。
AGENTS.md	最も近いファイルを優先	なし	ツリー内のどこにでも配置できます。編集対象のパスに最も近いファイルが優先されます。
CLAUDE.md	リポジトリのルートのみ	なし	ルートに単一ファイルを配置します。
GEMINI.md	リポジトリのルートのみ	なし	ルートに単一ファイルを配置します。

リポジトリ全体に適用されるファイルとパス固有のファイルは、パスが一致すると組み合わされ、 両方の指示が Copilot にまとめて送信されます。

---

Frontmatter（パス固有ファイルのみ）

---
applyTo: "**/*.ts, **/*.tsx"
excludeAgent: "code-review"
---

- Prefer `interface` over `type` for object shapes.
- Use named exports.

フィールド	必須	値
applyTo	はい	Glob パターン、またはカンマ区切りの glob（*.py、src/**/*.rb、**/subdir/**/*.py）。
excludeAgent	いいえ	"code-review" または "cloud-agent" — 該当するサーフェスでこのファイルを非表示にします。

---

サーフェス

Copilot は以下のサーフェスでリポジトリの指示を読み込みます。

• Copilot Chat — github.com/copilot（リポジトリを添付した場合）と IDE のチャット。
• Copilot コードレビュー — PR のレビュー。リポジトリごとに切り替えられます。ベースブランチではなく、 PR のヘッドブランチ（変更を含むブランチ）から読み込みます。
• Copilot コーディングエージェント（クラウドエージェント） — issue 主導の実装。

パス固有ファイル（.github/instructions/*.instructions.md）は、コードレビューとクラウドエージェント向けに github.com で完全にサポートされています。IDE ではパス固有ファイルのサポートが遅れているため、 IDE を広くカバーするにはリポジトリ全体に適用されるファイルがより安全です。 Copilot コードレビューにパススコープの指示のサポートが追加された 2025-09-03 の変更については、 references/code-review-knobs.md を参照してください。

---

優先順位

複数の指示セットがある場合は、すべて統合されて Copilot に送信されます。 明示されている優先順位（高 → 低）は次のとおりです。

1. 個人の指示（ユーザーごと、github.com の Chat のみ）。
2. リポジトリの指示（このスキル）。
3. 組織の指示。

競合は自動的に解決されず、Copilot にはすべてが表示されます。品質が低下した場合は、 重複した指示を調整するのではなく、一方のセットを一時的に無効にしてください。

---

手順

リポジトリ全体に適用される指示を追加する

1. mkdir -p .github
2. .github/copilot-instructions.md を作成します。Markdown のみで、frontmatter は不要です。
3. 2 ページ以内にしてください。空白は無視されるため、箇条書きを積極的に使用してください。
4. 役立つ内容：技術スタックの概要、ビルド／テストコマンド、レイアウトマップ、 直感的でない規約。Copilot がすでに理解している一般的なアドバイスは省略してください。
5. フィーチャーブランチでコミットし、PR を作成します。コードレビューでは PR のヘッドブランチを参照するため、 その PR のレビューには新しい指示が適用されます。

パス固有の指示を追加する

1. mkdir -p .github/instructions
2. applyTo の frontmatter を含む <name>.instructions.md を作成します。
3. スコープごとに 1 ファイルを作成します（例：python.instructions.md、frontend.instructions.md）。
4. レビュー専用またはコーディングエージェント専用のガイダンスが他のサーフェスに漏れないよう、 excludeAgent を使用します。

Copilot コードレビューを有効にする

リポジトリの設定 → コードと自動化 → Copilot → コードレビュー → **「プルリクエストのレビュー時にカスタム指示を使用する」**を切り替えます。

デフォルトでは有効ですが、組織で無効にされていることがあるため、確認してください。

すべての PR で Copilot のレビューを自動的に有効にする

方法は 2 つあります。どちらかを選んでください。どちらもブランチルールセットを作成します。API を使う方法はスクリプト化できます。

UI — Settings → Rules → Rulesets → New branch ruleset。 「Branch rules」で、Automatically request Copilot code reviewを選択します。 サブ切り替えは 2 つあります。Review new pushes（プッシュのたびに再レビューします。プレミアムリクエストを消費します）と Review draft pull requests です。

API（gh）— ルールタイプは copilot_code_review です。執筆時点では、rulesets schema page に記載されていませんが、エンドポイントでは受け付けられます。対象の指定方法は他のルールセットと同じです。

gh api repos/<owner>/<repo>/rulesets -X POST --input - <<'JSON'
{
  "name": "copilot-auto-review",
  "target": "branch",
  "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~ALL"], "exclude": [] } },
  "rules": [
    {
      "type": "copilot_code_review",
      "parameters": {
        "review_on_push": false,
        "review_draft_pull_requests": false
      }
    }
  ]
}
JSON

~ALL はすべてのブランチを対象とする PR に適用されます。デフォルトブランチを対象とする PR のみに適用するには、~DEFAULT_BRANCH を使用してください。

表示されているデフォルト設定は控えめです。PR が作成されたときに一度だけレビューし、ドラフトはスキップします。 プッシュのたびに再レビューするには、review_on_push を true に変更してください。エージェント型ワークフローには便利ですが、プレミアムリクエストの枠を多く消費します。

組織には Copilot Business／Enterprise、個人リポジトリには Copilot Pro が必要です。ライセンスがなくてもルールセットはインストールされますが、レビューは実行されません。

リポジトリ／組織／PR ごとの全設定項目と、Copilot レビューでできないこと（「変更をリクエスト」モードがない、重大度のしきい値がない、API で再リクエストできない）、削除された 4000 文字の指示制限、パス別の指示のサポートについて詳しくは、references/code-review-knobs.md をお読みください。

gh api を使ってルールセットのエンドポイントに対して行うライブの変更は、リポジトリの設定を変更します。リクエストを送信する前に、レンダリングされたペイロードを提示し、ユーザーから明示的な承認を得てください。

Copilot がファイルを読み取っていることを確認する

1. github.com/copilot を開き、リポジトリを追加します。
2. Copilot Chat で質問します。
3. 回答の上部にある References リストを展開します。
4. .github/copilot-instructions.md が表示されていることを確認し、クリックして想定したバージョンか確認します。パス別ファイルは、関連するパスが言及または添付されている場合に表示されます。

PR レビューを確認するには、レビューコメントのメタデータを確認するか、パス別ファイルの対象グロブに該当するファイルを変更する PR でレビューを実行します。

---

監査チェックリスト

ユーザーが「Copilot の設定を監査して」と言った場合：

1. ls -la .github/copilot-instructions.md .github/instructions/ AGENTS.md CLAUDE.md GEMINI.md 2>/dev/null を実行します（存在しないファイルの出力は抑制します）。
2. 存在する各ファイルを読み、次の点を確認します。
   • リポジトリ全体向けのファイルが 2 ページ以内であること。
   • パス別ファイルすべてに applyTo フロントマターがあること。
   • ファイル名が .instructions.md で終わること（パス別ファイルのみ）。
   • excludeAgent の値が "code-review" または "cloud-agent" のいずれかであること。
   • リポジトリ全体向けのファイルに、本来パス別にすべき指示（例：「常に型ヒントを追加する」—これは Python 専用です）が含まれていないこと。該当する指示は切り出します。
3. 現在の指示がどのブランチにあるかを確認します。コードレビューでは PR のヘッドブランチが読み取られるため、PR 自身の指示変更がその PR に反映されます。他のブランチからの PR には、変更がベースブランチにマージされ、そのブランチがベースからマージまたはリベースされた後にのみ反映されます。
4. 組織レベルの指示や、想定される個人の指示との競合を指摘します。

---

ルール

• リポジトリ全体向けのファイルにはフロントマターを付けないでください。 GitHub は .github/copilot-instructions.md のフロントマターを文書化していません。ここに applyTo を追加しないでください。
• パス別ファイルにはフロントマターが必須です。 applyTo がない場合、ファイルは無視されます。
• どちらのファイルにもタスク固有の指示を記載しないでください（「バグ X を修正する」「リファクタリング Y を行う」など）。これらは長期的な設定であり、チケットの範囲ではありません。
• 組織の指示を重複させないでください。 組織ですでに「Conventional Commits を使う」と定めている場合、リポジトリレベルで繰り返す必要はありません。
• コードレビューではヘッドブランチが読み取られます。 PR 内の指示変更は、その PR 自身のレビューに適用されるため、マージ前にテストできます。
• シークレット、トークン、内部 URL を記載しないでください。 これらのファイルはリポジトリの一部であり、読み取りアクセス権のある人なら誰でも閲覧できます。

---

注意点

• パス固有のファイルで YAML フロントマターが不正な場合、そのファイルは警告なしで無視されます。 コミットする前にフロントマターを検証してください。
• グロブが想定どおりに一致しない場合は、**/ を先頭に付けてネストされたパスも対象にしてください（**/*.py はネストされたファイルも対象にしますが、グロブエンジンによっては *.py はルートのみを対象にすることがあります）。
• IDE が指示をキャッシュすることがあります。編集後にウィンドウを再読み込みしてください。
• AGENTS.md は再帰的に適用されます。深い階層にある AGENTS.md は、そのファイルに近いファイルについて、上位のものより優先されます。便利ですが、ユーザーが内容の統合を想定している場合は混乱を招きます。
• CLAUDE.md と GEMINI.md も、もともとは他社のファイルですが、現在は Copilot にも読み込まれます。両方を管理している場合、Copilot は3つすべてを参照します。
• 個人用の指示は、github.com のチャットでは、そのユーザーに限りリポジトリのガイダンスより優先されます。「Copilot が Alice の場合だけルールを無視し、ほかのユーザーでは問題なく動作する」といった症状が見られます。個人用の指示はユーザーごとに設定され、リポジトリの外部で管理されます。このスキルでは管理しません。
• リポジトリ全体に適用されるファイルについて、文書に記載された唯一のサイズ目安は「2ページ以下」です。これを上限としてください。長い指示は実際の質問を押しのけてしまいます。

---

このスキルの対象外

• セットアップウィザードではありません。既存ファイルの編集やアドバイスを行いますが、対話形式で一から生成するものではありません。
• 個人用の指示ではありません。これらはユーザーごとに設定され、リポジトリの外部で管理されるため、対象外です。
• 組織レベルの指示ではありません。これらは GitHub Enterprise の組織設定で構成され、リポジトリの外部にあります。
• AGENTS.md の内容作成ではありません。その場合は agents-md スキルを使用してください。このスキルでは、ファイル配置の表における AGENTS.md の位置づけのみを説明します。

---

出典

• GitHub Copilot のリポジトリカスタム指示を追加する