チュートリアル - カスタムインストラクションの書き方例

Last updated at 2025-12-25Posted at 2025-12-24

チュートリアル - カスタムインストラクションの書き方例

1. はじめに

GitHub Copilotのコードレビュー機能に、カスタム指示を設定できることをご存じでしょうか。この機能を活用すると、チーム固有のコーディング規約やセキュリティ基準に沿った、より実用的なレビューコメントを自動生成できます。本記事では、GitHubの公式ドキュメントをもとに、効果的なカスタム指示の書き方を解説します。

2. なぜカスタム指示が必要なのか

コードレビューの品質は、レビュアーの知識と経験に大きく依存します。GitHub Copilotは優れたレビュー能力を持っていますが、デフォルトの状態では以下のような課題があります。

チーム固有の命名規則やアーキテクチャパターンを考慮できない
プロジェクト特有のセキュリティ要件を把握していない
使用している言語やフレームワークのベストプラクティスが汎用的

カスタム指示を設定することで、これらの課題を解決し、Copilotをチーム専用のコードレビューアシスタントとして機能させることができます。

3. Copilotが指示を処理する仕組み

カスタム指示を効果的に書くには、Copilotがどのように指示を処理するかを理解することが重要です。

ただし、AIシステムである以上、以下の特性を理解しておく必要があります。

非決定的動作: すべての指示が毎回完璧に守られるわけではない
コンテキスト制限: 指示ファイルが長すぎると、一部が見落とされる可能性がある
明確性の重要性: 具体的な指示ほど正確に処理される

これらを踏まえて、現実的な期待値を持ちながら指示を設計することが成功の鍵です。

4. 効果的なカスタム指示の書き方

4.1. 原則1: 簡潔さを保つ

指示ファイルは最大1,000行程度に抑えることを推奨します。これを超えると、Copilotの応答品質が低下する可能性があります。

最初は10〜20個の重要な指示から始め、実際の効果を確認しながら段階的に追加していくアプローチが有効です。

4.2. 原則2: 構造化とフォーマットを工夫する

Copilotは構造化された指示を効率的に処理します。以下のフォーマットを推奨します。

推奨されないパターン:

コードをレビューするときは、開発者がパスワードやAPIキーなどの
機密情報を誤って残している可能性がないか確認し、セキュリティ
上の問題もチェックしてください。

推奨パターン:

## セキュリティクリティカルな問題

- ハードコードされたシークレット、APIキー、認証情報をチェック
- SQLインジェクションとXSS脆弱性を確認
- 適切な入力検証とサニタイゼーションを検証

見出し、箇条書き、短い命令形を使うことで、Copilotが指示を正確に理解しやすくなります。

4.3. 原則3: 具体例を示す

抽象的な説明よりも、コード例を含めた方が効果的です。

## 命名規則

意図が明確に伝わる、説明的な名前を使用してください。

```javascript
// 避けるべきパターン
const d = new Date();
const x = users.filter(u => u.active);

// 推奨パターン
const currentDate = new Date();
const activeUsers = users.filter(user => user.isActive);
` ``

このように「良い例」と「悪い例」を両方示すことで、Copilotが期待される動作を理解しやすくなります。

5. 指示ファイルの構成戦略

Copilotは2種類の指示ファイルをサポートしています。

5.1. リポジトリ全体の指示: copilot-instructions.md

全ファイルに適用される指示を定義します。

適用対象:

一般的なコード品質基準
全体に共通するセキュリティ要件
エラーハンドリングの方針
ドキュメント要件

サンプル構成:

# 一般的なコードレビュー基準

## コード品質の基本

- 関数は焦点を絞り、適切なサイズ(50行以下)を保つ
- 明確で説明的な命名規則を使用
- 適切なエラーハンドリングを実装
- デッドコードと未使用のインポートを削除

## セキュリティ基準

- 認証情報やAPIキーをハードコードしない
- すべてのユーザー入力を検証
- SQLインジェクション防止のためパラメータ化クエリを使用

## ドキュメント要件

- すべてのパブリック関数にドキュメントコメントを記載
- 複雑なアルゴリズムには説明コメントを追加
- READMEファイルを常に最新の状態に保つ

5.2. パス固有の指示: *.instructions.md

特定のファイルやディレクトリにのみ適用される指示を定義します。frontmatterのapplyToプロパティで対象を指定します。

適用対象:

言語固有のコーディング標準
フレームワーク固有のパターン
コードベースの異なる部分に対する異なるルール

5.2.1. Python固有の指示例

.github/instructions/python.instructions.md を作成:

---
applyTo: "**/*.py"
---

# Python コーディング規約

## 命名規則

- 変数と関数には snake_case を使用
- クラス名には PascalCase を使用
- 定数には UPPER_CASE を使用

## コードスタイル

