VSCodeのGitHub Copilotに「プロジェクト横断」で使えるカスタム指示を読ませたい

VSCodeのGitHub Copilotにて、複数のプロジェクトで共通して使えるカスタム指示(.instructions.md)のつくり方を知ったので共有します。これをすることで

• 手間削減: 新しいプロジェクトを作るたびに.instructions.mdをコピーする必要がない

• 秘匿性: リポジトリに個人的な好みの指示を含めたくない場合に便利

• 一貫性: どのプロジェクトでも自分の書き方（命名規則やテスト方針）をCopilotに徹底させられる

などのメリットがあります。

カスタム指示とは

カスタム指示とは、GitHub Copilotに与えるMarkdown形式の指示書です。
簡単な例でいえば.instructions.mdに「日本語で回答して」と一度書いておけば(ほとんど毎回)日本語で回答してくれますし、「関西弁で回答して」と書いておけば関西弁で回答してくれます。
実際にはコーディングにおける命名・コメントの規則やテスト方針などを書く場合が多いのではないでしょうか(真面目な例は後述します)。

関西弁で話すようになる.instructions.mdの例

.instructions.md

---
applyTo: '**'
---

# 基本
- 日本語で応答すること
- 関西弁で話すこと

カスタム指示のつくり方

カスタム指示のファイルは

1. 指示を.instructions.mdに書いてプロジェクトの.github/ディレクトリに入れる(プロジェクト関係者と共有)
2. 指示を.instructions.mdに書いてVSCodeのユーザプロファイルに保存する(ユーザごとに個別)
3. 指示をAGENTS.mdに書いてワークスペースのルートディレクトリまたはサブディレクトリに置く(プロジェクト関係者と共有)

の3通りの方法で作成できます。本記事の目的である、プロジェクト横断で使える.instructions.mdはVSCodeのユーザプロファイルに保存する方法なのでそちらをメインで紹介し、その他の方法は割愛します。

AGENTS.mdをサブディレクトリに置く方法は現在、実験的(experimental)機能であり設定の変更が必要です

カスタム指示をユーザプロファイルに作成する

.instructions.mdをユーザプロファイルに作成する方法を説明します。

ファイルの作成

まずVSCodeの「チャット」ウィンドウの上部から歯車アイコンをクリックします(「チャット」ウィンドウが無ければCtrl+Alt+IまたはCtrl+Iで出せます)

つぎに、出てきたメニューの「指示(Chat Instructions)」を選択します。

画面上部にポップアップが現れるので、「新しい命令ファイル(New instruction file)」を選択します。

命令ファイルの保存場所として"User Data"を選択します。

ここまで行うとユーザプロファイルに.instructions.mdが作成されるので内容を好きに設定します。

カスタム指示の書き方

デフォルトでは以下のような内容で作成されるかと思います。

instructions.md

---
applyTo: '**'
---
Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.

ファイル冒頭のapplyTo: '**'は.instructions.mdの適用範囲を示すglobパターンです。
globパターンの指定方法にはたとえば

applyTo	適用範囲
'**'	すべてのファイル・チャット
'**/*.py'	.pyで終わるファイル(Pythonファイル)
'**/*.ts,**/*.tsx'	.ts,.tsxで終わるファイル(TypeScriptファイル)
'docs/**/*.md'	docsディレクトリ内にある拡張子が.mdのファイル(Markdownファイル)

などがあります。

指示本文はapplyTo:の下にMarkdown形式で書きます。試しに今回は「ござる」口調で話してもらうよう指示してみます。

.instructions.md

---
applyTo: '**'
---

# 基本
- 日本語で応答すること
- 語尾に「ござる」をつけて話すこと

カスタム指示を使う

.instructions.mdをユーザプロファイルに作成した状態でCopilotとチャットすると、カスタム指示をCopilotが自動で参照します。
実際にチャットしてみるとカスタム指示通りにCopilotが「ござる」をつけて話してくれました！しかもユーザプロファイルに保存しているのでどのプロジェクトでもこのカスタム指示が適用されます。

WindowsではC:\Users\ユーザ名\AppData\Roaming\Code\User\prompts\に.instructions.mdが作成されていました。

開発に役立つ.instructions.mdの例

