Microsoft Copilot documentation update：AIエージェント向け開発ワークフロー追加の影響と確認ポイント

Microsoft Copilot documentation update「[AI] Add Copilot prompts and AI agent guidelines for developer workflows」は、Microsoft CopilotやGitHub Copilotを使う開発チーム向けに、AIへ渡す作業手順をリポジトリ内に明文化する更新です。結論から言うと、SQL Server用JDBCドライバーの実行時挙動やアプリ側の接続コードが変わる更新ではありません。対応が必要なのは、mssql-jdbcに貢献する開発者、VS CodeでCopilot prompt filesを使う人、Copilot code reviewやAI coding agentを運用するメンテナーです。PR #2942では、.github/prompts/配下の再利用可能なプロンプト群、.github/copilot-instructions.md、AGENTS.mdが追加対象になっています。(GitHub)

今回のMicrosoft Copilot documentation updateで何が変わるのか

今回の変更は、Microsoftのmssql-jdbcリポジトリに対して、CopilotやAIエージェントが開発作業を進めやすくするための「作業ガイド」を追加するものです。mssql-jdbcはSQL ServerやAzure SQL Database向けのJava Database Connectivityドライバーであり、今回の更新対象はドライバー本体のAPI変更ではなく、開発者ワークフローのドキュメント・設定です。(Microsoft Learn)

具体的には、次の3種類のファイルが中心です。

追加対象	役割	確認すべきポイント
`.github/prompts/*.prompt.md`	VS Codeなどで呼び出せる再利用プロンプト	セットアップ、ビルド、テスト、PR作成などの定型作業をCopilotに依頼しやすくする
`.github/copilot-instructions.md`	リポジトリ全体のCopilot向け指示	プロジェクト構成、JREプロファイル、テスト方針、セキュリティ上の制約を常時コンテキスト化する
`AGENTS.md`	AI coding agent向けの作業ガイド	複数のAIエージェントやCopilot coding agentが参照する共通ルールをまとめる

重要なのは、これは「Copilotに何をどう頼むか」を標準化する更新だという点です。これまで担当者ごとに口頭やREADME参照で行っていた作業手順を、AIが読み取りやすいMarkdownファイルとしてリポジトリに置く形になります。

追加されるCopilot promptsの内容

PR #2942では、.github/prompts/配下にメンテナー向けの再利用プロンプトが追加されています。PR本文では、開発環境セットアップ、Mavenビルド、テスト実行、バグ修正、機能実装、コードレビュー、パフォーマンス調査、PR作成などのワークフローが対象として挙げられています。(GitHub)

プロンプト	主な用途	実務での使いどころ
`setup-dev.prompt.md`	開発環境のセットアップ	JDK、Maven、IDEフォーマッター、テストDBの確認
`build.prompt.md`	Mavenでのビルド	JREプロファイル別のコンパイル、JAR作成、ローカルインストール
`run-tests.prompt.md`	テスト実行	単体テスト、統合テスト、BVT、タグ指定、状態機械テストの切り分け
`fix-bug.prompt.md`	バグ修正	再現、原因調査、失敗テスト作成、修正、検証
`implement-feature.prompt.md`	機能追加	仕様確認、影響範囲調査、実装、テスト、ドキュメント更新
`code-review.prompt.md`	PRレビュー	互換性、テスト、ログ、セキュリティ、JDBC/TDS観点の確認
`perf-optimization.prompt.md`	性能改善	ホットパス、アロケーション、バッファ再利用、回帰確認
`create-pr.prompt.md`	PR作成	ブランチ、コミット、説明文、チェックリストの整理
`generate-doc-comments.prompt.md`	Javadoc生成	公開APIや変更箇所の説明コメント作成
`generate-prompt.prompt.md`	新規プロンプト作成	プロジェクト用の追加プロンプトを作る
`generate-skill.prompt.md`	Copilot Agent Skills作成	`SKILL.md`形式のスキル化を支援する

VS Codeのprompt filesは、共通タスクの指示をMarkdownファイルとして保存し、チャットから手動で呼び出す仕組みです。既定のワークスペース配置場所は.github/promptsで、カスタム指示と違って自動適用ではなく、チャット欄で/を入力して必要なプロンプトを選ぶ使い方になります。(Visual Studio Code)

