GitHub Copilotの設定 - パス固有カスタム指示のソースを表示

== 概要 ==
<u>.github/instructions/</u> ディレクトリは、GitHub Copilotに対してパス固有のカスタム指示を提供するための機能である。<br>
<br>
GitHub Copilotは、AIペアプログラミングツールとして、コード補完、チャット応答、コード生成を提供する。<br>
<u>.github/instructions/</u> ディレクトリ内に配置された <u>*.instructions.md</u> ファイルを使用することにより、特定のファイルパターンやディレクトリに対してコンテキスト固有のガイダンスをCopilotに伝えることができる。<br>
<br>
パス固有カスタム指示ファイルは、以下に示す特徴を持つ。<br>
* 特定のファイルパターンやディレクトリに適用される指示
* YAMLフロントマターによるglobパターン指定
* Markdown形式での自然言語記述
* 複数のIDEで統一された動作
* エージェント別の除外設定が可能
<br>
ファイルを使用することにより、以下に示すメリットが得られる。<br>
* コンテキストの最適化
*: 作業中のファイルに関連する指示のみが適用される。
* 言語別の規約管理
*: TypeScript、Python、Java等の言語別にコーディング規約を定義する。
* 領域別のガイダンス
*: フロントエンド、バックエンド、API、セキュリティ等の領域別に指示を分割する。
* チーム間の統一
*: チーム全体で同じコーディングスタイルとベストプラクティスを共有する。
<br><br>

== copilot-instructions.mdとの違い ==
GitHub Copilotには、2種類のカスタム指示ファイルが存在する。<br>
<br>
==== copilot-instructions.md ====
<u>.github/copilot-instructions.md</u> は、リポジトリ全体に適用される汎用ガイダンスである。<br>
<br>
* 配置場所
*: <u>.github/copilot-instructions.md</u>
* 適用範囲
*: リポジトリ全体
* ファイル数
*: 1ファイルのみ
* 用途
*: プロジェクト全体の共通原則、組織全体のポリシー、一般的なコーディング規約
<br>
==== パス固有カスタム指示ファイル (*.instructions.md) ====
<u>.github/instructions/*.instructions.md</u> は、特定のパスやファイルパターンに適用される指示である。<br>
<br>
* 配置場所
*: <u>.github/instructions/</u> ディレクトリ
* 適用範囲
*: YAMLフロントマターの <code>applyTo</code> プロパティで指定されたパターン
* ファイル数
*: 複数ファイルを作成可能
* 用途
*: 言語別のコーディング規約、ディレクトリ別のルール、機能別のガイダンス
<br>
下表に、2種類のカスタム指示ファイルの比較を示す。<br>
<br>
<center>
{| class="wikitable"
|+ カスタム指示ファイルの比較
! 特徴 !! copilot-instructions.md !! *.instructions.md
|-
| 配置場所 || .github/ || .github/instructions/
|-
| 適用範囲 || リポジトリ全体 || 特定のパターン
|-
| ファイル数 || 1ファイル || 複数ファイル可能
|-
| パターン指定 || 不要 || YAMLフロントマター必須
|-
| 用途 || 全体的な原則 || 言語別・領域別ルール
|}
</center>
<br>
推奨される使い分けを以下に示す。<br>
* <u>copilot-instructions.md</u>
*: プロジェクトの概要、技術スタック、ビルドコマンド、全体的なコーディング規約
* <u>*.instructions.md</u>
*: TypeScript固有のルール、フロントエンド専用の規約、APIルートの要件、セキュリティレビューガイドライン
<br><br>

== Claude Codeとの比較 ==
<center>
{| class="wikitable"
|+ GitHub Copilot パス固有カスタム指示 と Claude Codeの比較
! 項目 !! GitHub Copilot !! Claude Code
|-
| ファイル名 || <u>*.instructions.md</u> || <u>*.md</u> (ネスト配置も可)
|-
| 配置場所 || <u>.github/instructions/</u> || <u>.claude/rules/</u>
|-
| 適用範囲の指定方法 || <u>applyTo</u> プロパティでglobパターン指定 || ディレクトリ階層による暗黙的適用<br>(そのディレクトリ以下に適用)
|-
| globパターン対応 || 対応<br>例: <u>**/*.ts</u>, <u>src/**/*.py</u> || 非対応
|-
| 複数ファイルの作成 || 可能 (用途別に複数ファイル) || ディレクトリごとに1ファイル
|-
| フロントマター || YAML形式で設定<br><code>applyTo</code>, <code>excludeAgent</code> || なし
|-
| エージェント除外設定 || <code>excludeAgent</code> プロパティで指定可能 || 非対応
|-
| 継承・マージ || 親ディレクトリの指示と併用 || 親ディレクトリのCLAUDE.mdと自動マージ
|-
| 対応環境 || 
* VS Code
* Visual Studio
* JetBrains
* GitHub.com
| 
* Claude Code
* 各種IDE拡張
|}
</center>
<br><br>

