はじめに
こんにちは。
株式会社サイバーセキュリティクラウド SIDfm 開発部門の大谷です。
当社では積極的に AI 活用を進めており、脆弱性管理システム「SIDfm」の開発でも、Gemini や GitHub Copilot を日常的に利用しています。
本記事では、GitHub Copilot Chat をより使いやすくするための設定ファイル .instructions.md などについて、実例を交えながら紹介します。
Point
- リポジトリの内容を
.instructions.mdに書きましょう。 - 役割や会話スタイルは
.agent.mdに書きましょう。 - 複数リポジトリの共通内容は
User Data下に書きましょう。
Reason
.instructions.mdとは
AIに与える「指示」をまとめた設定ファイルです。
以前はcopilot-instructions.mdが用いられていましたが、
現在は.instructions.mdが一般的になりつつあります。
このファイルを整備することで、次のようなメリットが得られます。
- リポジトリのアプリがどういう目的、経緯で作成されたものかを毎回説明しなくて良い。
歴史的経緯などからあえて変わった設計になっている場合、AIがベストプラクティスに修正しようとしてくるのを訂正する手戻りが減ります。 - 調査や実装に掛かる時間が減る。
どのファイル、ディレクトリがどのロジックを行っているかを書いておくことで、それに基づいた素早い調査が可能になります。 - 自然言語で記述できるため、エンジニア以外の方でも内容を理解しやすい。
リポジトリのドキュメント、つまりREADME.mdとして読むことができます。
.agent.mdとは
AIに与える「エージェントとしての役割」をまとめた設定ファイルです。
Claudeで使用されるAGENTS.mdとは異なります。
以前は.chatmode.mdとして用いられていました。
現在は.chatmode.mdを作成すると、「Chat modes have been renamed to agents.」と表示され、.agent.mdにリネームするよう促されます。
.agent.mdを書くと、以下のようなメリットがあります。
- 「日本語で」「
rm禁止」といった、応答に関する指示を毎回書く必要が無くなります。
特に、毎回「あなたはプロのエンジニアです」「あなたは統計調査歴10年です」といった長文のペルソナ設定を行う際に、ブレの無い設定ができるようになります。 - どのモデルを使用するかも決定できるので、誤ってプレミアムモデルを使ってしまい、プレミアムリクエストを浪費するといった事態を減らせます。
その他
この他に.prompt.mdがあります。
という使い方のようですが、現時点ではあまり恩恵を感じられていないため、今回は割愛します。
Example
1. ファイル作成
VSCodeで適当なリポジトリを開き、チャットタブの歯車マークをクリックし、「指示」を選択します。
（アップデートを適用していないと表示されないことがあります）
GitHub Copilot Chatウィンドウ内の歯車マークをクリックするとポップアップが表示される
「新しい命令ファイル…」を選択します。
ここでは、新しい命令ファイル...を選択する
命令ファイルを作成する場所を選択します。
.github/instructionsを選んだ場合、（プロジェクトルート）/.github/instructions下に作成されます。
これらはそのリポジトリ内でのみ適用されます。
User Data下を選んだ場合、VSCodeのユーザ設定フォルダ下に作成されます。
（自分の環境では/Users/（ユーザ名）/Library/Application Support/Code/User/prompts でした）
これらは後述するapplyToで明示しない限り、全ファイルに適用されます。
ここでは、.github/instructionsを選択する
どちらかを選択すると、最後にファイル名を聞かれます。
適当な命名をしてEnterを押せば、（ファイル名）.instructions.mdが作成されます。
Custom Agentsなども同様の方法で作成できます。
2. instruction記述
まずは.instructions.mdを記述しましょう。
初期状態は以下のようになっているはずです。
---
applyTo: '**'
---
Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.
applyTo には適用するファイルやディレクトリを書きます。
**.（拡張子） と書くことで、指定の拡張子付きファイルにだけ適用できます。
（ディレクトリ名）/** と書くと、指定ディレクトリ下の全ファイルに適用できます。
また、シングルクォーテーション内でカンマを使うと、複数ファイルを指定できます。
---
applyTo: '**.rb, **/SIDfm/**'
---
以下は`SIDfm`ディレクトリ下にあるファイル、または全てのrubyファイルに適用する指示です。
特に、User Data下に.instructions.md を配置する場合はapplyTo に気を使う必要があります。
そのままだと全てに適用されるため、意図しない指示が含まれてしまいます。
意図しない指示はコンテキストの浪費にもなるため、慎重に扱いましょう。
一方で、リポジトリ内でも applyTo を細かく設定しておくと、曖昧なチャット入力であっても適切な制約が自動的に適用され、不要な指示が混ざりにくくなります。
その結果、コンテキストの無駄遣いを防ぎ、回答精度の向上につながります。
applyTo が書けたら、あとはマークダウンで指示を書いていくだけです。
各リポジトリの説明や、コンテナなどの構成、実行コマンドなどの環境固有の構成を書きましょう。
---
applyTo: '**/ruby-mcp/**'
---
# このリポジトリ
このリポジトリはModel Context Protocol（以下、MCP）サーバのソースコードを管理しています。
## MCP
このリポジトリは、[MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk)を使用しています。
## 開発方針
- テスト駆動開発で行います。
- **必ず1つのテストスクリプトをまず追加し、それを元に実装を追加してください。**
- **テストは必ず`rails test`コマンドで実行してください。Rubyスクリプト単体での実行は禁止です。**
## データベース
リポジトリが使用する主なデータベースはDockerコンテナ`DB_YYYY-MM-DD`です。
データベース名は`MCP_DB`、ユーザロール名は`MCP_DBUSER`です。
**データベースの編集は絶対に禁止です。**
3. agent記述
次に.agent.md を書きましょう。
初期状態は以下のようになっているはずです。
---
description: 'Describe what this custom agent does and when to use it.'
tools: []
---
Define what this custom agent accomplishes for the user, when to use it, and the edges it won't cross. Specify its ideal inputs/outputs, the tools it may call, and how it reports progress or asks for help.
description にはそのagentの説明文を書きます。
マウスオーバーしたときに表示される文です。
マウスオーバーすると説明文が表示される
tools にはこのagentが使用できる機能を書きます。
全てのツールを有効にする場合は単に’*’ を入れればよいですが、読み取り専用にする場合や、コンテキスト浪費を抑えたい場合は、必要なツールのみを書きましょう。
tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos']
この他に、デフォルトでは書かれていないmodel というものがあります。
これは、そのagentを選択すると、AIモデルも自動的にそれに変更される、というものです。
コーディング用agentでは「Claude Sonnet 4.5」を、推論用agentでは「GPT-5」を、というような使い分けをしたいときに役立ちます。
model: Claude Sonnet 4.5 (copilot)
以上が書けたら、あとはマークダウンでペルソナを書いていくだけです。
「常に日本語で返答してください」「単純明快な回答をしてください」といったスタイルを自分で書くのも良いですし、GitHubやGistにあるものを使用しても良いかもしれません。
---
description: general protocol
model: Claude Sonnet 4.5 (copilot)
tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos']
---
- **必ず日本語で応答してください。**
- **必ず以下のスタイルを遵守してください。**
Point
-
.instructions.mdを書くと、人間とAI両方が読めるドキュメントになります。
AIが実装を行う際に自然と従うようになるため、コードに一貫性が持たせられます。
人間が迷ったときはそれを見ることで、実装方針を思い出せます。
人間とAI両方が使うため、必然的にメンテナンスが必要となり、ドキュメントとしての鮮度も自然と保たれ、オンボーディングにも役立ちます。 -
.agent.mdを書くと、AIエージェントを用いた開発効率が良くなります。
AIの変な実装に対する指摘、AIの英語コメントをいちいち翻訳する、長文のペルソナを毎回設定するといった無駄な手間を省くことができます。
特にAgentモードを多用する人には恩恵が大きいでしょう。
おわりに
使いこなすと様々な恩恵がありますが、チーム共有する際のメンテナンス方法や、どのくらいの単位で分けるか、など運用保守の課題はたくさん出ると思います。
まずは個々人で運用しながら育て、十分に成熟した段階でチーム全体の方針にすり合わせる――そのような運用が取り組みやすいのではないかと考えています。
弊社のプレミアムリクエスト使用率1位の方でも「インストラクションズエムディー？って何ですか？」と言っていたので、この記事をきっかけにもっと多くのリポジトリに普及して、運用保守のノウハウが増えると嬉しいです。
Discussion