`.github/copilot-instructions.md`の追加で変わること

.github/copilot-instructions.mdは、Copilotにリポジトリ固有の前提を伝えるためのファイルです。GitHub Docsでは、リポジトリ全体のカスタム指示は.github/copilot-instructions.mdに置き、プロジェクトの理解、ビルド、テスト、検証の方法をCopilotに伝える用途と説明されています。(GitHub Docs)

今回のPRでは、mssql-jdbc向けに次のような文脈が追加されています。

項目	追加される文脈
プロジェクト概要	Microsoft JDBC Driver for SQL Serverであり、JDBC 4.2/4.3やTDSプロトコルを扱うこと
ソース構成	ドライバー本体は`src/main/java/com/microsoft/sqlserver/jdbc/`、テストは`src/test/java/`配下
JREプロファイル	`jre8`、`jre11`、`jre17`、`jre21`、`jre25`、`jre26`を意識したビルド
テスト方針	単体テスト、統合テスト、BVT、状態機械テストの区別
実装ルール	公開API変更時のJavadoc更新、ハードコード接続文字列の禁止、Eclipse formatter利用
セキュリティ	パスワード、トークン、資格情報付き接続文字列をログに出さない

実務上の効果は、Copilotが「このリポジトリでは何を守るべきか」を毎回ゼロから推測しなくて済むことです。たとえば、例外処理やログ出力、JRE互換性、テストの置き場所などを事前に伝えておけば、AIが生成するコードやレビューコメントのブレを減らせます。

ただし、カスタム指示は万能ではありません。VS Codeのドキュメントでは、カスタム指示はチャット要求に影響しますが、エディター入力中のインライン補完には考慮されないと説明されています。補完結果まで完全に統制できる設定ではない点に注意が必要です。(Visual Studio Code)

`AGENTS.md`追加の意味

AGENTS.mdは、AI coding agent向けのREADMEのような位置づけです。GitHubの情報では、Copilot coding agentはAGENTS.mdのカスタム指示をサポートしており、リポジトリルートの単一ファイルだけでなく、特定ディレクトリにネストしたAGENTS.mdも使えるとされています。(The GitHub Blog)

今回のAGENTS.mdでは、AIエージェントが作業前に参照すべきファイル、共通ワークフロープロンプト、コア原則、バグ修正や機能追加の流れが整理されています。特に重要なのは、次のようなルールです。

原則	実務での意味
クロスプラットフォーム対応	Windows、Linux、macOSのいずれかに依存する実装を避ける
複数JREプロファイル対応	変更後に対象JREでコンパイルできるか確認する
後方互換性	破壊的変更を安易に入れない
テストファースト	バグ修正では再現テストを先に作る
セキュリティ優先	認証情報をログに出さず、安全な既定値を選ぶ
性能意識	ホットパスで不要なオブジェクト生成を避ける

AIエージェントを使うチームでは、AGENTS.mdの有無で作業品質が変わります。エージェントはコードを読めますが、チーム内の暗黙知までは自動的に理解できません。レビューで毎回指摘されるルールほど、AGENTS.mdやcopilot-instructions.mdに明文化する価値があります。

誰が対応すべきか

今回のMicrosoft Copilot documentation updateは、全員が同じ温度感で対応すべき更新ではありません。影響範囲を切り分けると、優先度が分かりやすくなります。

対象者	対応優先度	理由
`mssql-jdbc`のメンテナー	高	プロンプト内容、レビュー基準、JREプロファイル、テスト方針の正確性を確認する必要がある
`mssql-jdbc`へPRを出す開発者	高	セットアップ、ビルド、テスト、PR作成の手順が変わる可能性がある
VS CodeでGitHub Copilotを使う開発者	中	prompt filesを使うと作業を標準化できるが、未使用なら直接影響は限定的
Copilot code reviewやAI agentを導入しているチーム	中〜高	カスタム指示がレビューやエージェント作業に影響する可能性がある
JDBCドライバーを依存関係として利用するアプリ開発者	低	ドライバー本体の機能変更ではないため、通常は接続コードや依存関係の変更は不要
Microsoft 365 Copilotの一般利用者	低	対象は開発者向けCopilotワークフローであり、WordやExcelのCopilot設定とは別物

