GitHub Copilot Agentを使っていて、「もう少しプロジェクトの書き方に合わせてくれたらいいのに」と感じることがありました。デフォルトでは汎用的なコードを提案してくれますが、プロジェクト固有の規約やパターンまでは理解していないのが現実です。
instructionsファイルを使うことでこの課題を解決できるのではないかと考え、実際に設定してみました。実用性を重視した観点から、その手順と効果を共有したいと思います。
instructionsファイルの仕組み
instructionsファイルは、AIにプロジェクトの文脈・制約・品質基準を伝える設定ファイルです。プロジェクト固有の書き方やルールをAIに教えることで、より適切なコード提案を受けられるようになります。
実際に感じられた効果
実際に設定してから、いくつかの改善を感じられました。プロジェクトで使っている技術スタックやアーキテクチャパターンを理解したコード提案が増え、命名規則や文体も統一されるようになりました。テストやアクセシビリティの考慮も自動的に含まれるため、手直しの回数が減りました。
VS Code設定の確認
まず最初に躓いたのが、この機能がデフォルトで有効になっていないことでした。VS Codeでinstruction filesの機能を有効化する必要があります。
設定画面で「copilot instruction」を検索し、GitHub › Copilot › Chat › Code Generation: Use Instruction Files（github.copilot.chat.codeGeneration.useInstructionFiles）にチェックが入っているか確認してください。この設定が無効だと、ファイルを作成してもCopilotに認識されません。
ファイルの配置
instructionsファイルは特定の場所に配置する必要があります：
プロジェクトルート/
├── .github/
│ └── copilot-instructions.md ← ここに配置
├── src/
├── package.json
└── README.md
ファイル名は copilot-instructions.md でなければなりません。VS Codeがこの名前で認識するため、他の名前では機能しません。
ファイルの書き方
instructionsファイルはMarkdown形式で書きます。実際に使っている構成例を紹介します：
---
mode: agent
---
# プロジェクト向けCopilot指示書
## プロジェクト概要
このプロジェクトは、Next.js + TypeScriptで構築されたWebアプリケーションです。
### 技術スタック
- Next.js 15（App Router）
- TypeScript
- Tailwind CSS
- Playwright（E2Eテスト）
## コーディング規約
### ファイル命名規則
- コンポーネント: PascalCase（例: `UserProfile.tsx`）
- ユーティリティ: camelCase（例: `dateUtils.ts`）
- ディレクトリ: kebab-case（例: `user-profile/`）
### 品質基準
- すべてのコンポーネントにはPropsの型定義を必須とする
- アクセシビリティ（WCAG 2.1 AA）準拠
- レスポンシブデザインの実装
ファイルの先頭に mode: agent を指定することで、Copilot Agent用の指示であることを明示します。
まとめ
instructionsファイルを設定することで、Copilotがプロジェクト固有の書き方を理解してくれるようになりました。初期設定は少し手間ですが、長期的に見ると開発効率の向上につながると思います。
プロジェクトの規模や複雑さに応じて、instructionsの内容を調整していくのが現実的なアプローチでしょう。まずは基本的な設定から始めて、必要に応じて詳細を追加していくことをおすすめします。