== ファイルの配置 ==
ファイルは、<u>.github/instructions/</u> ディレクトリに配置する。<br>
<br>
* 配置場所
*: <u>.github/instructions/</u>
* ファイル命名規則
*: <u>*.instructions.md</u> 形式
*: 例: <u>frontend.instructions.md</u>、<u>backend.instructions.md</u>
* ファイル形式
*: Markdown形式
* 記述言語
*: 自然言語 (英語推奨)
<br>
ディレクトリ構成の例を以下に示す。<br>
 project/
 ├── .github/
 │   ├── copilot-instructions.md       # 全体的な指示
 │   └── instructions/                 # パス固有カスタム指示ディレクトリ
 │       ├── frontend.instructions.md  # フロントエンド向け
 │       ├── backend.instructions.md   # バックエンド向け
 │       ├── api.instructions.md       # APIルート向け
 │       └── security.instructions.md  # セキュリティレビュー向け
 ├── src/
 │   ├── frontend/
 │   ├── backend/
 │   └── api/
 └── README.md
<br>
複数のファイルを作成することにより、以下に示すメリットが得られる。<br>
* ルールの明確化
*: 各ディレクトリやファイルタイプに適用されるルールが明確になる。
* メンテナンス性の向上
*: 指示の修正が容易になる。
* コンテキストの最適化
*: 作業中のファイルに関連する指示のみが適用される。
<br><br>

== YAMLフロントマターの設定 ==
ファイルには、YAMLフロントマターによる設定が必須である。<br>
<br>
==== 基本的な構造 ====
YAMLフロントマターは、ファイルの先頭に <code>---</code> で区切られた形式で記載する。<br>
<br>
基本的な構造を以下に示す。<br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "globパターン"
 excludeAgent: "エージェント名"
 ---
 
 # 指示の内容
 
 指示の詳細をMarkdown形式で記述する。
 </syntaxhighlight>
<br>
==== applyToプロパティ ====
<code>applyTo</code> プロパティは、指示が適用されるファイルまたはディレクトリをglobシンタックスで指定する。<br>
<br>
基本的なglobパターンの例を以下に示す。<br>
* <u>*.py</u>
*: カレントディレクトリのみのPythonファイル
* <u>**/*.py</u>
*: 全てのPythonファイル (再帰的)
* <u>src/**/*.py</u>
*: <u>src/</u> 以下のすべてのPythonファイル
* <u>**/subdir/**/*.py</u>
*: あらゆる深さの <u>subdir/</u> 以下のファイル
<br>
複数パターンの指定例を以下に示す。<br>
<br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.ts,**/*.tsx"
 ---
 </syntaxhighlight>
<br>
==== excludeAgentプロパティ ====
<code>excludeAgent</code> プロパティは、特定のエージェントが指示を使用するのを防ぐ。<br>
<br>
有効な値を以下に示す。<br>
* <code>code-review</code>
*: Copilot Code Reviewエージェントを除外する。
* <code>coding-agent</code>
*: Copilot Coding Agentを除外する。
<br>
省略した場合、両方のエージェントが指示にアクセスできる。<br>
<br>
Code Reviewエージェントのみを除外する例を以下に示す。<br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.ts,**/*.tsx"
 excludeAgent: "code-review"
 ---
 </syntaxhighlight>
<br>
Coding Agentのみを除外する例を以下に示す。<br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.ts,**/*.py,**/*.java"
 excludeAgent: "coding-agent"
 ---
 </syntaxhighlight>
<br><br>