最も注意すべきなのは、mssql-jdbcをフォークしているチームです。本家のプロンプトをそのまま取り込むと、自社のCI、JDKバージョン、テストDB、レビュー体制と合わない場合があります。取り込む場合は、コマンドや除外タグ、秘密情報の扱いを必ず自社環境に合わせて調整してください。

移行や設定確認で見るべきポイント

VS Codeでprompt filesが読み込まれるか確認する

Copilot prompt filesは、GitHub Docs上ではパブリックプレビューであり、VS Code、Visual Studio、JetBrains IDEsで利用可能とされています。利用可否や表示方法はIDEや拡張機能の状態によって変わる可能性があるため、まずは自分の環境で読み込まれるかを確認してください。(GitHub Docs)

確認手順は次の通りです。

手順	確認内容
リポジトリを最新化する	`.github/prompts/`、`.github/copilot-instructions.md`、`AGENTS.md`が存在するか
VS Codeでリポジトリルートを開く	`.github`がワークスペース直下として認識されているか
Copilot Chatで`/`を入力する	追加されたプロンプトが候補に出るか
候補が出ない場合	prompt filesの対応状況、拡張機能、ワークスペース設定を確認する
モノレポの場合	親リポジトリのカスタマイズ検出設定が必要か確認する

VS Codeでは、prompt filesの既定配置はワークスペースの.github/promptsです。また、モノレポで親リポジトリ側のカスタマイズを検出したい場合は、chat.useCustomizationsInParentRepositoriesの設定が関係します。(Visual Studio Code)

`AGENTS.md`が利用される設定を確認する

VS Codeのカスタム指示では、.github/copilot-instructions.mdやAGENTS.mdは常時適用される指示として扱われます。ただし、AGENTS.mdが適用されない場合は、chat.useAgentsMdFileなどの関連設定を確認する必要があります。(Visual Studio Code)

確認するときは、次の観点を見てください。

確認項目	見るべきこと
ファイル位置	`AGENTS.md`がリポジトリルート、または対象ディレクトリに置かれているか
適用範囲	ネストされた`AGENTS.md`がある場合、近い階層の指示が優先されるか
内容の衝突	`copilot-instructions.md`、`AGENTS.md`、組織指示で矛盾がないか
診断	VS CodeのChat diagnosticsで読み込みエラーがないか

指示ファイルは増やすほど良いわけではありません。似たルールを複数ファイルに書くと、AIがどちらを優先すべきか迷います。共通ルールはcopilot-instructions.md、エージェント運用の入口はAGENTS.md、タスク別手順は.prompt.mdに分けるのが扱いやすい構成です。

JDKとMavenプロファイルを確認する

今回のPRでは、mssql-jdbcのビルド手順にJREプロファイルの整理が含まれ、jre26を既定プロファイルとして扱う記述も見られます。build.prompt.mdでは、jre8からjre26までのプロファイルと出力JARが整理され、JDKバージョン不一致時のトラブルシューティングも追加されています。(GitHub)

開発者は、次のコマンドでまず環境を確認してください。

java -version
mvn --version

JDK 26を入れていない環境で既定プロファイルのビルドが失敗する場合は、対象に合わせて明示的にプロファイルを指定します。

mvn clean compile -Pjre11
mvn clean package -DskipTests -Pjre11
mvn clean test -Pjre11

失敗しやすいのは、JDKの実行バージョンとMavenが参照しているJAVA_HOMEがずれているケースです。java -versionでは期待通りでも、mvn --versionで別のJDKを見ていることがあります。

テストDBと接続文字列の扱いを確認する

run-tests.prompt.mdでは、単体テストはDB不要、統合テストやBVTなどはSQL Server接続が必要という整理が追加されています。テスト実行用の環境変数としてmssql_jdbc_test_connection_propertiesを使う記述も含まれています。(GitHub)

単体テストだけを確認したい場合は、まずDB不要の範囲から始めるのが安全です。

mvn clean test -Pjre11 -Dtest="com.microsoft.sqlserver.jdbc.unit.**"

統合テストを実行する場合は、接続文字列を環境変数に設定します。ただし、実際のパスワードや本番環境の接続情報をプロンプト、ログ、PR本文に貼り付けてはいけません。

