注意:
この記事はGitHub Copilotの指示書の自分なりの使い方です。
GitHub Copilotに新しい機能が追加されたので、その機能と自分なりの使い方がメインとなります。
翻訳部分は、第一版に相当するSCode の Rules for AI 全体のルール設定翻訳 GitHub Copilotを御覧ください。

指示書のリポジトリ

masakinihirota/github-copilot-custom-instructions: GitHub Copilot 指示書

GitHub Copilotシリーズ

※第一版に相当する VSCodeのRules for AI 全体のルール設定翻訳 GitHub Copilotも合わせてご覧ください。

GitHub Copilotに伝われば、形式はどのような形でもよいです。

これは、指示書の作成例です。

Webアプリ開発で設計書、指示書、MCP

指示書には
矛盾がないか？
シンプルに書かれているか？
重複がないか？

用語

全体の指示書

英語では custom instructions file (公式Doc) と呼ばれます。
ルールが重複すると管理が煩雑になるため、目的別に指示書を使い分けます。
この記事では、GitHub Copilot に設定するファイルを「指示書」とします。
GitHub Copilot には3種類の指示書を設定でき、ルールの重複を避けて管理を効率化するため、目的別に使い分けます。

タスクリストファイル

設計書に基づいて分割された、実装すべき目的や、機能単位のリスト。各タスクは、コード実装を優先して定義されます。

タスク分解

設計書から、機能などを1機能1タスクを目安に分解してもらいます。
タスクリストの各項目を、より小さな実装単位に分割したものです。
1タスクの大きさが十分に小さかったらタスク分解の必要はありません。
タスク分解したものをプロンプトファイルにします。

プロンプトファイル

GitHub Copilot に具体的なタスクを指示するための詳細なドキュメントです。

設計書をタスクリスト化して(タスクが大きい場合はタスク分解)、GitHub Copilotに指示しやすい大きさにしたものです。
問題を小さく分けることで、AI にすべての情報を与え、希望する提案を得やすくなります。

タスクリストの各項目を実装するために、AIに与える詳細な指示を記述したドキュメントです。

１つのプロンプトファイルで１つの仕事の単位で書きます。

AIと会話して設計書からプロンプトファイルを書きます。
会話をしていく中で、詳細な部分まで決めていきます。

設計書

Webアプリケーションの構想、概要、要件定義、画面設計、データベース設計、API設計、テスト計画などをまとめたドキュメントです。
/design フォルダ内に置いています。

リポジトリ

Webアプリケーションのソースコードや関連ファイルを管理するための保管場所です。
Gitバージョン管理システムを用いて、変更履歴の追跡や共同開発を容易にします。

べからず集してはいけないこと

1回で複数の問題を解決しようとする。
1回のプロンプトファイルで1つの問題を解決することに集中する。
GitHub Copilotが可能な手段で考える必要がある。
まだ一度の指示ですべての問題を解決出来るほどGitHub Copilotはそれほど賢くない。
指示書に詰め込む。
指示が長過ぎると指示が反映されなくなります。
Gemini系など受け付ける容量が大きいとこの問題は小さくなります。
曖昧な指示をする。
「それっぽい感じで」「なんとなく」といった曖昧な表現は、GitHub Copilotが混乱します。
具体的な要件や期待する動作を明確にします。
複雑な指示をする
指示は出来る限りシンプルにしたほうが良いでしょう。
小さな違和感の放置
技術的負債が入り込みやすくなります。
徹底的に技術的負債と向き合います。
技術的負債を後回しにする。
技術的負債を後回しにすればするほど大きく、修正困難になっていきます。
技術的負債は小さいうちにどんどん片付けておきましょう。
余計な情報を与える。
GitHub Copilotは書かれてある指示通りに最後まで突き進もうとします。
余分な指示やコードはできるだけ排除します。
GitHub Copilotは何でも出来るので何でも命令する。
GitHub Copilotはあくまでコーディングエージェント、アシストツールであり、完全な自動化ツールではありません。
複雑なロジックや高度な設計判断は、分解して問題を小さくするか、人間の手で行う必要があります。
自動生成だからテストを書かなくていい。
テストコードは重要です。
GitHub Copilotも気づかずに他の機能に関与したコードを書き換える可能性があります。
テストはレグレッションテスト(退行テスト)も兼ねています。
GitHub Copilotが生成したコードに対して、適切なテストコードを作成し動作確認を行います。
テストコードは、コードの品質を保証します。
盲目的にGitHub Copilotを信用する。
GitHub Copilotを信用してはいけません。
生成されたコードは、あくまで提案でしかありません。
失敗してもコードを残す。
失敗したコードは破棄しましょう。
サンクコストです、料金を払って提案されたコードといえどもプロジェクトに沿わないコードを残していけば、たちまち雪だるま式に負債が溜まっていきます。

フォルダ・ファイルの種類

設計書
全体の指示書: プロジェクト全体で共通する指示
個別の指示書: 全体の指示書ではかけなかった個別の指示
プロンプトファイル: タスクの実装詳細情報

タスクリストファイル: タスク一覧
メモリーファイル: 実行履歴

settings.json

VSCode用の設定ファイルです。
VSCodeの設定で呼び出して登録します。
自然言語で登録できます。
ファイルで登録できます。

開発者のための指示を書きます。

設計書のフォルダ

design/

design/design.md (設計書)

Webアプリの設計を書きます。

GitHub Copilotへの指示書・プロンプトファイル

プロジェクトのための指示を書きます。

.github/
├── copilot-instructions.md (全体の指示書)
├── memory.md (メモリーファイル)
├── .copilot-commit-message-instructions.md (以下、個別の指示書)
├── .copilot-review-instructions.md
├── .copilot-test-instructions.md
├── .copilot-codeGeneration-instructions.md
└── prompts/ (プロンプトファイル用のフォルダ)
├── task-list.prompt.md (タスクリストファイル)
├── completes/ (実装が終わったプロンプトファイルを入れるフォルダ)
├── 20250401-001-code-style-doc.prompt.md (以下、プロンプトファイル)
├── 20250401-003-comment-rule-doc.prompt.md
├── 20250401-004-component-style-doc.prompt.md
├── 20250401-005-sample-doc.prompt.md
├── 20250401-002-test-rule-doc.prompt.md
└── 20250401-006-user-authentication-feat.prompt.md

MCP (VSCode Insider)

.vscode
└── mcp.json

全体の指示書

GitHub Copilot に最初 copilot-instructions.md ファイルを参照してもらいます。
プロジェクト全体、もしくはプロジェクト単位のルールを記述してあります。
概要、構造、アーキテクチャ、制約、技術スタック、ツールを記述してあります。
プロンプトファイルを実装する時に毎回、プロジェクトのアーキテクチャ、目標、スタイル、制約を理解するために、新しい会話を始めるときは常に copilot-instructions.md を参照してください。
タスクリストが出来たら優先度を付けましょう。設計書の段階でどの機能を優先してつけるかを決めてもいいです。

メモリーファイル

.github/memory.md

コード生成や、チャットで決めてきた仕様を記録するファイルです。
メモリーファイルを利用することで、途中から再開することが容易くなります。

個別の指示書

全体の指示書以外に個別に決めた指示です。
全体の指示書よりも、個別の指示書を優先してもらいます。

コード生成の指示書
.github/.copilot-codeGeneration-instructions.md
コミットメッセージの指示書
.github/.copilot-commit-message-instructions.md
レビューの指示書
.github/.copilot-review-instructions.md
テストの指示書
.github/.copilot-test-instructions.md

タスク

原則として、1タスク1機能で作ります。

タスクリストファイル
.github/prompts/task-list.prompt.md
設計書をタスクに分解を登録したリストです。

プロンプトファイル

1タスクの詳細を書いてあるファイルです。
プロンプトファイルは、具体的な実装を書いたファイルです、このプロンプトファイルに従ってGitHub Copilotにコードを生成してもらいます。実際にコードを生成する前にGitHub Copilotを話し合って内容をしっかり詰めておきましょう。
原則として1タスク1機能で、1つのプロンプトファイルを作成します。
プロンプトファイルには実際にコードを生成する情報が書かれています。
GitHub Copilotはこのプロンプトファイルの指示に従ってコードを生成してください。

プロンプトファイルのフォーマット

.github/prompts/[YYYYMMDD]-[タスクid]-[タスク名]-[タスクの種類].prompt.md

