本記事は、GitHub Copilot Code Review をプロジェクトの受入レビューなどで運用するための方針・設定・利用方法・注意事項をまとめたものです。
GitHub Copilot Code Review を利用することで、Pull Request 上でプロジェクト独自の観点を加えたレビューを自動的に実施できます。本ガイドでは、その設定方針から custom instructions の構成、運用上の注意事項まで一通りの内容をまとめています。
開発現場のプロジェクトに応じてカスタマイズして利用いただければ幸いです。
1. 目的
本ドキュメントは、GitHub Copilot Code Review の利用方針、指示書構成、利用方法、制約事項を定めるものです。
Copilot Code Review では、主に以下の観点に関する検出補助を目的とします。
- プロジェクト規約・コーディング規約違反
- アプリケーション設計上の問題（保守性・可読性を低下させる実装、責務分担が不明確な実装）
- 一般的な実装上の問題（非推奨 API の利用、保守性の低いコード、NullPointerException 等の実行時例外につながる可能性）
- 性能上の問題（N+1 クエリ、コストの高い SQL、不要なループや効率の悪い処理）
- セキュリティ上の問題（SQL インジェクション、XSS / DOM XSS、CSRF、機微情報・個人情報・認証情報・トークン等の漏えい）
- 障害・不具合につながる具体的な問題
2. 利用イメージ
Copilot Code Review の基本的な利用イメージは以下のとおりです。
- 開発担当者が実装する
- Pull Request を作成する
- Copilot Code Review を依頼する
- Copilot が Pull Request の差分をレビューし、Pull Request 上にレビューコメントを付与する
- 開発担当者がレビューコメントを確認する
- 指摘内容の妥当性を人間が判断し、必要に応じてコードを修正する
- 必要に応じて Copilot に再レビューを依頼する
- 人間によるレビューを実施する
- 問題がなければマージする
3. 責任範囲
GitHub Copilot Code Review は、Pull Request のレビューを補助するための機能です。
Copilot Code Review の指摘有無にかかわらず、最終的なコードに関する責任は、開発担当およびレビュー担当が負うものとします。
また、Copilot Code Review が指摘した内容についても、必ず人間が妥当性を確認してください。
- Copilot の指摘がないことは、問題がないことを保証しない
- Copilot の指摘がすべて正しいとは限らない
- 指摘内容を採用するかどうかは、人間が判断する
- 最終的な確認および判断は、人間が行う
4. Copilot Code Review の機能概要
GitHub Copilot Code Review は、Pull Request の差分を対象として、Copilot がレビューコメントを投稿する機能です。主な機能は以下のとおりです。
- Pull Request の差分をもとにレビューコメントを投稿する
- 問題があると判断された箇所に対して指摘を行う
- 一部の指摘では修正案を提示する
- リポジトリ内の custom instructions により、プロジェクト固有の共通レビュー観点を指定できる
- ファイル種別やパスごとに path-specific instructions により個別のレビュー観点を適用できる
- GitHub の Ruleset 設定により、Pull Request に対して自動的に Copilot Code Review を依頼できる
4.1 レビューコメントとしての投稿
Copilot Code Review の結果は、Pull Request 上のレビューコメントとして投稿されます。ここでいうレビューコメントとは、Pull Request の変更箇所に対して投稿されるコメント、および Pull Request 全体に対して投稿されるコメントを指します。
Copilot のレビューコメントは、人間のレビューコメントと同様に確認・返信・解決を行うことができます。
4.2 マージ可否への影響
Copilot Code Review の結果が Pull Request のマージ可否に影響するかどうかは、GitHub 側の以下の設定に依存します。
- Branch protection rules
- Rulesets
- Required status checks
- Required reviews
本運用では、Copilot Code Review はレビュー補助の位置づけで利用します。そのため、原則として Copilot Code Review をマージ条件には設定しません。
5. Copilot Code Review の位置づけ
本運用では、Copilot Code Review を主に開発担当者のセルフレビュー補助として利用します。開発担当者は Pull Request 作成後、対象機能を選定したうえで Copilot Code Review を依頼し、指摘内容を確認します。
- 人間によるレビューの代替ではなく、補助として利用する
- Pull Request 作成後のセルフチェックとして利用する
- 規約違反、実装上の問題、セキュリティリスク、性能問題の早期検出に利用する
- 指摘内容は人間が判断し、必要なもののみ対応する
6. Custom instructions の基本方針
本プロジェクトでは、Copilot Code Review にプロジェクト固有のレビュー観点を反映するため、GitHub Copilot の custom instructions を利用します。Custom instructions は、リポジトリ内に配置する Markdown ファイルにより定義します。
6.1 利用する instruction file
本プロジェクトでは、以下の 2 種類の instruction file を利用します。
| 種類 | 配置場所 | 用途 |
|---|---|---|
| Repository-wide instructions | .github/copilot-instructions.md | リポジトリ全体に適用する共通方針 |
| Path-specific instructions | .github/instructions/*.instructions.md | ファイルパス、レイヤー、技術要素ごとのレビュー観点 |
6.2 Repository-wide instructions
Repository-wide instructions は、リポジトリ全体に適用する共通方針を記載します。配置場所は .github/copilot-instructions.md とします。主に以下を記載します。
- レビューの基本方針
- レビュアーとしての役割
- 技術スタック
- 言語やコンポーネント種別に依存しないレビュー観点
- 指摘時の基本姿勢
- 指摘の重要度
- 静的解析ツールに任せる項目
6.3 Path-specific instructions
Path-specific instructions は、ファイルパス、レイヤー、技術要素ごとに適用するレビュー観点を記載します。配置場所は .github/instructions/*.instructions.md とします。
applyTo で適用対象ファイルを指定することが可能です。applyTo に一致する変更ファイルが Pull Request に含まれる場合、その instruction file がレビュー時に適用対象となります。
例：Controller クラスを対象にする場合
---
applyTo: "**/*Controller.java"
---
# Controller レビュー観点
- Controller に業務ロジックを持たせすぎていないか
- 入力値検証が適切に行われているか
- 認証・認可が必要な処理でチェック漏れがないか
- Service 層へ適切に処理を委譲しているか6.4 Instruction file の分割方針
本運用では、レビュー観点を 1 つの instruction file に集約せず、レイヤー別・技術要素別に分割します。分割する理由は以下のとおりです。
- Copilot に渡す不要な input を減らすため
- レビュー対象に関係のない観点を適用しないため
- AI credits の消費量を適切に抑えるため
- レビュー精度を高めるため
- instruction file の保守性を高めるため
- レイヤー別、技術要素別にレビュー観点を管理しやすくするため
各 instruction file の記載方針は以下のとおりです。
- 各 instruction file は簡潔に記載する
- 重要な指示はファイル前半に記載する
- 長い説明文よりも、箇条書きで具体的なチェック観点を記載する
- 1 つの instruction file に複数領域の観点を詰め込みすぎない
- レイヤー別、技術要素別にファイルを分割する
- 重要度の高い観点を優先して記載する
- 重複する指示はできるだけ共通ファイルへ集約する
分割の目的は、不要な input を減らし、クレジット消費量を適切にしつつ、レビュー精度を高めることです。
6.5 Base branch 側の instruction が使用される点
Copilot Code Review では、Pull Request の base branch に存在する instruction file が参照されます。base branch とは、Pull Request のマージ先として指定されているブランチを指します。
例えば、以下のようなブランチ構成を取っているとします。
main
└─ stg
└─ test
└─ devこの場合、Pull Request の向きによって base branch は変わります。
| Pull Request | base branch | compare branch |
|---|---|---|
dev から test への PR | test | dev |
test から stg への PR | stg | test |
stg から main への PR | main | stg |
Copilot Code Review は、PR の変更元ブランチではなく、マージ先である base branch 側の instruction file を参照します。
Instruction file をレビュー運用に反映したい場合は、レビュー対象 PR の base branch に instruction file が存在している必要があります。
7. ファイル構成
本プロジェクトでは、以下の構成で instruction file を配置します。
.github/
copilot-instructions.md
instructions/
html-rule.instructions.md
javascript-rule.instructions.md
java-rule.instructions.md
web.instructions.md
api.instructions.md
batch.instructions.md
junit.instructions.md7.1 .github/copilot-instructions.md
リポジトリ全体に適用する共通方針を記載します。主な記載内容は、レビューの基本方針、レビュアーとしての役割、共通のレビュー観点、指摘の重要度、静的解析ツールに任せる項目です。
7.2 .github/instructions/html-rule.instructions.md
HTML、Thymeleaf、CSS 向けのコーディング規約を記載します。HTML・CSS に関する命名規則、記述ルール、禁止事項、推奨記法などを記載します。
7.3 .github/instructions/javascript-rule.instructions.md
JavaScript 向けのコーディング規約を記載します。JavaScript に関する命名規則、記述ルール、禁止事項、推奨記法などを記載します。
7.4 .github/instructions/java-rule.instructions.md
Java 向けのコーディング規約を記載します。Java に関する命名規則、記述ルール、禁止事項、推奨記法などを記載します。
7.5 .github/instructions/web.instructions.md
Web モジュール全般のレビュー観点を記載します。
7.6 .github/instructions/api.instructions.md
API 向けのレビュー観点を記載します。
7.7 .github/instructions/batch.instructions.md
バッチ処理向けのレビュー観点を記載します。
7.8 .github/instructions/junit.instructions.md
JUnit 等のテストコード向けのレビュー観点を記載します。
8. 利用方法
8.1 基本方針
Copilot Code Review は、GitHub の設定により全 Pull Request に自動適用することも可能です。ただし、本運用ではコスト面およびレビュー対象の制御を考慮し、原則として手動で適用します。
- Pull Request 作成後、対象機能を選定したうえで Copilot Code Review を依頼する
- 全 Pull Request に対する自動レビューは原則として利用しない
- Copilot Code Review の結果は人間が確認する
- 妥当な指摘のみ対応する
Copilot Code Review の実行対象は、レビュー効果やクレジット消費を考慮して選定します。
8.2 GitHub 画面から手動依頼する方法
Pull Request 作成後、GitHub 画面から Copilot Code Review を手動で依頼します。手順は以下のとおりです。
- GitHub 上で対象 Pull Request を開く
- 右サイドバーの Reviewers 欄を表示する
Copilotの横にあるRequestをクリックする- Copilot Code Review の実行完了を待つ
- Pull Request 上に投稿されたレビューコメントを確認する
- 指摘内容の妥当性を人間が確認する
- 必要に応じてコードを修正する
9. クレジット消費
Copilot Code Review は、実行時に GitHub AI credits を消費します。AI credits の紐づきは、レビューの依頼方法により異なります。
| 実行方法 | AI credits の紐づき |
|---|---|
| 手動で Copilot Code Review を依頼した場合 | レビューを依頼したユーザー |
| Ruleset 等により自動で実行された場合 | Pull Request 作成者 |
| Bot や GitHub Actions により PR が作成された場合 | ワークフロー実行者、または指定された課金主体 |
Copilot Business / Copilot Enterprise では、AI credits は Organization または Enterprise の共有プールとして管理される場合があります。ただし、利用実績はユーザーに紐づいて記録され、ユーザー単位の budget が設定されている場合はその制限の影響を受けます。
不要なクレジット消費を避けるため、本プロジェクトでは原則として手動実行とします。
10. 注意事項・制約
10.1 すべての問題を検出する保証はない
Copilot Code Review は、すべての不具合、脆弱性、設計不備、規約違反を検出するものではありません。Copilot Code Review の指摘がない場合でも、コードに問題がないことを意味しません。
10.2 指摘がすべて正しい保証はない
Copilot Code Review が指摘する内容は、すべて正しいとは限りません。以下のようなケースがあり得ます。
- 仕様を誤解した指摘
- 前提条件が不足した指摘
- 実装意図に合わない修正提案
- プロジェクトの既存方針と合わない指摘
- 影響範囲を十分に考慮していない指摘
最終的には人間の判断により、対応可否や対応方法を決定してください。
10.3 出力形式の完全な制御はできない
Copilot Code Review では、custom instructions により出力方針やレビュー観点を指定できます。ただし、出力形式・指摘粒度・コメント位置・指摘有無・指摘件数・修正案の有無を完全に制御することはできません。プロジェクトで定型的な出力形式が必要な場合は、必要に応じて別途ツール化を検討してください。
10.4 Instruction file の変更がすぐにレビューへ反映されない場合がある
Copilot Code Review は、Pull Request の base branch 側に存在する instruction file を参照します。そのため、Pull Request の変更内容として instruction file を追加または修正しても、その Pull Request のレビュー時点では変更後の instruction が使われない場合があります。
例として、develop-review から develop への Pull Request を作成した場合、base branch は develop です。このとき、develop-review 側で .github/instructions/security.instructions.md を修正していても、develop 側にその修正が存在しなければ、Copilot Code Review が参照する instruction は develop 側の内容になります。
Instruction file の追加・変更は、レビュー運用の対象となる本線側ブランチに反映したうえで利用してください。
10.5 excludeAgent の指定に注意する
.github/instructions/*.instructions.md では、特定の Copilot 機能から instruction を除外する設定が利用できる場合があります。Copilot Code Review で利用したい instruction file には、Code Review を除外する指定を入れないでください。
例えば、以下のような指定がある場合、Copilot Code Review で利用されません。
---
applyTo: "**"
excludeAgent: "code-review"
---本プロジェクトでは、Copilot Code Review 用の instruction file には、原則として excludeAgent: "code-review" を指定しません。
10.6 対象外ファイルが存在する
Copilot Code Review では、レビュー対象外となるファイル種別が存在します。依存関係管理ファイル、ログファイル、SVG ファイルなどはレビュー対象外となる場合があります。対象外ファイルについては、必要に応じて人間が確認してください。
10.7 Re-review 時に同じ指摘が再投稿される場合がある
Copilot Code Review に再レビューを依頼した場合、過去に解決済みとしたコメントや不要と判断したコメントと同様の指摘が再度投稿される場合があります。再レビュー時には、既に対応済みの指摘かどうかの確認と、不要と判断した指摘が再投稿されていないかの確認を行い、必要な指摘のみ対応してください。
11. 将来的な拡張候補
将来的に以下のような要件が出た場合は、Copilot cloud agent、Custom Agent、または独自 AI Review Bot の利用を検討します。
11.1 Copilot cloud agent の検討
以下のような要件が出た場合は、Copilot cloud agent の利用を検討します。
- Copilot の指摘をもとに修正案を作成させたい
- 指摘内容に対する修正 PR を作成させたい
- レビューコメントから具体的な修正作業へつなげたい
11.2 Custom Agent の検討
以下のような要件が出た場合は、Custom Agent の利用を検討します。
- 長文のレビュー指示をより詳細に適用したい
- 出力形式をある程度固定したい
- セルフレビュー用と Pull Request レビュー用で指示を分けたい
- ローカルリポジトリ上の差分を対象にレビューしたい
- ステージング済み変更のみをレビュー対象にしたい
11.3 独自 AI Review Bot の検討
以下のような要件が出た場合は、独自 AI Review Bot の構築を検討します。
- 出力形式を完全に固定したい
- PR 差分だけでなく、リポジトリ全体を厳密に調査させたい
- レビュー対象ファイル、除外ファイル、評価ルールを厳密に制御したい
- 社内システムと連携したい
- レビュー結果を自動的に集計・保存したい