# macOS/Linux
export mssql_jdbc_test_connection_properties="jdbc:sqlserver://localhost:1433;databaseName=testDb;user=sa;password=yourPassword;encrypt=true;trustServerCertificate=true;"

# Windows PowerShell
$env:mssql_jdbc_test_connection_properties = "jdbc:sqlserver://localhost:1433;databaseName=testDb;user=sa;password=yourPassword;encrypt=true;trustServerCertificate=true;"

trustServerCertificate=trueのような設定は、ローカル検証では便利ですが、本番環境の接続方針とは分けて考えるべきです。Copilotにテスト手順を依頼する場合も、「本番資格情報は使わない」「ログに接続文字列を出さない」と明示しておくと事故を減らせます。

この更新で期待できる効果

今回の更新で最も大きい効果は、AI支援開発の品質を「個人のプロンプト力」から「リポジトリの標準手順」に移せることです。

従来の課題	更新後に期待できる改善
開発者ごとにCopilotへの頼み方が違う	共通プロンプトを使い、作業手順をそろえられる
AIがビルド方法やテスト分類を推測する	リポジトリ内の指示から正しい手順を参照しやすくなる
PRレビューで同じ指摘が繰り返される	レビュー観点を`code-review.prompt.md`にまとめられる
新規コントリビューターのオンボーディングに時間がかかる	`setup-dev.prompt.md`で環境構築を段階的に案内できる
AIエージェントが不要な探索を繰り返す	`AGENTS.md`で参照すべきファイルと原則を先に渡せる

特にオープンソースや大規模リポジトリでは、Copilotが正しい作業手順を知らないままコード変更を提案すると、レビューコストが増えます。今回のようなプロンプト整備は、AIを「速く書く道具」ではなく「チームルールを守って作業する補助者」に近づける取り組みです。

注意すべき失敗パターン

プロンプトをコピーしただけで運用した気になる

.prompt.mdは、置くだけでチームの作業が改善するものではありません。実際に開発者が呼び出し、失敗した箇所を直し、CIやレビュー結果に合わせて更新する必要があります。

たとえば、社内プロジェクトに流用するなら、次の項目は必ず書き換えてください。

書き換える項目	理由
ビルドコマンド	Maven、Gradle、npm、dotnetなどプロジェクトごとに違う
テストコマンド	DB要否、タグ、除外条件、CI実行条件が異なる
フォーマッター	Eclipse formatter、Prettier、Blackなど採用ツールが違う
レビュー観点	セキュリティ、性能、互換性、アクセシビリティなど重視点が違う
秘密情報の扱い	ログ、環境変数、サンプル値のルールは組織ごとに明文化が必要

指示ファイルを長くしすぎる

Copilot向けの指示は、詳細であるほど良いとは限りません。VS Codeのドキュメントでも、効果的な指示は短く自己完結させ、非自明なルールに絞ることが推奨されています。標準のリンターで検出できることまで長々と書くより、「なぜそのルールが必要か」「例外時にどう判断するか」を書いたほうが実務では役立ちます。(Visual Studio Code)

悪い例は、次のような指示です。

きれいなコードを書いてください。
エラーがないようにしてください。
必要に応じてテストしてください。

これでは抽象的すぎて、AIの判断が安定しません。改善するなら、次のように具体化します。

公開APIを変更した場合は、該当メソッドのJavadocを更新し、互換性への影響をPR本文に記載してください。
接続文字列、パスワード、アクセストークンをログに出力しないでください。
単体テストはDB不要の`unit/`配下に追加し、DBが必要な検証は統合テストとして分けてください。

Copilotの提案を検証せずにマージする

AI向けの指示を整えても、最終責任は人間のレビューにあります。今回のPRでも、CopilotによるレビューやAutofix由来のコミットが見られますが、PRページ上ではレビュー依頼や承認要件が残っています。AIレビューは補助として使い、JREプロファイル、テスト、セキュリティ、公開APIの互換性は人間が確認するべきです。(GitHub)

自社リポジトリへ応用する場合の進め方

今回のMicrosoft Copilot documentation updateは、mssql-jdbc固有の変更ですが、他の開発チームにも応用しやすいパターンです。導入するなら、いきなり大量のプロンプトを作るより、効果が出やすい3つから始めるのが現実的です。

