github-copilot-repo-instructions

github-copilot-repo-instructions

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

汎用的で、ドキュメントに忠実です。特定のエンジニアリング原則を組み込んだ独自のジェネレーターについては、/copilot の setup モード（/copilot setup）を参照してください（インストールされている場合）。

複数モードに対応した Copilot ドライバー（review／delegate／setup）については、/copilot を参照してください（インストールされている場合）。このスキルでは、指示ファイルの作成と監査のみを行います。

---

ファイル構成

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

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

---

フロントマター（パス固有のファイルのみ）

---
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 code review — PR のレビュー。リポジトリごとに切り替え可能です。フィーチャーブランチではなく、ベースブランチから読み込みます。
• Copilot coding agent（cloud agent） — Issue を起点とした実装。

パス固有のファイル（.github/instructions/*.instructions.md）は、code-review と cloud agent 向けに github.com で完全にサポートされています。IDE でのパス固有ファイルのサポートは遅れているため、IDE 対応を確実にするにはリポジトリ全体に適用されるファイルのほうが安全です。

---

優先順位

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

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

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

---

手順

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

1. mkdir -p .github
2. .github/copilot-instructions.md を作成します。Markdown のみを使用し、フロントマターは付けません。
3. 2 ページ以内に収めます。空白は無視されるため、箇条書きを積極的に使ってください。
4. 有用な内容：スタックの概要、ビルド／テストのコマンド、構成マップ、わかりにくい慣例。Copilot がすでに知っている一般的なアドバイスは省いてください。
5. ベースブランチ（通常は main）にコミットします。code review はベースから読み込みます。

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

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

Copilot code review を有効にする

リポジトリの Settings → Code & automation → Copilot → Code review → "Use custom instructions when reviewing pull requests" を切り替えます。

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

すべての 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 です。執筆時点では、ルールセットのスキーマページには記載されていませんが、エンドポイントでは受け付けられます。ターゲットの指定方法は他のルールセットと同じです。

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

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

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

リポジトリ、組織、PR ごとのすべての設定項目と、Copilot のレビューでできないこと（「変更を要求」モード、重大度のしきい値、API による再リクエストがないことを含む）については、references/code-review-knobs.md をお読みください。

Copilot がファイルを読み込んでいることを確認する

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

PR レビューを確認するには、レビューコメントのメタデータを確認するか、パス固有のファイルが対象とする glob に一致するファイルを変更する 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. git log でベースブランチを確認します。フィーチャーブランチ上の指示ファイルへの最近の変更は、マージされるまでコードレビューに反映されません。
4. 組織レベルまたは個人に適用される想定の指示との矛盾を指摘します。

---

ルール

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

---

注意点

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

---

このスキルの対象外

• セットアップウィザードではありません。助言や編集は行いますが、ユーザーへの聞き取りは行いません。
• /copilot setup（インストールされている場合）と同じものではありません。/copilot ドライバーのそのモードには、特定のスタイルが組み込まれています。
• 個人用指示ではありません。/github-copilot-personal-instructions を参照してください。
• 組織レベルの指示ではありません。これらは GitHub Enterprise の組織設定で構成され、どのリポジトリにも属しません。

---

参照元

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