例: 20250401-123-loginFeature-feat.prompt.md

feat: 機能開発（新しい機能の追加）
fix: バグ修正
test: テスト関連
doc: ドキュメント関連
refactor: リファクタリング
style: スタイル調整

プロンプトファイルの例

.github/prompts/20250401-001-code-style-doc.prompt.md
.github/prompts/20250401-002-test-rule-doc.prompt.md
.github/prompts/20250401-003-comment-rule-doc.prompt.md
.github/prompts/20250401-004-component-style-doc.prompt.md
.github/prompts/20250401-005-sample-doc.prompt.md
.github/prompts/20250401-006-user-authentication-feat.prompt.md

completesフォルダ

.github/prompts/completes/

.github/prompts/completes/20250401-007-user-profile.prompt.md

実装が終わったプロンプトファイルを入れる場所です。

MCP設定ファイル

.vscode
└── mcp.json

GitHub Copilot への指示書

指示書より前の準備

設計書を作成しておきます。
設計書は開発しながら一緒に成長させます。
設計書から、まず人間がプロジェクトの大枠、ドメインの範囲を設定します。
例えば、テンプレート、スターター等を用意します。
その枠内を一つ一つ確実に積んでいくというイメージで作ります。
環境変数を開発者の手で設定しておきます。
メモリーファイルをリセットしておきます。

指示書の書き方

コードを作成する前に、開発者と GitHub Copilot で十分に話し合ってください。
プロジェクト開始時に、スコープとタスクを明確に定義してください。
コンテキストは詳細であればあるほど、より適切なコード生成に繋がります。
具体的なサンプルコードは、GitHub Copilot の理解を助けます。
コードとドキュメントは同時に記述することを推奨します。
環境変数の実装は、開発者が責任を持って行ってください。

第二版 VSCode の Rules for AI 全体のルール設定翻訳 GitHub Copilot #githubcopilot - Qiita
https://qiita.com/masakinihirota/items/247bee4bd66ace86e1da

VSCode(ネイティブ)にMCPを設定して、GitHub Copilot Agent modeでSupabaseを操作する。 #githubcopilot - Qiita
https://qiita.com/masakinihirota/items/b5ae692191d197eb5ad7

指示書

VSCodeの設定ファイル内に記入

settings.json

copilot-instructions.md

copilot-instructions.md

# Webアプリ開発プロジェクトのための全体の手順

最初に設計書をもとにタスク分解を行います。
タスク分解をしたものをタスクリストファイルに登録します。
タスク分解で分けたものを1タスクとします。
1タスクはGitHub Copilotに読み込ませるのに適切な大きさです。

[繰り返し]
1タスクを元に詳細な情報を載せたプロンプトファイルを作成します。
開発者は、プロンプトファイルに詳細な実装のための情報を補強します。
開発者とGitHub Copilotの双方が確認したプロンプトファイルを利用して機能を追加していきます。
GitHub Copilotはコードを生成します。
生成されたコードに技術的負債がないかを確認します。
実装後、ユニットテスト、結合テスト、E2Eテスト等を行います。
問題があれば、リファクタリングを行います。
ソースコードだけを見てもらってコードの批判と分析をしてもらいます。
レビューをします。

設計書の最後まで、これを繰り返します。



# Webアプリ開発のための設計書＆指示書・プロンプトファイル

最初にWebアプリの**設計書**を作っておきます。
設計書から**タスクリストファイル**やGitHub Copilotへの**指示書・プロンプトファイル**を作成します。

## 指示書の優先順位

メモリーファイル＞プロンプトファイル＞個別の指示書＞全体の指示書

## フォルダ・ファイルの種類

設計書(複数)
タスクリストファイル: タスク一覧
指示書 全体の指示書(1ファイル): プロジェクト全体で共通する指示
指示書 個別の指示書(複数): 全体の指示書ではかけなかった個別の指示
指示書 プロンプトファイル(複数): タスクの実装詳細情報
指示書 メモリーファイル(1ファイル): 実行履歴

## 振る舞い

GitHub Copilot に、以下の技術スタックに精通したエキスパートとして振る舞ってください。

* TypeScript、Node.js、Next.js (App Router)、React
* Shadcn/UI、Radix UI、Tailwind CSS
* Zustand
* Supabase、Drizzle ORM
* Zod
* Stripe
* Vitest、React Testing Library
* Storybook

## タスク管理

### タスクリストファイルの作成と更新