優先度	作るファイル	内容
1	`.github/copilot-instructions.md`	技術スタック、禁止事項、ビルド・テストの最小手順
2	`.github/prompts/run-tests.prompt.md`	よく使うテスト範囲、失敗時の調査手順、レポート場所
3	`.github/prompts/create-pr.prompt.md`	PR本文テンプレート、確認項目、変更影響の書き方
4	`AGENTS.md`	AIエージェントに任せてよい作業、禁止作業、参照ドキュメント
5	`.github/prompts/code-review.prompt.md`	レビュー観点、セキュリティ、性能、互換性チェック

導入時は、次の流れで進めると失敗しにくくなります。

ステップ	作業
現状把握	README、CONTRIBUTING、CI設定、テスト手順を棚卸しする
最小作成	まずはビルド、テスト、PR作成の3領域だけをプロンプト化する
実作業で検証	実際のバグ修正や小さなPRで使い、曖昧な指示を修正する
レビュー導入	PRレビュー時に「プロンプト通りに検証できたか」を確認する
定期更新	CI変更、ツール更新、JDKやNode.js更新に合わせて見直す

ポイントは、AI用ファイルを「ドキュメントの別置き場」にしないことです。READMEやCI設定と矛盾した瞬間に、Copilotは古い手順を信じて失敗します。更新責任者を決め、リリースやCI変更のたびに見直す運用が必要です。

よくある疑問

Copilot promptsは自動で適用されるのか

.github/prompts/*.prompt.mdは、基本的にチャットから手動で呼び出すタスク別プロンプトです。一方、.github/copilot-instructions.mdやAGENTS.mdは、ワークスペースやリポジトリの文脈として自動的に適用される指示に近い役割を持ちます。VS Codeのドキュメントでも、prompt filesは手動呼び出し、custom instructionsは自動適用という違いが説明されています。(Visual Studio Code)

アプリ側でmssql-jdbcのバージョンを変更する必要はあるか

今回のPRは、開発者向けワークフローのプロンプトとAIエージェント向けガイドラインの追加です。ドライバーのリリース、JAR、接続仕様、アプリケーションコードの変更を直接求める内容ではありません。mssql-jdbcを依存関係として利用しているだけなら、通常はこの更新だけを理由にバージョン変更する必要はありません。

Copilot code reviewに影響するのか

影響する可能性があります。GitHub Docsでは、リポジトリカスタム指示はCopilot code reviewやCopilot cloud agentで使われる説明があり、path-specific instructionsもCopilot cloud agentとCopilot code review向けにサポートされると説明されています。今回のPRでは.github/copilot-instructions.mdやAGENTS.mdが追加されるため、レビューやエージェント作業でリポジトリ固有の前提が参照される可能性があります。(GitHub Docs)

`copilot-instructions.md`と`AGENTS.md`は両方必要か

必須ではありませんが、役割を分けると便利です。copilot-instructions.mdにはリポジトリ全体の開発ルールや技術的制約を書き、AGENTS.mdにはAIエージェントが作業を始める前に読むべき入口情報、参照ドキュメント、禁止事項、作業フローを書きます。複数のAIエージェントを使うチームでは、AGENTS.mdが共通の作業ガイドとして機能します。

まず取るべきアクション

今回のMicrosoft Copilot documentation updateで最初にやるべきことは、ドライバー更新ではなく、自分が影響対象かを切り分けることです。

mssql-jdbcのメンテナーやコントリビューターは、PR #2942の追加ファイルを確認し、JDK/JREプロファイル、テストDB、フォーマッター、セキュリティ指示が実態と合っているかを見てください。VS CodeでCopilotを使う開発者は、.github/prompts/のプロンプトがチャットから呼び出せるかを確認し、まずsetup-dev、build、run-tests系のプロンプトを実作業で試すのが効果的です。

一方、JDBCドライバーをアプリケーションの依存関係として利用しているだけのチームは、今回の更新だけで接続コードや本番環境設定を変える必要はありません。むしろ、自社リポジトリでも同じように「AIに任せる作業」と「人間が必ず確認する作業」を明文化できるかを検討すると、Copilot活用の品質を上げられます。

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。