- PEP 8 スタイルガイドラインに従う
- 行の長さは88文字に制限(Black フォーマッタ標準)
- 関数シグネチャには型ヒントを使用

## ベストプラクティス

- 単純な変換にはリスト内包表記を使用
- 文字列フォーマットには f-string を優先
- リソース管理にはコンテキストマネージャ(with文)を使用

```python
# 避けるべきパターン
file = open('data.txt')
content = file.read()
file.close()

# 推奨パターン
with open('data.txt') as file:
    content = file.read()

5.2.2. React/TypeScript固有の指示例

.github/instructions/frontend.instructions.md を作成:

---
applyTo: "src/components/**/*.{tsx,jsx}"
---

# React コンポーネントガイドライン

## コンポーネント構造

- フックを使った関数コンポーネントを使用
- コンポーネントは小さく焦点を絞る(200行以下)
- 再利用可能なロジックはカスタムフックに抽出

## 状態管理

- ローカルなコンポーネント状態には useState を使用
- コンポーネント間で共有する状態には useContext を使用
- prop drilling は2〜3階層を超えないようにする

## アクセシビリティ

- すべてのインタラクティブ要素にキーボードアクセスを提供
- 適切なARIAラベルを含める
- 色のコントラストがWCAG AA基準を満たすことを確認

5.3. 複雑な指示セットの分割

大規模なリポジトリでは、指示を複数のファイルに分割することを推奨します。

.github/
  copilot-instructions.md              # 一般基準

.github/instructions/
  python.instructions.md               # Python固有
  javascript.instructions.md           # JavaScript固有
  security.instructions.md             # セキュリティ固有
  api.instructions.md                  # API固有

各ファイルは明確で具体的な目的を持ち、必要に応じて適切なapplyTo frontmatterを含めます。

6. 推奨される指示ファイル構造

実際の運用で効果的だった構造テンプレートを紹介します。

---
applyTo: "**/*.{js,ts}"  # パス固有ファイルの場合
---

# [タイトル: 技術名またはドメイン名] ガイドライン

## 目的

このファイルが何をカバーし、いつ適用されるかの簡潔な説明。

## 命名規則

- ルール1
- ルール2
- ルール3

## コードスタイル

- スタイルルール1
- スタイルルール2

``javascript
// 正しいパターンを示す例

## エラーハンドリング

- エラーの処理方法
- 使用すべきパターン
- 避けるべきもの

## セキュリティ考慮事項

- セキュリティルール1
- セキュリティルール2

## テストガイドライン

- テスト要件1
- テスト要件2

## パフォーマンス

- パフォーマンス考慮事項1
- パフォーマンス考慮事項2

この構造を基本としつつ、プロジェクトの要件に合わせて調整してください。明確なセクション分けと箇条書きフォーマットは維持することが重要です。

7. 指示に含めてはいけない内容

Copilotが現在サポートしていない指示タイプを理解することで、無駄な労力を避けられます。

7.1. サポートされていない指示

以下のような指示は機能しません。

ユーザー体験やフォーマットの変更

# これらは機能しません
- 重大な問題には太字テキストを使用
- レビューコメントのフォーマットを変更
- コメントに絵文字を追加

プルリクエスト概要の変更

# これらは機能しません
- PR概要にセキュリティ問題のサマリーを含める
- 概要コメントにテストチェックリストを追加

Copilotのコア機能の変更

# これらは機能しません
- すべてのCopilotレビューコメントが対応されない限りPRをブロック
- すべてのPRに対して変更ログエントリを自動生成

外部リンクへの参照

# これは機能しません
- 外部URLの基準に従ってレビュー

回避策: 外部リンクの内容を直接指示ファイルにコピーしてください。

曖昧な品質改善要求

# これらは機能しません
- より正確に
- 問題を見逃さないで
- フィードバックに一貫性を持たせて

これらの指示は、Copilotが既に最適化されているため、追加してもノイズになるだけです。

8. テストと反復的改善

効果的なカスタム指示を作成する最良のアプローチは、小規模から始めて結果に基づいて反復することです。

8.1. ステップ1: 最小限の指示セットから開始

最も重要なレビューニーズに対応する10〜20個の具体的な指示から始めます。

8.2. ステップ2: 実際のプルリクエストでテスト

指示を作成したら、実際の環境でテストします。

リポジトリでプルリクエストを作成
Copilotにレビューを依頼
どの指示が効果的に守られているか観察
一貫して見落とされる、または誤解される指示を記録

8.3. ステップ3: 結果に基づいて反復

1つずつ、または小グループで新しい指示を追加します。

Copilotがより適切にレビューできるパターンを特定
そのパターンに対する具体的な指示を追加
新しいプルリクエストでテスト
結果に基づいて指示を改善

この反復的アプローチにより、何が機能するかを理解し、指示ファイルを焦点を絞った状態に保てます。

9. 完全な実装例

これまでのベストプラクティスを統合した完全な例を紹介します。

9.1. ファイル: .github/copilot-instructions.md

# 一般的なコードレビュー基準

## 目的

この指示は、リポジトリ内のすべてのファイルに対するCopilotコードレビューをガイドします。
言語固有のルールは別の指示ファイルに記載されています。

## セキュリティクリティカルな問題

- ハードコードされたシークレット、APIキー、認証情報をチェック
- SQLインジェクションとXSS脆弱性を確認
- 適切な入力検証とサニタイゼーションを検証
- 認証と認可ロジックをレビュー

## パフォーマンスの問題

- N+1データベースクエリ問題を特定
- 非効率なループとアルゴリズムの問題を発見
- メモリリークとリソースクリーンアップをチェック
- 高コストな操作のキャッシング機会をレビュー

## コード品質の基本

- 関数は焦点を絞り、適切なサイズ(50行以下)を保つ
- 明確で説明的な命名規則を使用
- 適切なエラーハンドリングを実装
- デッドコードと未使用のインポートを削除

## レビュースタイル

- フィードバックは具体的で実行可能にする
- 推奨事項の「理由」を説明
- 良いパターンを見つけたら認める
- コードの意図が不明確な場合は質問する

## テスト基準

- 新機能には単体テストが必要
- テストはエッジケースとエラー条件をカバーすべき
- テスト名はテスト内容を明確に説明すべき

常にセキュリティ脆弱性とユーザーに影響を与える可能性のあるパフォーマンス問題を優先してください。

9.2. ファイル: .github/instructions/typescript.instructions.md

---
applyTo: "**/*.{ts,tsx}"
---

# TypeScript 開発基準

## 型安全性

- `any`型の使用を避ける—`unknown`または具体的な型を使用
- strictヌルチェックを使用(明示的な処理なしに`null`や`undefined`を使わない)
- すべてのオブジェクト形状にインターフェースを定義

``typescript
// 避けるべきパターン
function processData(data: any) {
    return data.value;
}

// 推奨パターン
interface DataShape {
    value: string;
}

function processData(data: DataShape): string {
    return data.value;
}
``

## 命名規則

- 型、インターフェース、クラスには PascalCase を使用
- 変数、関数、メソッドには camelCase を使用
- 定数には UPPER_CASE を使用

## モダンなTypeScriptパターン

- オプショナルチェイニング(`?.`)とnullish coalescing(`??`)を使用
- `let`より`const`を優先、`var`は絶対に使わない
- コールバックと短い関数にはアロー関数を使用

## React固有(.tsxファイル用)

- TypeScript propsインターフェースを持つ関数コンポーネントを使用
- すべてのpropsとstateを明示的に型付け
- 適切なイベント型を使用(例: `React.ChangeEvent<HTMLInputElement>`)

10. トラブルシューティング

Copilotが期待通りに指示に従わない場合の解決策を紹介します。

10.1. 問題: 指示が無視される

考えられる原因:

指示ファイルが長すぎる(1,000行超)
指示が曖昧または不明確
指示同士が矛盾している

解決策:

重要度の低い指示を削除してファイルを短縮
曖昧な指示を具体的で実行可能な内容に書き直し
矛盾する指示をレビューし、最も重要なものを優先

10.2. 問題: 言語固有のルールが間違ったファイルに適用される

考えられる原因:

applyTo frontmatterが欠落または不正確
リポジトリ全体のファイルにパス固有のルールが含まれている

解決策:

パス固有の指示ファイルにapplyTo frontmatterを追加
copilot-instructions.mdから言語固有のルールを適切な*.instructions.mdファイルに移動

10.3. 問題: レビュー間で動作が一貫しない

考えられる原因:

指示が多すぎる
指示に具体性が欠けている
AIレスポンスの自然な変動性

解決策:

最優先の指示に焦点を当てる
意図を明確にするために具体例を追加
AIシステムの変動性は正常であることを受け入れる

11. まとめ

効果的なカスタム指示により、GitHub Copilotのコードレビューはチームの基準に合わせた、より実用的なフィードバックを提供できるようになります。本記事で紹介した原則—指示を簡潔に保つ、明確な構造を提供する、具体例を使用する、複数ファイルに整理する—に従うことで、コードレビュー体験を大幅に改善できます。

効果的な指示の作成は反復的なプロセスです。焦点を絞った小さな指示セットから始め、実際のプルリクエストでテストし、チームにとって効果的なものに基づいて段階的に拡張していきましょう。

実際のプロジェクトでカスタム指示を試し、チームにとって最適な設定を見つけてください。適切に設定されたCopilotは、コードレビューの品質と効率を向上させる強力なツールとなります。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up