もう少し開発に役立つ.instructions.mdの例として、普段使用している指示を折りたたみ内に示しておきます(いろいろなサイトの内容を継ぎ接ぎしています)。全言語共通のルール(.instructions.md)とPythonで開発する際のルール(.python-instructions.md)に分けて管理しています。

共通(.instructions.md)

.instructions.md

---
applyTo: '**'
---

# 基本
- 日本語で応答すること
- 必要に応じて、ユーザに質問を行い、要求を明確にすること
- 情報が不足している場合、推測で実装を行わずに、ユーザに確認するかドキュメント・Webページ等のfetchを行うこと
- 作業後、作業内容とユーザが次に取れる行動を説明すること
- コマンドの出力が確認できない場合、 get last command / check background terminal を使用して確認すること


# 開発
- 記載されている以上の実装を絶対に行わない
- 既存のコードスタイル、命名規則、アーキテクチャに従うこと
- 実装は計画の後に、ユーザの承認を得てから行うこと
- 計画には実装方針や使用する関数・ライブラリや作成する関数・クラス等の具体的な内容を含めること
- 作業項目が多い場合は、段階に区切り、git commit を行いながら進めること

Python(.python-instructions.md)

.python-instructions.md

---
applyTo: '**/*.py'
---
# Pythonコーディング規約

## Pythonに関する指示

- 各関数には、明確で簡潔なコメントを書いてください。
- 関数には内容を表す名前をつけ、型ヒント（type hint）を必ず含めてください。
- PEP 257の規約に従ってdocstring（ドキュメンテーション文字列）を提供してください。
- 型アノテーション（List[str]やDict[str, int]など）にはtypingモジュールを使用してください。
- 複雑な関数は、より小さく管理しやすい関数に分割してください。

## 全般的な指示
- 常に読みやすさと明確さを最優先してください。
- アルゴリズム関連のコードには、使用したアプローチ（手法）の説明を含めてください。
- 保守性（メンテナンスのしやすさ）を考慮したコーディングを心がけ、特定の設計判断をなぜ行ったのかをコメントに残してください。
- エッジケース（境界値や例外的なケース）を処理し、明確な例外処理を記述してください。
- ライブラリや外部依存関係については、その用途と目的をコメントに記載してください。
- 一貫した命名規則を使用し、言語固有のベストプラクティスに従ってください。
- 簡潔で効率的、かつその言語らしい（idiomatic）コードを書き、同時にそれが理解しやすいものであるようにしてください。

## コードスタイルとフォーマット
- PythonのスタイルガイドであるPEP 8に従ってください。
- 適切にインデント（字下げ）を行ってください（インデントの各レベルには4つのスペースを使用してください）。
- 1行の長さが79文字を超えないようにしてください。
- 関数とクラスのdocstringは、defまたはclassキーワードの直後に配置してください。
- 関数、クラス、およびコードブロック間には、必要に応じて空行を挿入し、区切りを明確にしてください。

## エッジケースとテスト
- アプリケーションの重要な処理経路（クリティカルパス）については、必ずテストケースを含めてください。
- 空の入力、無効なデータ型、大規模なデータセットといった一般的なエッジケースを考慮してください。
- エッジケースに関するコメントと、その場合の期待される動作（ふるまい）を記述してください。
- 関数の単体テスト（ユニットテスト）を作成し、そのテストケースを説明するdocstringを記述してください。

## ロギング
- loggingモジュールを使用して、重要なイベント、エラー、警告をログに記録してください。
- ログメッセージは明確で説明的なものにし、時刻やログレベル，実行ファイルなどの関連情報を含めてください
- ログは標準出力とファイルの両方に出力するように設定してください。
- ログのコンフィギュレーションは、init_logging関数などの専用関数にまとめてください。

## 実行
- 実行はuvを使用して行うこと

## 適切なドキュメントの例
```python

def calculate_area(radius: float) -> float:
    """
    半径を指定して円の面積を計算します。
    
    Parameters:
    radius (float): 円の半径。
    
    Returns:
    float: 円の面積 (π * radius^2)。
    """
    import math
    return math.pi * radius ** 2
  

Awesome-Instructions

awesome-copilotリポジトリのAwesome Instructionsのページ
を覗くと便利なカスタム指示がたくさんあるのでこちらも役立つかもしれません。

参考文献