1.  **設計書の確認とタスク分解**:
    * 最初に設計書を確認します。
    * 設計書の場所は **design/** にあります。
    * 設計書を元に、1機能単位にタスク分解を行います。
    * タスク分解したものをタスクリストファイルに登録します。

2.  **タスクリストファイルの管理**:
    * `task-list.prompt.md` ファイルを作成、編集、更新します。
    * それぞれのタスクにタスクIDを割り当てます。
    * 現在のタスク、これから行うタスクを記録します。
    * 完了したタスクは、終了後すぐに `task-list.prompt.md` にチェックマークを付けます。
    * 開発中に発見された新しいタスクや TODO は、`task-list.prompt.md` の「作業中に発見」セクションに追加します。

### プロンプトファイルの作成と実行

1.  **プロンプトファイルの作成**:
    * タスクリストファイルから、1タスク1機能ごとにプロンプトファイルを作成します。
    * 1プロンプトファイルは1機能1タスクを守ります。
    * タスクリストファイルから1タスクを取り出した時、以下の命名規則でプロンプトファイルを作成します。
    * プロンプトファイルの命名規則

プロンプトファイルのフォーマット
`.github/prompts/[YYYYMMDD]-[タスクid]-[タスク名]-[タスクの種類].prompt.md`

例: 20240426-123-loginFeature-feat.prompt.md

feat: 機能開発（新しい機能の追加）
fix: バグ修正
test: テスト関連
doc: ドキュメント関連
refactor: リファクタリング
style: スタイル調整

2.  **プロンプトファイルの実行**:
    * 指示されたプロンプトファイルに基づいてファイル内に書いてある指示を実行します。
    * プロンプトファイルの実行前に `task-list.prompt.md` を確認します。
    * プロンプトファイルの実行時に `copilot-instructions.md` に記述されているルールに従います。
    * プロンプトファイルの実行後、「プロンプトファイル完了後の処理」の指示に従います。

### プロンプトファイル完了後の処理

1.  **タスクリストファイルの更新**:
    * 完了したタスクは、終了後すぐに `task-list.prompt.md` にマークします。
    * GitHub Copilot は `task-list.prompt.md` を更新します。
        * 例: 「`task-list.prompt.md` の〇〇が完了したのでチェックし、△△を新しいタスクとして追加してください。」

2.  **コードレビューと改善**:
    * プロジェクトの背景情報を一切見ずに、ソースコードだけを読み、ソースコードや設計を批判します。
    * すべてのdeprecatedのコードを削除します。
    * 新しい仕組みへの中間状態を作らないようにします。
    * 技術的負債を徹底的に無くします。

### 技術的負債の定義と解消

* **技術的負債の定義**:
    * コードの重複
    * 複雑すぎるコード
    * テストがないコード
    * ドキュメントがないコード
    * パフォーマンスが悪いコード
    * セキュリティ上の問題があるコード

* **技術的負債の解消方法**:
    * リファクタリング
    * テストの追加
    * ドキュメントの作成
    * パフォーマンス改善
    * セキュリティ修正

## GitHub Copilot の動作ルール

* コンテキストが不明な場合は、質問してください。
* 存在しないライブラリや関数は使用せず、既知の、検証されたライブラリのみを使用してください。
* コードやテストで参照する前に、ファイルパスやモジュール名が存在することを確認してください。
* 明示的に指示されていない限り、または `task-list.prompt.md` のタスクに含まれていない限り、既存のコードを削除または上書きしないでください。
* プロジェクトの修正や変更を行う際は、一度に 1 つのタスクに集中してください。
* 変更、修正があった場合メモリーファイル `memory.md` を更新してください。
* コード変更後は、タスクリストファイル `task-list.prompt.md` を更新してください。


### メモリーファイル

メモリーファイル `memory.md` には、

* 開発環境、使用技術
* システムの構成、技術的判断、設計パターン
* プロジェクトの目的、解決する問題、期待される挙動
* 現在作業中の内容、最近の変更点、次のステップ
* 完成済みの機能、進捗状況、残りの作業
を書いてください。

例

	```memory.md
	[開発環境、使用技術]

	[システムの構成、技術的判断、設計パターン]

	[プロジェクトの目的、解決する問題、期待される挙動]

	[現在作業中の内容、最近の変更点、次のステップ]

	[完成済みの機能、進捗状況、残りの作業]

	```



## 使用技術スタック

### 基本事項

* 言語: TypeScript、Node.js
* フレームワーク: Next.js (App Router)、React
* UI ライブラリ: Shadcn/UI、Radix UI、Tailwind CSS
* 状態管理: Zustand
* ORM: Drizzle ORM
* バックエンド: Supabase
* スキーマ検証: Zod
* 決済: Stripe
* テスト: Vitest、React Testing Library
* UI コンポーネント管理: Storybook

### 環境変数

* 環境変数は `.env` ファイルおよび `.env.local` ファイルで管理し、Next.js の仕組みに従って安全に利用してください。

## コーディング規約

* 性能よりもシンプルさを優先してください。
* 関数型および宣言型のプログラミングパターンを推奨し、クラスの使用は極力避けてください。
* コンポーネントの配置パターンには、コンポーネントのコロケーションを考慮してください。
* コロケーションを利用したコンポーネントは、同じフォルダにビューコンポーネント、ビジネスロジックコンポーネント、フェッチコンポーネント、テストファイル、およびストーリファイルを配置してください。
* anyを使用しないでください。
* 型安全を設定してください。
* 1 ファイルあたりの行数は 500 行以内にしてください。ファイルがこの制限に近づいたら、モジュールやヘルパーファイルに分割してリファクタリングしてください。
* 機能または責任ごとに、明確に分離されたモジュールにコードを整理してください。
* 指示は具体的に記述し、曖昧な部分があれば指摘してください。
* 互換性は残さないでください、全て消してください。



### コードのコメント

* コメント形式: JSDocを使った明確なコンテキストを書いてください。
* コードを修正したらコメントも適切なものにしてください。
* 不要なコメントは削除してください。
* 食い違いのあるコメントは修正してください。


## テストに関する指示

* 関数はユニットテストを書いてください。
* 全ての新しい機能にユニットテストを記述してください。
* Vitest を使用してユニットテストを記述してください。
* React Testing Library を使用してコンポーネントのテストを記述してください。
* テストは `describe` でグループ化し、`it` でテストケースを記述してください。
* テストケースは日本語で記述してください。
* ロジックを変更した場合は、既存のユニットテストを更新する必要があるか確認し、必要に応じて更新してください。
* テストは、コンポーネントと同じフォルダ内に配置してください (コロケーション)。
* テストには、少なくとも次のものを含めてください。
    * 予想される使用に対するテスト
    * 1 つのエッジケースのテスト
    * 1 つの失敗ケースのテスト

## UI に関する指示

* UI はシンプルで直感的なデザインを心がけてください。
* モバイルフレンドリーなレスポンシブデザインを考慮してください。

## セキュリティ

* `.env*` ファイルは git で管理しないでください。

## ドキュメント

* `README.md` には、使い方や説明などを記述してください。
* 変更内容は `README.md` に反映させてください。


### テストのベストプラクティス

* テストは、コンポーネントと同じフォルダ内に作成してください (コロケーション)。
* DB や GitHub Copilot のようなサービスへの呼び出しは、常に「モック」を使用してください。
* 各関数について、少なくとも 1 つの成功シナリオ、1 つの意図的な失敗 (適切なエラー処理を保証するため)、および 1 つのエッジケースをテストしてください。

## MCP (Model Context Protocol) の設定

* MCP の設定は `.vscode\mcp.json` にあります。
* 現在の MCP の設定: Supabase

指示書を書く心構え

指示書とは

AIと人間とのギャップを埋めるためのルール
AIは何も指示しないとあらゆる可能性を試そうとします。
人間がきちんとルールで縛っておくことが重要です。
そのための文書が指示書です。

下準備はきちんと行う

料理を作る前に材料と道具をすべて揃えておくように
AIも必要なすべての指示書やMCP、開発環境、モデル選定、タスクリストを用意しておきます。
例えば、バグの処理を頼むなら、AIは推論モデルを使うのが良いとされています。
Gemini 2.0 Flash Thinkingなど

AIはレールの上ならばきちんと動きますが、
AIは壊れた環境を直すのに適していません。
殆どの場合、修復不可能に破壊することになるでしょう。

したがって、すべてが正しく設定されいることを確認してください。

AIは記憶しない

AIはタスクを実行するよう指示するたびに必要なコンテキストを再構築する必要があります。

AIは新しくチャットを開始するたびに、コードベースを0から理解しようとします。
AIに適切な指示書を与えることで、誤解を防ぎ、効率的なコーディングをすることが出来ます。

AIは仕様を尊重することが得意ではない

コーディング中にテストを削ったり、APIを変更したり何でも行ってしまいます。
人間がコードレビュー時に仕様との整合性を確認する必要があります。
正確な情報を与えることやタスク分解をして問題を小さくするなどの対応が有効です。

AIはイノシシ

AIは力ずくで問題を解決しようとします、
学習しながらうまくいくまで何回も試そうとします。
AIの試行回数の制限は付けておきましょう。

難しい問題の場合、人間ならば途中で立ち止まりますが、AIはタスクを忠実に完了させようと進み続けます。
AIの良い面でもあり、悪い面でもあります。
人間が実装書を作るに当たり、問題を回避したり、タスク分解をして問題を解決しやすくします。

フォーマッターを利用する

AIは機械的なコーディングルールに従うのが苦手です。
Next.jsなどはBiome,Prettier等のツールを利用します。
VSCode本体や、GitHubにPush時にhusky等のツールで自動化を設定しておきます。

MCPを使用する

モデルコンテキストプロトコル（MCP）サーバーは、LLMが環境とやり取りするための標準インターフェースを提供します。
使用することで、MCPはAIを強力にサポートしてくれます。

大きなファイルは禁止

ファイルが大きくなるとパフォーマンスに影響を与えます。
ファイルを小さく保つことが重要です。

静的な型

TypeScriptの型を利用することでAIは把握しやすくなります。

ドキュメントを読ませる。

AIはトレーニングによって非常に多くのことを知っていますが、最新の情報に弱い場合があります、そのようなときは最新のドキュメントを読ませるようにします。

読ませ方は色々あります。
Web検索がサポートされているAIを利用する
MCPを利用する
ファイルにしてAIに読み込ませる。
ドキュメントのURLを教える

優先順位

AIは優先順位をつけることが苦手です。
指示された文章をすべて覚えておこうとするので
どうでもいいような情報がたくさんあると、
本当に大事なことを忘れることがあります。
だから、最初に「こういうことをお願い！」ってちゃんと伝えておくことが大切です。
あとは、関係ない情報はなるべく入れないようにするとか工夫をしましょう。

テンプレートを作る

テンプレートとは必要なすべてのパーツを備えた最小限の実装です。
まずは大枠を作っておいて、全体を動かし、そして少しづつ実装していくのがおすすめです。

AIに痛みはない

人間は限界以上の動作には痛みがでて自然に止まります。
AIは自分の限界を知るのが苦手です。
限界を認識させるために明示的な指示が必要です。
AIが実行できることのみを実装するように依頼することが重要です。

リファクタリング

AIはコードをコピーする傾向があります
同じコードが増えた場合はコードを積極的にリファクタリングをするようにしましょう。
AIは指示がない限りコードを積極的にリファクタリングをしようとはしません。
重複を減らすように指示を出しましょう。

コードは、きれいに整理整頓して、メンテナンスしやすい状態を保ちましょう。

リファクタリング前のリファクタリング

AIは変更を一度に行おうとしたり、関係のない箇所のリファクタリングをしようとします。
リファクタリングをするまえに、リファクタリングしやすいように下準備しておきましょう。
リファクタリングを終えた後は、人間がレビューすることが大切です。

AIはすでにルールを持っている

AIは学習データやファインチューニング、コンテキストウィンドウによって形成されます。よってAIが生成するコードはそれらに大きく影響を受けます。

例えば、コンテキストウィンドウに特定のライブラリを使うコードがたくさんあれば、LLMもそのライブラリを使い続ける傾向があります。

ルールを変えたい場合は、指示書を使って自分のルールに従わせる必要があります。指示書に書いてない場合は、AIはすでに持っているルールでコードを生成し始めます。
コードベースは指示書よりもAIの行動に大きく影響を与えます。

複数の指示書に分ける目的

指示書のアップデートをしやすくする。
人間が理解しやすくなる。
指示の抜け落ちなどが見つけやすくなる。
目的別に管理しやすくする。
固定のルールを再利用しやすくする。
一度きりのルールを作りやすくする。
チームで管理しやすくなる。
履歴を残しやすくする。

考慮する項目

機能

機能、具体的な処理内容
限界値、条件、入力値の範囲、処理するデータ量
エラー対策、例外処理、エラーメッセージ、ログ出力方式、ユースケース

テスト

使用するテストフレームワーク、ストーリー、ユーザーシナリオ、単体テスト、結合テスト、E2Eテスト、Playwright MCP

関数、コンポーネント、ページ

データの名前
型
範囲
意味
関係性
処理内容
入力内容
出力内容

などを決めていきプロンプトファイルを完成させていきます。
GitHub Copilot の提案精度の向上を行います。

プロンプトファイルを完成させたら、GitHub Copilot Agent mode等でコードを書いてもらいます。

指示書とプロンプトファイルの違い

指示書はGitHub Copilotに設定する指示です。
プロンプトファイルは設計書をタスクリスト(＆タスク分解)から、特定の目的や機能を詳細に書いたものです。
プロンプトファイルの内容を基に、動的な指示書（プロンプトファイル）を作成し、GitHub Copilot に具体的なコード生成やテストなどのタスクを実行させる、という流れが考えられます。プロンプトファイルは、AI との会話を通じて詳細を詰めていく過程で進化していくドキュメントと言えるでしょう。
プロンプトファイルを作成する際には、GitHub Copilot がより良い提案をするために、以下の点を考慮すると良いでしょう:

GitHub Copilotの指示書とは

GitHub Copilot in VS Code
https://code.visualstudio.com/docs/copilot/overview

Custom instructions for GitHub Copilot in VS Code
https://code.visualstudio.com/docs/copilot/copilot-customization

GitHub Copilotには事前に設定しておく
指示書があります。

詳しくは

VSCode の Rules for AI 全体のルール設定翻訳 GitHub Copilot #githubcopilot - Qiita
https://qiita.com/masakinihirota/items/1694715063247574467d

👆この記事ではVSCodeに設定する指示と、リポジトリに設定する指示のかなりの部分が被っています。

👆この記事以降にプロンプトファイルという機能が追加されました。

以前は実質1つのみでしたが
(VSCode本体に書くか、リポジトリ直下に書くか)

3つ目の指示書、プロンプトファイルの導入で
静的(固定)なルール
動的なルール
を使い分けるという意味で、さらに柔軟な運用ができるようになりました。

今回はGitHub Copilotの指示書が3種類になったので、目的別にルールを使い分けてみます。

注意:
GitHub Copilotの公式で定めた場合のファイルは別ですが、
指示書の中で外部のファイル(指示書)を読み込ませようとするのは非推奨とされていました。
これは公式ドキュメントに書いてあります。
なので共通の指示書を作ってそれを個別の指示書に読み込ませるなどは止めたほうがいいでしょう。

現在のGitHub Copilotの指示書の種類

それぞれの使用目的

VSCode固定のルールをVSCode本体(settings.json)に書きます。
リポジトリ全体のルールをcopilot-instructions.mdに書きます。
個別の機能や目的のルールはプロンプトファイルに書きます。

1の固定のルールとはVSCodeを使う時に毎回必ず守ってもらうルール。

2のリポジトリ全体のルールとはそのリポジトリで使う全体のルール

3の開発者の目的を明確に伝えるための指示書になります。
(毎回設定を全部読み込ませると、GitHub Copilotの提案がぼやけてしまうため。)

指示書のファイルの種類

VSCodeの設定settings.jsonファイル内
copilot-instructions.md
プロンプトファイル

これを使い分けて利用します。

VSCode側の設定

settings.json

1 settings.jsonファイル内は通常のVSCodeの設定を開いて指示を追加できます。
自然言語とファイル名を指定できます。

これをVSCodeを使う上で必ず使う指示を書きます。

例
常に日本語で分かりやすい言葉を選び、丁寧な表現を心がけます。
語尾に「にゃー」をつけてください。

GitHub Copilot側の設定

2 copilot-instructions.md このファイルはリポジトリのルート直下の.github内に置くよう定められています。

リポジトリ全体に影響を与えるルールを書きます

例
TypeScript、Node.js、Next.js (App Router)、React、Shadcn UI、Radix UI、Tailwind CSS、Zustand、Supabase、Zodのエキスパートとして振る舞います。
Next.js 15 を使います。
App routerを使います。
Supabaseを使います。
Honoを使います。

3 プロンプトファイルは、ワークスペースの .github/prompts ディレクトリに拡張子 *****.prompt.md のファイルを作成します。

指示書の使い分け

固定ルールを settings.json
全体の指示書 copilot-instructions.md
個別のプロンプトファイル

固定ルールにはVSCodeの基本的なルールを書きます。
全体の指示書にはリポジトリ単位のルールを書きます。
個別のプロンプトファイルは目的、機能単位にルールを書きます。

指示書のためのリポジトリを作成

※GitHub Copilotはインストール、有効化済みとします。
※GitHub CLIがインストール済み
ghコマンド が使えるようになります。

VSCode Insidersのインストール(スキップ可)

GitHub Copilot Agent modeは
VSCode Insidersでのみ使用できます。

Download Visual Studio Code Insiders
https://code.visualstudio.com/insiders/

Agent modeを使用したい場合は、インストールしておきます。

GitHub Copilot Agent modeを有効化の確認

GitHub Copilotのエージェントモードを使ってみた #AI - Qiita
https://qiita.com/kei1-dev/items/e6b0ead5f24de35e30ed

プロンプトファイルの有効化

GitHub Copilot のリポジトリカスタム命令を追加する - GitHub Docs
https://docs.github.com/ja/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot

"chat.promptFiles": true

プロンプトファイルの有効化。
この設定を有効にすると、チャット機能がプロンプトファイル（指示書）を利用できます。

"chat.renderRelatedFiles": true

関連ファイルの表示を有効化。
この設定により、チャット機能が現在のプロジェクトや作業中のファイルに関連するファイルを表示します。

"chat.agent.maxRequests": 20

エージェントモードでの試行回数の上限。この設定は、エージェントモードで送信されるリクエスト数を制限します。
無制限に試行されるのを防ぎます。これがなくてループにハマると永遠に終わりません。
デフォルト値: 15

"chat.mcp.discovery.enabled": true

MCPサーバーの探索機能を有効化。
この設定は、MCP（Microsoft Chat Protocol）サーバーへの接続や探索を可能にします。

"github.copilot.chat.codesearch.enabled": true

GitHub Copilot Chatでコードベース検索機能（#codebase）を有効化します。
プロジェクト全体からコード検索を行い、関連する提案や結果を取得したい場合に使用します。

"github.copilot.chat.edits.temporalContext.enabled": true

最近編集した指示書やコードをGitHub Copilot Chatの提案に含めるかどうかをきめます。

"github.copilot.chat.newWorkspaceCreation.enabled": true

新しいワークスペース作成機能を有効化します。
これにより、チャット機能が新しい作業環境（ワークスペース）のセットアップを支援します。
新規プロジェクト開始時に便利です。

"github.copilot.chat.search.semanticTextResults": true

セマンティック検索機能を有効化します。この設定では、意味的な一致（セマンティックマッチ）に基づいて検索結果が提供されます。
より高度な検索結果が必要な場合に使用します。

具体的な指示書の作成

指示書の設定場所

VSCodeのsettings.json

VSCodeの設定を開きます。

copilot-instructions.mdの指示書を有効化するために

settings.json

"github.copilot.chat.codeGeneration.useInstructionFiles": true,

を設定します。

copilot-instructions.md

リポジトリのルート直下

.github/copilot-instructions.md

を作成して指示を記入します。

mkdir .github
touch .github/copilot-instructions.md

プロンプトファイル

.github/prompts/フォルダを作成して、その中に置きます。

拡張子

*****.prompt.md

例

mkdir .github/prompts/
touch .github/prompts/code-style.prompt.md
touch .github/prompts/comment-rule.prompt.md
touch .github/prompts/test-rule.prompt.md

👆GitHub Copilot公式ドキュメントでのファイル名

自分は、
コーディングスタイル
コメントルール
テストルールは
静的な指示書に書いたほうがいいと思います。

1. VSCodeの指示書

固定(VSCode)の指示書
個人用のルールを書きます。

VSCodeのGitHub Copilotを使う上でずっと使い続けるルール

このファイルの指示の優先度は一番後回しにします。
※ルールが被った場合のため

settings.jsonに登録する指示書の作成

touch .copilot-codeGeneration-instructions.md
touch .copilot-test-instructions.md
touch .copilot-review-instructions.md
touch .copilot-commit-message-instructions.md

👆それぞれ
コード生成用の指示書
テスト用の指示書
レビュー用の指示書
コミットメッセージ用の指示書

※拡張子は *****.md です

settings.json テンプレート

settings.json内で指示書を指定できます。
👇settings.json内の好きな場所に挿入してください。

settings.json(一部)

// Customize GitHub Copilot in VS Code
 // https://code.visualstudio.com/docs/copilot/copilot-customization
 // テンプレート
 // 有効化(デフォルト)
  "github.copilot.chat.codeGeneration.useInstructionFiles": true,
  "github.copilot.chat.codeGeneration.instructions": [ // コード生成の設定です。
    {
      "file": ".copilot-codeGeneration-instructions.md"
    },
  ],
  "github.copilot.chat.testGeneration.instructions": [ // テストコード生成の設定です。
    {
      "file": ".copilot-test-instructions.md"
    },
  ],
  "github.copilot.chat.reviewSelection.instructions": [ // コードレビューの設定です。
   {
      "file": ".copilot-review-instructions.md"
    },
  ],
  "github.copilot.chat.commitMessageGeneration.instructions": [ //コミットメッセージ生成の設定です。
    {
      "file": ".copilot-commit-message-instructions.md"
    },
  ],

※👆ファイル指定式を採用しています。
指示は自然言語でも可能です。

自然言語で指示する場合は、

settings.json

    {
      "text": "初心者にも分かりやすく説明します。"
    },

👆このように書きます。

半永久的に決まっているルールは、VSCodeのsettings.jsonに自然言語で書いておいたほうがいいです。

ファイルを指定している場合は、新しいリポジトリを作成するごとに👇設定が必要です。

リポジトリの直下に指示書を置く。
.github/フォルダを作ってそこに指示書をいれる。

など

例

settings.json

	{
		"text": "常に日本語で分かりやすい言葉を選び、丁寧な表現を心がけます。"
	},
	{
		"text": "初心者にも分かりやすく説明します。"
	},
	{
		"text": "専門用語はできるだけ避け、必要な場合は簡単な説明を加えます。"
	},
	{
		"text": "常に励ましの言葉を添えます。学習意欲が高まるよう工夫します。"
	},
	{
		"text": "最後に、関連するTipsを教えて下さい。"
	},

settings.json

それぞれの指示書に書きます。

コード生成用の指示書

.copilot-codeGeneration-instructions.md

# コード生成に関する指示

このファイルでは、GitHub Copilotがコードを生成する際に従うべき具体的な指示を定義します。

このファイルのルールの優先度は低いです。

## コード生成

* コードを書く前に既存のコードを深くレビューし動作を確認します。

* 正確な例を用いて、簡潔で技術的なTypeScriptコードを記述します。

* 宣言的なJSXを記述します。
* 関数型および宣言型のプログラミングパターンを使用し、クラスの使用は避けます。
* 補助動詞（`isLoading`、`hasError`など）を用いた説明的な変数名を使用します。
* ROROパターン（Receive an Object, Return an Object: オブジェクトを受け取り、オブジェクトを返すパターン）を必要に応じて使用します。
* エクスポートされたコンポーネント、サブコンポーネント、ヘルパー、静的コンテンツ、型でファイルを構成します。
* ディレクトリ名にはケバブケースを使用します（例：`components/personal-information`）。
* コンポーネントは名前付きエクスポートを使用します。
* コンポーネント名にはケバブケースを使用します（例：`my-component.tsx`）。
* 純粋な関数には `function` キーワードを使用します。
* 単純なステートメントには簡潔な構文を使用します。
* 条件文では不要な中括弧を避け、1行文では中括弧を省略します。
* セミコロンは省略します（ただし、文の曖昧さを避けるために必要な場合は使用します）。

## コメント

* コード例を示す際は、各行の目的を詳細なコメントで説明し、実行結果も示します。
* 複雑なロジックには明確で簡潔なコメントを付けます。

## セキュリティ

* データを危険にさらしたり、新たな脆弱性をもたらさないように、あらゆる段階で確認します。

コーディングルールが長くなったら
フロントエンドの指示書(Next.js、TypeScript、TailwindCSS、Shadcn/UI)
バックエンドの指示書(TypeScript、Hono)
DBの指示書(Supabase、Drizzle)
などのように分離させるとよいです。

テスト用の指示書

.copilot-test-instructions.md

# テストに関する指示

このファイルでは、GitHub Copilotがテストコードを生成する際に従うべき具体的な指示を定義します。

## テストファイル

* コンポーネントのテストコードはコンポーネントファイルと同じ場所に置くというコロケーションの考え方を採用します。


## テストコード ユニットテスト

* テストにはvitestとReact Testing Libraryを使用してコンポーネントのユニットテストを記述します。
* テストケースは日本語で書いてください。
* テストは `describe` でグループ化します。
* テストは `it` でテストケースを書いてください。
* 変数名などのフィールド名にはアンダースコアを使用してください。
* テストメソッド名を 'test_' でプレフィックスをつけてください。"
* 等号チェックには 'assertEqual' を使用してください。"
* 不等式チェックには 'assertNotEqual' を使用してください。"
* 真偽チェックには 'assertTrue' を使用してください。"
* 虚偽のチェックには 'assertFalse' を使用してください。"
* テストクラス名の前に 'Test' を付けてください。"
* 例外チェックには 'assertRaises' を使用してください。"
* 依存関係のモックには 'unittest.mock' を使用してください。"

## テストコード 統合テスト

* 重要なユーザーフローには統合テストを実装します。

レビュー用の指示書

.copilot-review-instructions.md

# コードレビューに関する指示

このファイルでは、GitHub Copilotがコードレビューを行う際に考慮すべき具体的な指示を定義します。

* 潜在的なセキュリティリスクがある場合は、追加のレビューを行います。
* コードの可読性を重視してレビューしてください。
* エラーハンドリングが適切か確認してください。
* テストケースが網羅されているか確認してください。

コミットメッセージ用の指示書

.copilot-commit-message-instructions.md

# コミットメッセージに関する指示

このファイルでは、GitHub Copilotがコミットメッセージを生成する際に従うべき具体的な指示を定義します。

* コミットメッセージは短く、要点を押さえたものにしてください。
* 変更内容の概要を明確に書いてください。

2. リポジトリ全体への静的な指示書

静的な指示書
チーム全体で共有するルールを書きます。

使いまわしをするルールです。

このファイルの指示の優先度は低くします。

リポジトリを分析して
使用しているツールの具体的な使用方法を指示します。

指示書の場所

リポジトリ直下

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

3．目的、機能単位の指示書

GitHub Copilotではプロンプトファイルと呼びます。

※プロンプトファイル(*.prompt.md)は毎回指定する必要があります。
この指示書はGitHub Copilotへのドラッグアンドドロップで読み込ませることが可能です。

プロンプトファイル

特定の目的や、単体の機能を作る時用のルールを書きます。
機能を具体的に明確化してGitHub Copilotに説明するために必要です。

使い捨てするルールです。(独自)

利用しているリポジトリを使っている間、
ある程度の期間 AIに指示を与えるというイメージ。
AIとチャットで会話して、会話が終了するまでの間だけ覚えておくルールというイメージです。

このファイルの指示の優先度は一番高くします。

指示書の場所

リポジトリ直下

.github/prompts フォルダ

フォルダ内にプロンプトファイルとして作成します。

※拡張子は *****.prompt.md です

3. プロンプトファイル `*****.prompt.md`

これらは特定の機能やタスクを開発する際に、必要に応じて利用する指示書です。
例えば、特定のReactコンポーネントを作成する場合の指示書は以下のようになります。

例: components/user-profile.prompt.md

components/user-profile.prompt.md

# ユーザープロファイルコンポーネントの作成

## コンポーネントの目的

* ログインしているユーザーのプロフィール情報を表示するコンポーネントを作成します。

他の指示書と違っていたら、この指示を最優先とします。

## 技術要件

* Next.js v15を使用します。
* APIは Hono v4 を使用します。
* Reactを関数コンポーネントとして実装します。
* TypeScript で型定義を行います。
* UIは Radix UI の `<Avatar>` コンポーネントと適切なレイアウト要素を使用します。
* スタイルは Tailwind CSS を適用します。
* ユーザーデータは Supabase から取得します。

※バージョンも指定します。
(Next.js 15が2025年3月の最新バージョン、Next.js 14からの破壊的変更あり
page.tsx や layout.tsx の params や searchParams が Promise で渡されるようになり、データ取得が非同期になりました。これにより、Next.js 14までの同期的なデータ取得処理が動作しなくなります。)



## データ要件

* 以下のユーザー情報フィールドを表示します。

名前 (表示名)
メールアドレス
プロフィール画像 (URL)

## GitHub Copilot への指示

* Supabase のクライアントライブラリを使用して、ユーザーデータを非同期にフェッチする処理を実装してください。
* ローディング状態やエラー状態を適切に処理するUIを実装してください。
* プロフィール画像が存在しない場合のデフォルト表示を設定してください。
* Radix UI のコンポーネントを効果的に組み合わせて、アクセシブルなUIを構築してください。
* Tailwind CSS のユーティリティクラスを使用して、シンプルで見やすいスタイルを適用してください。
* 作成したコンポーネントの Storybook のストーリーファイル (`*****.stories.tsx`) を作成し、様々な表示パターンをテストできるようにしてください。
* vitest と React Testing Library を用いた簡単なユニットテストを作成してください。
例えば、データのローディング状態の表示や、ユーザー情報のレンダリングなどをテストしてください。



## 追加事項(将来の拡張予定)

* ダークモードにも対応できるようなスタイリングを検討してください。
* 将来的な拡張性を考慮し、コンポーネントのpropsを適切に定義してください。

※使い終わったプロンプトファイルは
.github/prompts/completes フォルダを作成し
そこに移動させておきます。 (独自)
削除しても構いません。

ルールの個別具体的な例

例1: `component-style.prompt.md` (特定のコンポーネントのスタイルに関する指示)

component-style.prompt.md

*   目標は、新しいユーザープロファイルコンポーネント (`UserProfile.tsx`) を生成することです。
*   このコンポーネントは、以下の要件を満たす必要があります。
    UIライブラリ: Shadcn UI の `Card` コンポーネントをベースにしてください。
    スタイル: Tailwind CSS を使用して、以下のスタイルを適用してください。
	 *   背景色は `bg-gray-100`
	 *   文字色は `text-gray-800`
	 *   角丸は `rounded-md`
	 *   内側のpaddingは `p-4`
    レスポンシブ: 画面幅が小さい場合は、要素が適切に折り返されるようにしてください。
    必要に応じてFigma参照



### 例2: `api-integration.prompt.md` (特定のAPI連携に関する指示)

* 目標は、`/api/users` エンドポイントからユーザーデータを取得し、それを表示する処理を実装することです。
* 以下の点を考慮してください。
    データ取得: Hono API を使用してデータを取得してください。
    認証: Supabase の認証ヘルパー (`supabase-auth-helpers`) を使用して、認証済みのユーザーのデータのみを取得してください。
    データ形式: APIのレスポンスは以下のJSON形式です。

json
{
  "id": "...",
  "name": "...",
  "email": "..."
}

エラーハンドリング: データ取得に失敗した場合は、適切なエラーメッセージを表示してください。

例3: `design.prompt.md` (設計書に関する指示)

design.prompt.md

### 設計書

* 構想、概要を読んで設計書を書いてください。
	* 構想、概要: [Webアプリ].concept.md
	* 要件定義: [Webアプリ].requirements.md
	* 画面設計書: [Webアプリ].screen.md
	* 画面遷移図: [Webアプリ].screen-transition-diagram.md

* 設計書を docs フォルダ直下に作成してください：
	* 設計書: [Webアプリ].design.md
	* データベース設計: [Webアプリ].db.md
	* データベーススキーマ: [Webアプリ].db-schema.md
	* データベース関連図: [Webアプリ].db-entity-relationship-diagram.md
	* API設計書: [Webアプリ].api.md
	* テスト設計書: [Webアプリ].test.md

* 既存のWebアプリを修正する場合：
	* 既存のリポジトリを参照してWebアプリを開発してください
	* 変更時に設計書も同時に更新してください
* 設計書を作成したら、コードを作成する前にユーザーに設計書のチェックを依頼してください。

プロンプトファイルが長くなる場合は、タスク分解を行い、個々の指示の長さを短くして複数のファイルに分割します。
これは、AIの理解を助けるためです。
また、人間が指示書を作成する際にも、タスク分解を行うことで、タスクの抜け漏れや不足を防ぐことができます。

※ローカルのファイルは指定できますが、外部のファイルを読み込ませようとするとうまくいきません。

例4: 機能とそのテストのプロンプトファイル

動的な指示書（プロンプトファイル）で特定の機能を実装した後、そのテストを実行させ、さらにテストが希望通りに動作するようにいくつかの想定される動作をGitHub Copilotに伝える方法

ステップ1：プロンプトファイルの作成と基本構造

.github/prompts/ フォルダ内に、機能に関連する名前を持つ拡張子 .prompt.md のファイルを作成します（例：user-authentication.prompt.md）。

プロンプトファイルの基本的な構造は以下のようになります：

# [機能の目的や名前]

## テストに関する指示

*   [使用するテストフレームワーク名] を使用してテストを記述してください（例：Jest、vitest、React Testing Library）。
*   [テストの種類] を記述してください（例：ユニットテスト、統合テスト）。
*   テストは \`describe\` でグループ化し、\`it\` でテストケースを記述してください。

## テストで想定する動作

*   **[想定される動作1]** であることをテストで確認してください。
*   **[想定される動作2]** であることをテストで確認してください。
*   （必要に応じてさらに記述）

## テストの実行

*   上記のテストがすべて成功することを確認してください。

ステップ2：具体的な指示と想定される動作の記述例

例えば、ユーザー認証機能を実装した後、そのテストを行いたい場合、user-authentication.prompt.md ファイルに以下のように記述できます。

# ユーザー認証機能のテスト

## テストに関する指示

*   vitest と React Testing Library を使用してコンポーネントのユニットテストを記述してください。
*   認証成功時の処理、認証失敗時の処理、ローディング状態などをテストしてください。
*   テストケースは 日本語 で記述してください。
*   テストは \`describe\` で認証処理に関するグループを作り、\`it\` で個々のテストケースを記述してください。

## テストで想定する動作

*   正しいユーザー名とパスワード が入力された場合、認証が成功し、ダッシュボードにリダイレクトされることを確認してください。
*   誤ったユーザー名 が入力された場合、エラーメッセージが表示されることを確認してください。
*   誤ったパスワード が入力された場合、エラーメッセージが表示されることを確認してください。
*   認証処理中に ローディング 状態が表示されることを確認してください。
*   APIからのエラーが発生した場合、適切な エラーメッセージ がユーザーに表示されることを確認してください。

## テストの実行

*   上記のテストがすべて成功することを確認してください。
*   テストの実行後、成功したテストの数と失敗したテストの数を 日本語 で報告してください。
*   もし失敗したテストがあれば、その理由と修正案を提示してください。

GitHub Copilotで使用可能なAIモデル

2025年3月現在

Claude 3.5
Claude 3.7 sonnet
Claude 3.7 sonnet Thinking
Gemini 2.0 Flash
GPT-4o
o1
o3-mini

AIモデルが受け付けるプロンプトの長さ

Claude 3.5 Sonnet: 約200Kトークン（おおよそ300,000文字に相当）

Claude 3.7 Sonnet: 約200Kトークン（おおよそ300,000文字に相当）

Claude 3.7 Sonnet - Extended Thinking: 約200Kトークン（おおよそ300,000文字に相当）

Gemini 2.0 Flash: 最大1Mトークン（おおよそ1,500,000文字に相当）

GPT-4o: 最大128Kトークン（おおよそ192,000文字に相当）

o1: 最大128Kトークン（おおよそ192,000文字に相当）

o3-mini: 最大200Kトークン（おおよそ300,000文字に相当）

指示書に具体的な例を書くのが難しい時

リポジトリのどこか適当な場所に playground フォルダを作成します。

コンポーネントの例だったら
componentsフォルダの直下に置きます。
そしてお手本になるコンポーネントを書き、
GitHub Copilotにpalygroundフォルダを参考にしてくださいと指示を出します。

例えば、Next.js 15にHonoを導入した時、
APIの最小限のCRUDを書き、APIを利用する時はplaygroundを参考に生成してくださいと指示を出します。

AIにも指示書を書かせる。

例えば、このBlog記事をNotebookLMに読ませて
さらに設計書をよませて
XXXXの機能を開発するので、動的な指示書(プロンプトファイル)を作ってください。
とお願いしたりします。

人間は細かいところまで指示書を書くのがお仕事です。

uithub
👆例えばこのサービスを使います。
似たようなサービスはたくさんありますが
URLを一文字変えるだけで簡単にアクセスできるので気に入っています。

uithub
NotebookLM
👆これらのWebサービスは👇を御覧ください。

私の使用しているAI関連サイト UPDATE 2025年3月 #Gemini - Qiita
https://qiita.com/masakinihirota/items/dc260e90f43a833d0e98

設計書を書くための情報源、市場調査なども
GeminiのDeep Researchに任せます。

https://uithub.com/
https://notebooklm.google.com/
https://gemini.google.com/app

おまけ: GitHub CopilotをMCPで強化する

MCP（Model Context Protocol）は、AIが外部の情報源にアクセスするためのプロトコルです。

例えば、Next.jsやSupabaseのドキュメントといった情報を、AIが理解しやすい形式で接続するためのルールを定めています。

現時点では、GitHub CopilotはMCPに直接対応していませんが、VS Codeの拡張機能を利用することで、MCPサーバーを介して外部情報にアクセスし、GitHub Copilotの機能を拡張できます。

👇適当に検索して星やDL数がちょっと多いもの。
Copilot MCP - Visual Studio Marketplace
https://marketplace.visualstudio.com/items/?itemName=AutomataLabs.copilot-mcp

MCPの概要:
- MCPは、大規模言語モデル（LLM）が様々なデータソースやツールと連携するためのオープンな標準プロトコルです。
- これにより、AIは最新のドキュメントやデータベース、APIなどの外部情報に基づいた、より正確でコンテキストに沿った提案やコード生成が可能になります。
MCPサーバー:
- MCPサーバーは、外部情報とLLMとの橋渡し役を担います。
- 様々なデータソースに対応したMCPサーバーが開発されており、目的に応じて選択できます。
VS Code拡張機能:
- VS CodeでMCPを利用するためには、MCPサーバーと連携する拡張機能が必要です。
- 例として、Clineなどの拡張機能が挙げられます。これらの拡張機能は、MCPサーバーをVS Code上で実行し、GitHub Copilotと連携させることができます。
MCPの利点:
- AIの知識を最新の状態に保つことができます。
- 特定のドメイン知識や企業内の情報など、AIがデフォルトでは持たない情報にアクセスできます。
- より複雑なタスクや、外部システムとの連携が必要な開発を支援できます。
MCPを利用することで、GitHub Copilotをより強力な開発支援ツールとして活用できます。

MCPツール：AI活用の効率化を加速する最先端ツール群

情報収集・分析

Perplexity
最新の情報検索に特化したAI検索エンジンです。従来の検索エンジンとは異なり、AIが情報を解析し、より精度の高い検索結果を提供します。

Firecrawl
複数のウェブサイトをクロールし、最新情報を収集・分析します。Deep Research機能により、競合他社の動向や市場トレンドの把握を自動化します。

個人情報管理

Memory
個人の情報を記憶し、必要な時に提供するAIツールです。個人の知識や経験を蓄積し、効率的な情報活用を支援します。

開発効率化

GitHub MCP
GitHubリポジトリの情報取得、PR作成、Issue管理などをLLMから直接操作できます。開発ワークフローを効率化し、生産性を向上させます。

Sentry
アプリケーションのエラー情報をリアルタイムで取得し、LLMが自動的に解析・修正します。デバッグ作業を効率化し、アプリケーションの安定性を高めます。

ビジネス支援

Stripe MCP
サブスクリプション課金や決済管理を自動化します。煩雑な決済業務を効率化し、ビジネスの成長を支援します。

Supabase MCP
ユーザーデータやコンテンツのデータベース操作を自動化します。データベース管理の負担を軽減し、開発者はより重要な業務に集中できます。

GitHub Copilotに頼る前に

GitHub Copilotでゼロから作るのもいいですが、
自分は使い慣れた使用するツールや環境変数は
自分でセットアップしておいたほうがいいと思っています。
自分はテンプレート(スタータ＋自分の慣れたツール)を作って、それを元にGitHub Copilotを利用するつもりです。

設計書とプロンプトファイル

指示書をうまく使うために

要約 3行

設計書と指示書を作成します。

設計書からタスクリストを作成し、そのタスクが大きければ処理しやすい大きさにタスク分解しプロンプトファイルとして管理します。

プロンプトファイルの通りにタスク単位でGitHub Copilotにコードを書いてもらい、テストと検証を行います。このサイクルを繰り返します。

目的

複雑な機能を持つWebアプリ開発において、GitHub Copilotを活用し、効率的かつ高品質な開発を実現する。

ある程度の規模の設計書をGitHub Copilotに直接読み込ませると、開発者が制御不能におちいります。
そのため、設計書から機能単位で分割したタスクリストを作成し、各タスクに対応する詳細な指示をまとめた「プロンプトファイル」を作成します。
👆プロンプトファイルに相当します。

ワークフロー

設計書作成

Webアプリの設計書を作成します。

開発環境構築

開発初期環境（スターターキット等）を準備します。
開発に必要なツールやライブラリを追加します。
ディレクトリ構成、基本的なコンポーネント、共通関数など、Webアプリの土台となるテンプレートを作成します。
テンプレートに基本的な最小限の動作を実装し、ユニットテストなどのテストコードを作成します。

タスク分解とプロンプトファイル作成

設計書から機能を分割し、タスクリストを作成します。
タスクリストの各項目が大きすぎる場合は、さらにタスクを分割し、GitHub Copilotで扱いやすい粒度に調整します。
各タスクの詳細な仕様、バージョン情報など、GitHub Copilotへの指示を記述します。
これらの情報を「プロンプトファイル」にまとめます。
プロンプトファイルはタスクリストの各項目に対応する1機能単位で分けてGitHub Copilotに読み込ませます。

AIによる実装

作成したテンプレートとプロンプトファイルをAIに読み込ませ、機能の実装をGitHub Copilotに行わせます。
実装したものをドキュメントとして出力します。

テストと検証人間による理解

ユニットテスト、結合テスト、E2Eテストなど、適切なテストを実施し、実装された機能が設計通りに動作するか検証します。
必要に応じて修正、改善を行います。

※テストは人間のためのものであり、GitHub Copilotにコードを書くのをすべて任せるのなら最低限のテストがあればいいです。

反復

プロンプトファイルに基づく実装、テスト、検証のサイクルを繰り返し、Webアプリ全体を構築していきます。

プロンプトファイルの役割

設計書と実際のコーディングの中間段階として、GitHub Copilotに対する詳細な指示書となります。
機能単位で分割されたタスクと、その実装に必要な情報をまとめます。
GitHub Copilotによる実装結果を検証するための基準となります。
GitHub Copilotとの円滑な連携を可能にするための重要な架け橋となります。

プロンプトファイルのポイント

人間の手による制御のため、人間とGitHub Copilotとのバランスを考えます。
開発者は設計とタスク管理に集中し、AIは実装に特化させることで、効率的な開発を実現します。
詳細なプロンプトファイルを作成することで、GitHub Copilotによる実装の精度と効率を高めます。
テストを重視し、品質の高いWebアプリを構築します。

テスト駆動開発との相性

※注意似ているけど全く違うものという話です。

GitHub Copilotに与える指示書、プロンプトファイルに沿って開発してく手法をAI駆動開発とします。

再考テスト駆動開発 #TDD - Qiita
https://qiita.com/masakinihirota/items/0a714d729d14da5cc7f4

AI駆動開発とテスト駆動開発の相性の悪さ

問題

テストリストの粒度と進め方の不整合

GitHub Copilotに任せるタスクと、テスト駆動開発のテストリストは全く違うものです。
タスクリスト分解したものとテストリストの大きさを無理やり合わせるのは開発が非効率です。

テストの煩わしさ

人間主導の開発においてはテストが非常に有効ですが、GitHub Copilotが生成したコードに対して同様のテストを行うことが非効率です。

設計プロセスにおける人間との考え方の違い

テスト駆動開発はテストを先に書き設計を重視しますが、AI駆動開発は指示に基づきコード生成が先行します。
GitHub Copilotによるコードの生成は、テスト容易性を考慮した設計が必ずしも行われず、人間主導の設計との間にギャップが生じます。

GitHub Copilotが自動修正してしまう問題

GitHub Copilotがコードを自動で修正するので、人間がテスト駆動開発でステップを回すとは意味合いが変わってきます。

テストの目的とタイミングのずれ(独自)

テスト駆動開発はテストで仕様を明確化し設計を促進しますが、AI駆動開発ではコード生成後のテストを書くというものです。
回帰テストに重点が置かれ、初期段階のフィードバックや設計への誘導が不足します。

リファクタリングの考え方の違い

テスト駆動開発では、テストで動作を保証しつつ可読性・保守性を高めるリファクタリングをします。一方、GitHub Copilotの自動修正は意図しない変更を招き、テスト駆動開発の安全なリファクタリングと矛盾します。

学習コストと導入の障壁

GitHub Copilotは設計書から指示書を生成しますが、そこから更にテスト駆動開発の考えを導入することは学習コスト等がかかり開発が遅れます。

コストの問題

従量課金制のAIモデルを利用する場合、テストコードの生成や実行にかかるコストが追加で発生する可能性があります。

手順を変える

GitHub Copilotに動的な指示書でコードを生成させた後、人間がテストを書く場合、そのテストの主目的はレグレッションテストとなります。
これは、GitHub Copilotによるコード生成を「変更」と捉え、既存の機能が意図せず損なわれていないか、そして生成されたコードが設計書通りに動作するかどうかを確認するためです。

既存機能の維持と設計意図の確認、安定性の確保が主な役割です。
テストの重点は、設計検証から機能確認へと変化します。
人間はGitHub Copilotによる生成コードの品質保証を担います。
自動テストの重要性やコード変更による問題の早期発見の意義があります。
•
この手順のようにテストは事後的な検証が中心となります。

最後に

指示書に正解はありません。開発する目的、プロジェクトの規模、チームの構成などによって、最適な指示書は異なります。
重要なのは、以下の点を考慮しながら、自分たちのプロジェクトに合った指示書を作成し、継続的に改善していくことです。

指示書作成のポイント

目的の明確化
何を実現したいのか、具体的な目標を明確に記述します。
具体性の追求
抽象的な表現を避け、具体的な要件や指示を記述します。
コード例や設計図などを積極的に活用します。
優先順位の明確化
複数の指示がある場合は、優先順位を明確に記述します。
継続的な改善
指示書の効果を定期的に評価し、改善を繰り返します。
チームメンバーからのフィードバックを積極的に取り入れます。
柔軟性
状況の変化に応じて、指示書を柔軟に修正します。
完璧な指示書を目指すのではなく、状況に合わせて変化できるようにします。

参考

基本設計について #ER図 - Qiita
https://qiita.com/hukuryo/items/97797a91d7e2ee0bcabc

👆設計書を作る参考。

第二版 VSCode の Rules for AI 全体のルール設定翻訳 GitHub Copilot

この記事は、GitHub Copilotの最新機能と指示書の活用方法について解説します。

最新情報

GitHub Copilotの指示書の種類

GitHub Copilotでは、以下の3種類の指示書を利用できます。

VSCodeの設定 (settings.json)
- VSCode全体で適用される固定ルールを記述します。
- 例: 日本語での説明、初心者向けの表現など。
リポジトリ全体の指示書 (.github/copilot-instructions.md)
- プロジェクト全体で共有するルールを記述します。
- 例: 使用する技術スタック、コーディング規約、テスト方針など。
プロンプトファイル (.github/prompts/*.prompt.md)
- 特定のタスクや機能に関する動的な指示を記述します。
- 例: 特定のコンポーネントの作成、API連携の実装など。

プロンプトファイルの活用

プロンプトファイルは、タスクごとに詳細な指示を記述するためのファイルです。以下のような命名規則を使用します。

.github/prompts/[YYYYMMDD]-[タスクID]-[タスク名]-[タスクの種類].prompt.md

例:

20250401-001-user-authentication-feat.prompt.md
20250401-002-api-integration-test.prompt.md

MCP (Model Context Protocol) の利用

MCPを活用することで、GitHub Copilotが外部情報（ドキュメント、API仕様など）にアクセスし、より正確な提案を行えるようになります。

MCPの設定ファイル: .vscode/mcp.json
利用例: SupabaseやStripeのドキュメントを参照しながらコードを生成。

最新のAIモデル

2025年4月現在、以下のAIモデルが利用可能です。

Claude 3.7 Sonnet
Gemini 2.0 Flash
GPT-4o

これらのモデルは、プロンプトの長さや処理能力が向上しており、大規模なプロジェクトにも対応可能です。

指示書作成のベストプラクティス

具体性を重視: 抽象的な表現を避け、具体的な要件を記述します。
優先順位を明確化: 複数の指示がある場合は、優先順位を明確にします。
継続的な改善: 指示書の効果を定期的に評価し、改善を繰り返します。

参考リンク

この記事は、GitHub Copilotの最新機能を活用し、効率的かつ高品質な開発を実現するためのガイドです。

VSCodeのエージェントモード？

GitHub Copilot in VS Code
https://code.visualstudio.com/docs/copilot/overview

公式ドキュメント

追記の前提
今のAIは大雑把に分けると
Chat 会話モード
Edits 編集モード
Agent mode 代理人モード
の3種類があります。

GitHub Copilotの種類
GitHub Copilot
GitHub Copilot Chat
GitHub Copilot CLI
GitHub Copilot Edits
GitHub Copilot Agent mode

VSCode のAI(土台だけ、操作の共通化？)
VScode Copilot Chat
VScode Copilot Edits エージェントモードに対応
※複数の同時編集セッションは未対応(並列にEditsは使えない)
#codebase はクエリに関連するコンテキストを見つけてくれます。

AIは1,2年前から進化を続けていて、AIとの会話、1ファイルの編集、複数ファイルの編集、一部、もしくは全体をAIにコードを提案してもらう代理人モードができるようになり、段々と便利になってきました。

今回の追記は、これまでは色んな会社がそれぞれ独自にAIを利用する方法を探っていたのが、「VScode共通の操作」の実装でどのAIも同じに使えるようになります・・・かもしれない。

それぞれ独自の指示書の設定やチャット枠、履歴がありました。

たとえばVScodeのAI、Agent modeの拡張機能は

Cline
Roo Code
Gemini Code Assist
その他
等群雄割拠の時代に突入していました、今回のVSCodeのアップデートで、操作や設定の共通化がされるのではないでしょうか？
MCPの利用など、独自設定は残るかもしれません。
これら独自の拡張機能開発者が、VSCodeのAgent modeでの操作を利用しない可能性もあります。

VScode Agent mode

GitHub Copilot Agent mode
とは別に
VScodeでAgent modeが利用できるようになります。
※VScode Insidersで試験的に実装中

つまりこれからはそれぞれのAIモデルの実装や独自の拡張機能に依存せず、「VScode共通の操作」で各AIのエージェントモード (それ以外のモードも)が使えるようになります・・・かもしれない。

Use agent mode (preview)
https://code.visualstudio.com/docs/copilot/copilot-edits#_use-agent-mode-preview

VScodeのエージェントモードはファイルをいちいち指定する必要がなくなるそうです。

会話の共有

これまでは、GitHub Copilotでは
GitHub Copilot chat
GitHub Copilot Agent mode
ではそれぞれ会話の共有はされていませんでしたが
VScode Copilot Chat
VScode Copilot Edits
これらを利用することで、これからは会話の共有がされるようになります・・・かもしれない。

Copilot Chatでアイデアを練り、
Copilot Editsでコードを生成することができるようになります・・・かもしれない。

Copilot Edits
Send a chat request to Copilot Edits
https://code.visualstudio.com/docs/copilot/copilot-edits#_send-a-chat-request-to-copilot-edits