== 対応環境 ==
パス固有カスタム指示ファイルは、複数のIDEとプラットフォームで対応している。<br>
対応環境を以下に示す。<br>
<br>
==== VS Code ====
VS Codeでは、完全に対応している。<br>
<br>
* 設定方法
*: <code>github.copilot.chat.codeGeneration.useInstructionFiles</code> を有効化する。
* 適用範囲
*: ワークスペース内の全てのチャットリクエストに自動適用される。
* パス固有カスタム指示
*: 対応している。
<br>
==== Visual Studio ====
Visual Studioでは、完全に対応している。<br>
<br>
* 設定方法
*: リポジトリの <u>.github/instructions/</u> ディレクトリを自動検出
* 適用範囲
*: 全てのチャットリクエストに自動適用
* パス固有カスタム指示
*: 対応している。
<br>
==== JetBrains IDE ====
JetBrains IDE (IntelliJ IDEA, PyCharm, WebStorm等) では、部分的に対応している。<br>
<br>
* 設定方法
*: リポジトリの <u>.github/copilot-instructions.md</u> のみを自動検出する。
* 適用範囲
*: 全てのチャットリクエストに自動適用される。
* 制限事項
*: パス固有の複数ファイル (<u>.github/instructions/*.instructions.md</u>) には未対応
<br>
==== GitHub.com ====
GitHub.comのWebインターフェースでは、完全に対応している。<br>
<br>
* 対応ファイル
** <u>.github/copilot-instructions.md</u>
** <u>.github/instructions/</u> ディレクトリ内の複数ファイル
* 適用範囲
*: 全てのチャットリクエストに自動適用される。
* パス固有カスタム指示
*: 対応している。
<br>
==== GitHub Copilot CLI ====
Copilot Code Reviewでは、パス固有カスタム指示ファイルを使用できる。<br>
<br>
* 対応ファイル
*: <u>.github/instructions/*.instructions.md</u>
* <code>excludeAgent</code> プロパティ
*: <code>code-review</code> を指定することにより、Code Reviewエージェントから除外可能
<br><br>

== 記述例 ==
==== フロントエンド用指示ファイル ====
TypeScriptとReactを使用するフロントエンド向けの指示ファイルの例を以下に示す。<br>
<br>
ファイル名: <u>.github/instructions/frontend.instructions.md</u><br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.ts,**/*.tsx"
 ---
 
 # フロントエンドコーディング規約
 
 ## ファイル構成
 
 - コンポーネント毎のディレクトリ構成を使用する
 - ファイル名はPascalCaseとする (例: UserProfile.tsx)
 
 ## ネーミング規則
 
 - Reactコンポーネント: PascalCase
 - 関数・変数: camelCase
 - 定数: UPPER_SNAKE_CASE
 
 ## コードスタイル
 
 - インデント: 2スペース
 - セミコロン: 必須
 - 引用符: ダブルクォート推奨
 - 関数は50行以内に抑える
 - 最大行長: 100文字
 
 ## React規約
 
 - 関数コンポーネントのみを使用する
 - Propsには必ずTypeScript型定義を記述する
 - useEffectの依存配列を必ず記述する
 - カスタムフックはuseで始まる名前にする
 </syntaxhighlight>
<br>
==== バックエンド用指示ファイル ====
Pythonを使用するバックエンド向けの指示ファイルの例を以下に示す。<br>
<br>
ファイル名: <u>.github/instructions/backend.instructions.md</u><br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.py"
 ---
 
 # バックエンドコーディング規約
 
 ## ファイル構成
 
 - モジュール毎のディレクトリ構成を使用する
 - ファイル名はsnake_caseとする (例: user_service.py)
 
 ## ネーミング規則
 
 - クラス名: PascalCase
 - 関数・変数: snake_case
 - 定数: UPPER_SNAKE_CASE
 - プライベートメソッド: _で始まる名前
 
 ## コードスタイル
 
 - PEP 8に準拠する
 - インデント: 4スペース
 - 最大行長: 88文字 (Black準拠)
 - docstringは必須
 
 ## エラーハンドリング
 
 - 全てのAPI関数はtry-exceptブロックを使用する
 - カスタム例外クラスを定義する
 - エラーログは適切なレベルで記録する
 
 ## データベース
 
 - SQLインジェクション対策としてプリペアドステートメントを使用する
 - トランザクションは明示的に管理する
 </syntaxhighlight>
<br>
==== APIルート用指示ファイル ====
APIルート向けの指示ファイルの例を以下に示す。<br>
<br>
ファイル名: <u>.github/instructions/api.instructions.md</u><br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "src/api/**"
 ---
 
 # APIルート規約
 
 ## エンドポイント設計
 
 - RESTful APIの原則に従う
 - エンドポイントはリソース名を複数形で表現する (例: /users, /products)
 - HTTP動詞を正しく使用する (GET, POST, PUT, DELETE)
 
 ## バリデーション
 
 - 全てのエンドポイントで入力バリデーションを実施する
 - リクエストボディのスキーマを定義する
 - バリデーションエラーは400 Bad Requestで返す
 
 ## レスポンス形式
 
 - 一貫したエラーレスポンス形式を使用する
 - HTTPステータスコードを正しく使用する
 - JSON形式で返す
 
 ## ドキュメント
 
 - 全てのエンドポイントにOpenAPIコメントを記述する
 - リクエスト・レスポンスの例を含める
 </syntaxhighlight>
<br>
==== セキュリティレビュー用指示ファイル ====
セキュリティレビュー向けの指示ファイルの例を以下に示す。<br>
<br>
ファイル名: <u>.github/instructions/security.instructions.md</u><br>
 <syntaxhighlight lang="md">
 ---
 applyTo: "**/*.ts,**/*.py,**/*.java"
 excludeAgent: "coding-agent"
 ---
 
 # セキュリティレビューガイドライン
 
 ## 認証・認可
 
 - JWT、OAuth2等の標準認証方式を使用する
 - パスワードはハッシュ化して保存する (bcrypt、Argon2等)
 - アクセストークンの有効期限を設定する
 - リフレッシュトークンを適切に管理する
 
 ## データ保護
 
 - 機密情報はログに記録しない
 - 外部通信はHTTPS必須
 - SQLインジェクション対策を行う (プリペアドステートメント)
 - XSS対策を行う (入力のサニタイズ)
 - CSRF対策を行う (CSRFトークン)
 
 ## 入力検証
 
 - 全てのユーザ入力を検証する
 - ホワイトリスト方式で検証する
 - ファイルアップロードは拡張子とMIMEタイプを検証する
 
 ## アクセス制御
 
 - 最小権限の原則を適用する
 - ロールベースアクセス制御 (RBAC) を使用する
 - センシティブな操作はログに記録する
 </syntaxhighlight>
<br><br>

== 指示ファイルの分割戦略 ==
ファイルを効果的に分割するための戦略を以下に示す。<br>
<br>
==== 言語別分割 ====
プログラミング言語別に指示ファイルを分割する方法である。<br>
<br>
* <u>frontend.instructions.md</u>
*: TypeScript、TSXファイル向け
* <u>backend.instructions.md</u>
*: Python、Javaファイル向け
* <u>sql.instructions.md</u>
*: SQLファイル向け
<br>
言語別分割のメリットを以下に示す。<br>
* 言語固有のコーディング規約を明確に定義
* 各言語のベストプラクティスを反映
* チームメンバーが言語別にルールを理解しやすい
<br>
==== ディレクトリ別分割 ====
ディレクトリ構造に基づいて指示ファイルを分割する方法である。<br>
<br>
* <u>api.instructions.md</u>
*: <u>src/api/**</u> ディレクトリ向け
* <u>utils.instructions.md</u>
*: <u>src/utils/**</u> ディレクトリ向け
* <u>components.instructions.md</u>
*: <u>src/components/**</u> ディレクトリ向け
<br>
ディレクトリ別分割のメリットを以下に示す。<br>
* ディレクトリの役割に応じたルールを定義
* コードの配置場所とルールの対応が明確
* ディレクトリ構造の変更に柔軟に対応
<br>
==== 機能別分割 ====
機能やドメイン別に指示ファイルを分割する方法である。<br>
<br>
* <u>database.instructions.md</u>
*: データベース関連のコード向け
* <u>auth.instructions.md</u>
*: 認証・認可関連のコード向け
* <u>testing.instructions.md</u>
*: テストファイル向け
<br>
機能別分割のメリットを以下に示す。<br>
* ドメイン知識とルールの対応が明確
* 機能横断的なベストプラクティスを共有
* セキュリティやパフォーマンス等の非機能要件を明確化
<br>
==== エージェント別分割 ====
GitHub CopilotのエージェントごとにCoding AgentとCode Reviewエージェントで異なる指示を定義する方法である。<br>
<br>
* Coding Agent専用
*: <code>excludeAgent: "code-review"</code> を指定
*: コード生成時のルールを定義
* Code Review専用
*: <code>excludeAgent: "coding-agent"</code> を指定
*: コードレビュー時のチェック項目を定義
<br>
エージェント別分割のメリットを以下に示す。<br>
* コード生成とレビューで異なる視点を提供
* レビュー時のチェック項目を明確化
* コード生成時の自動適用ルールとレビュー基準を分離
<br><br>

== 記述のベストプラクティス ==
効果的なパス固有カスタム指示ファイルを作成するためのベストプラクティスを以下に示す。<br>
<br>
==== 簡潔性を保つ ====
焦点を絞った短い指示で最も効果的である。<br>
<br>
* 重要な情報のみを記載
*: 詳細すぎる指示は逆効果
* 1ファイルあたり1ページ以内
*: 長すぎる指示は分割する
<br>
==== 構造化された記述 ====
見出し、箇条書き、明確な構造でコンテンツを整理する。<br>
<br>
* Markdownの見出しを使用
*: セクションを明確に分割
* 箇条書きでポイントを整理
*: 読みやすさを向上
<br>
==== 指示型言語を使用 ====
直接的で命令的な言語を使用する。<br>
<br>
良い例を以下に示す。<br>
* <u>全ての新規コードにTypeScriptを使用すること</u>
* <u>全ての関数にJSDocコメントを記述すること</u>
* <u>継承よりコンポジションを優先すること</u>
<br>
悪い例を以下に示す。<br>
* <u>TypeScriptを使用するのが好ましい</u>
* <u>コメントの追加を検討すること</u>
* <u>継承は最良の選択肢ではないかもしれない</u>
<br>
==== コード例を含める ====
概念をコード例で実証する。<br>
<br>
コード例の記述例を以下に示す。<br>
 <syntaxhighlight lang="md">
 # 関数の命名規則
 
 関数名はcamelCaseを使用する。
 
 ## 良い例
 
 ```typescript
 function getUserById(id: string): User {
    // 実装
 }
 ```
 
 ## 悪い例
 
 ```typescript
 function GetUserById(id: string): User {
    // 実装
 }
 ```
 </syntaxhighlight>
<br><br>

== 避けるべき内容 ==
ファイルに記述すべきでない内容を以下に示す。<br>
<br>
* UI / UXの変更要求
*: GitHub CopilotはUIを変更できない
* プルリクエスト概要コメントの変更要求
*: PRの形式は別の設定で管理
* コードレビュー範囲外の機能実装要求
*: Code Reviewエージェントは機能を実装しない
* 外部リンクの参照
*: 外部リンクはアクセスできない可能性がある
* 曖昧な改善要求
*: <code>より正確に</code>、<code>もっと良く</code> などの曖昧な表現
<br>
具体的な悪い例を以下に示す。<br>
 <syntaxhighlight lang="md">
 # 悪い例
 
 - より正確にコードを書くこと
 - UIを改善すること
 - PRのコメントをもっと詳しく書くこと
 - https://example.com/docs を参照すること
 </syntaxhighlight>
<br>
具体的な良い例を以下に示す。<br>
 <syntaxhighlight lang="md">
 # 良い例
 
 - 関数は50行以内に抑える
 - 変数名はcamelCaseを使用する
 - 全ての公開APIにJSDocコメントを記述する
 - エラーハンドリングにはtry-catchブロックを使用する
 </syntaxhighlight>
<br><br>

== 関連項目 ==
* [[GitHub Copilotの設定 - カスタム指示]]
*: リポジトリ全体に適用される汎用ガイダンス
* [[GitHub Copilotの設定 - AGENTS.md]]
*: ベンダー中立の指示ファイル形式
* [[GitHub Copilotの設定 - サブエージェント]]
*: カスタムエージェントの作成方法
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,GitHub,Copilot,instructions,Path-specific,Custom Instructions,AI,Configuration,Settings,Programming,Development,SUSE,Linux
|description={{PAGENAME}} - GitHub Copilotの.github/instructions/ディレクトリとパス固有カスタム指示ファイルに関する包括的なガイド
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:設定]]