はじめに
こんにちは。アイスタイルにて会員基盤の運用保守や機能改修を担当しているyukawacです。
近年、業務におけるAI活用の機会が増えてきました。
私の所属する環境ではGitHub Copilot（以下、Copilot）のBusinessプランを利用でき、最近のコーディングはCopilotを前提として進める場面が増えています。
その中で、「Custom Instructions（リポジトリ単位でCopilotに指示を与える仕組み）」を知りました。
これまでに作成してきたシステム開発におけるコーディング規約をCustom Instructions化すれば、人間にとって読みやすい形を保ちつつ、Copilotにも同じルールを参照させられるのではないかと考えました。
この記事では、既存のコーディング規約をCustom Instructions化するまでに、どの順番で整備し、どのようなファイルを用意したかを導入手順としてまとめます。
Custom Instructionsとは
公式ドキュメント： GitHub Copilot のリポジトリ カスタム命令を追加する
要点は次のとおりです。
- リポジトリ単位で、Copilotに対する指示（方針・ルール）を与えられる
- 指示はMarkdownで記述し、リポジトリ全体向けは
.github/copilot-instructions.mdに、特定範囲向けは.github/instructions/*.instructions.mdに作成する - 特定範囲向け指示ファイルには
applyToを指定でき、特定ディレクトリ／特定ファイルにのみに適用することも可能
コーディング規約からCustom Instructions化するまでの流れ
Custom Instructionsの整備自体もCopilotのAgentモードを活用し、次の3ステップで進めました。
すでにコーディング規約資料のあった、メイン言語がJavaのリポジトリで実施しました。
- Custom Instructionsを作成するためのCustom Instructionsを整備
- コーディング規約とリポジトリのコードをCopilotに読み込ませ、
*.instructions.mdの分割案を提示させる - 分割案に沿って
*.instructions.mdを1ファイルずつ生成し、人とCopilotで調整しながら完成させる
1. Custom Instructionsを作成するためのCustom Instructionsを整備
Custom Instructions化そのものもCopilotを活用して進めたかったため、先に土台となるinstructionsを用意しました。
- instructions.instructions.md
- 指示ファイルの型（frontmatter、章立て、文体、例の出し方、検証手順）
- java.instructions.md
- Javaの基本方針（Optional、命名、JavaDoc、よくあるバグパターン、静的解析導入の考え方）
- springboot.instructions.md
- Spring Bootの方針（DI、設定外部化、ログ、入力バリデーション、ビルド・検証の基本）
- markdown.instructions.md
- ドキュメント作成ルール（見出し、リスト、リンク、画像alt、テーブル、行長など）
- self-explanatory-code-commenting.instructions.md
- コメント方針（WHATを書かずWHYを書く、古いコメントを残さない、注釈タグの使い分け）
- taming-copilot.instructions.md
- 最上位ルール（ユーザー指示の最優先、時点依存情報は事実確認、変更は外科的に最小、など）
参考資料（Custom Instructionsの例集）：awesome-copilot/instructions
2. コーディング規約とリポジトリのコードをCopilotに読み込ませ、*.instructions.mdの分割案を提示させる
コーディング規約（mdファイルや文章）とリポジトリのコードを、Copilotチャットで指示して読み込ませ、作るべき*.instructions.mdの分割案（ファイル一覧と役割）を提示させました。
プロンプト例：
このリポジトリの、リポジトリ用のCustom Instructions（instructions.mdファイル）を作成したいです。
まずは、どのような`*.instructions.md`を作ればよいか、リポジトリのコードやコーディング規約を確認して考えて、一覧に出してください。
足りない情報がありましたら、尋ねてください。
Copilotが出した分割案の例
リポジトリの構造まとめ
技術スタック: ...略...
ファイル数: ...略...
情報収集が完了しました。リポジトリの構造を把握できました。以下に提案をまとめます。
プロジェクト固有インストラクション（8ファイル）
| ファイル | 対象 | 説明 |
|---|---|---|
| web-controller.instructions.md | **/controller/**/*.java |
WEB画面用Controller実装 |
| api-controller.instructions.md | **/api/controller/**/*.java |
REST API Controller実装 |
| service.instructions.md | **/service/**/*.java |
Service層実装 |
| database-dao.instructions.md | **/dao/**/*.java, **/*.sql |
DAOとSQLファイル |
| database-entity.instructions.md | **/entity/**/*.java |
Entity実装ガイド |
| thymeleaf.instructions.md | **/templates/**/*.html |
Thymeleafテンプレート |
| form-validation.instructions.md | **/form/**/*.java |
Form/バリデーション実装 |
| testing.instructions.md | **/*Test.java |
テストコード実装 |
既存のコーディング規約は1つのmdファイルにまとまっていましたが、
規約に沿いつつ実体コードにも則した、レイヤ／役割ごとの分割案になりました。
3. 分割案に沿って*.instructions.mdを1ファイルずつ生成し、人とCopilotで調整しながら完成させる
Copilotから分割案（ファイル一覧と役割）を得たあと、分割案に沿って*.instructions.mdを1ファイルずつ生成させ、レビューと調整を繰り返しながら整備しました。
プロンプト例:
上から順番に1つずつ、instructions.mdファイルの作成をお願いします。
instructions.mdファイルの出力例（雰囲気）：
---
applyTo: '**/controller/**/*.java'
description: 'WEB画面用Controller実装ガイドライン'
---
# WEB画面用 Controller 実装ガイドライン
## 概要
WEB UIを提供するモジュールです。
ControllerはThymeleafテンプレートと連携し、画面遷移とユーザー操作を処理します。
## アーキテクチャ
・・・
## 基本実装パターン
### クラス構成
・・・
## アノテーション使用ガイド
### 必須アノテーション
・・・
## セッション管理
・・・
これで、既存のコーディング規約をCustom Instructions化できました。
既存のコーディング規約はCustom Instructionsへ移行し、旧ファイルは整理したうえで、READMEからはCustom Instructionsを参照するように整えました。
今回こだわったこと：Custom Instructions化もCopilotに寄せる
今回こだわったのは、Custom Instructions化そのものを「人が手で書き起こす作業にしない」ことです。
まず土台となるinstructionsを用意し、その上でコーディング規約とリポジトリの実装をCopilotに読ませ、分割案の作成から*.instructions.mdの初稿生成まで、できる限りCopilotに寄せて進めました。
人が作業したのは、生成結果のレビューと微調整、そして最終的な判断だけです。
また、人だけでは見落としがちな「実装上の暗黙ルール」も文章化されるため、規約の再整理や学び直しにもつながりました。
今後の運用
効果検証
導入効果はこれから確認します。次の観点で観察します。
- 人が行うレビュー指摘の減少（命名、責務境界、例外、テスト不足）
- PRの往復回数・リードタイム
- Copilot提案を採用した後の手戻り量
Custom Instructionsのメンテナンス
Custom Instructionsは、一度作って終わりではありません。
リポジトリの実装が変われば、指示内容やapplyToの適用範囲も追従させないと、指示と実コードがズレて逆に混乱の原因になります。
そこで、更新作業も人手に寄せすぎず、Copilotを使って定型化する方針にしました。
具体的には、Instructionsをメンテするためのプロンプトファイル（prompt.md）を用意し、「実体コードとCustom Instructionsの内容のズレを洗い出して、必要な修正を提案・反映する」ことをCopilotに1コマンドで指示できるようにしたいと考えています。
プロンプトファイルについての参考資料：
まとめ
本記事では、既存のコーディング規約をGitHub CopilotのCustom Instructionsとして再構成し、Copilotにも規約を参照させるための導入手順を紹介しました。
結果として、コーディング規約を「読むもの」だけにせず、Copilotの提案にも反映される「効かせるもの」として扱える状態にできました。
今後は効果検証を進めつつ、実装変更とInstructionsのズレを検知して追従させる更新作業もCopilotに任せられるよう、メンテ用のプロンプトファイルを整備していく予定です。
Custom Instructionsを「作って終わり」ではなく、Copilotと一緒に育てていける状態を目指します。