2026年5月5日に公開された「Microsoft developer platform documentation update: Update README and instructions for agents」は、アプリの実行仕様やAPIを直接変える更新ではありません。主なポイントは、Microsoft/DiskANN リポジトリで README と AI エージェント向けの作業指示を整備し、GitHub Copilot や coding agent を使った開発・レビューの品質を安定させることです。対象になるのは、DiskANNを参照している開発者、RAG・ベクトル検索基盤の検証担当者、CopilotなどのAI開発支援をチームで使っている管理者です。PRは本稿確認時点で Draft 状態のため、すぐに本番コードを変更するより、まずは「ドキュメント参照先」「AIエージェント設定」「レビュー基準」を確認するのが現実的です。(GitHub)
Microsoft developer platformのドキュメント更新で何が変わったのか
今回の更新は、Microsoft の DiskANN リポジトリに対する Pull Request #1014「Update README and instructions for agents」として確認できます。PRは main ブランチへ5コミットをマージする内容で、2026年5月5日にPRコメントが作成され、その後5月7日にも README や instructions、AGENTS.md に関する追加コミットが入っています。(GitHub)
DiskANNは、検索、レコメンド、RAG、ベクトルDBプラットフォームで使うことを想定したスケーラブルなベクトルインデックスライブラリとして説明されています。READMEでは、DiskANN3 が Provider API を通じて新しいストアやデータベースへ拡張できる構成であること、リアルタイム更新、複数の距離関数・量子化、メモリ階層、フィルター連携などの特徴が整理されています。(GitHub)
つまり、今回の Microsoft developer platform のドキュメント更新は「DiskANNそのものの挙動変更」よりも、開発者とAIエージェントがリポジトリを正しく扱うための運用ルール整備と見るべきです。
変更点の全体像
今回確認すべき変更は、主に5つあります。
| 変更対象 | 主な変更 | 影響を受ける人 | まず確認すべきこと |
|---|---|---|---|
.github/copilot-instructions.md | Copilot向けのコードレビュー指示を追加 | Copilot Code Review利用者、レビュアー | SemVer、依存関係、unsafe、テスト、ライセンスのレビュー基準 |
.github/instructions.md | 旧来の簡易レビュー指示を削除 | 既存の自動化・社内手順でこのファイルを参照しているチーム | 参照先を新しいファイルへ移せるか |
AGENTS.md | 279行のエージェント向けオンボーディングガイドを追加 | Copilot coding agent、Codex系ツール、AI開発支援の利用者 | ファイル名の大文字小文字、記載された禁止事項・実行コマンド |
README.md | DiskANN3の位置付け、Provider API、機能概要を更新 | DiskANNを評価・導入する開発者 | 旧C++中心の理解で説明していないか |
diskann/README.md | テストベースラインの開発者向け説明を整理 | テストを書く開発者、レビュー担当 | DISKANN_TEST=overwrite の扱いと生成ファイルの確認手順 |
PRの差分では、.github/copilot-instructions.md が65行追加され、.github/instructions.md は11行削除、AGENTS.md は279行追加されています。ファイル一覧にはルートの README.md、旧 agents.md、diskann/README.md も含まれています。(GitHub)
重要度が高いのはAGENTS.mdとCopilot向け指示
今回の更新で特に重要なのは、AGENTS.md と .github/copilot-instructions.md です。どちらも人間向けの説明というより、AIコーディングエージェントやAIレビュー機能がリポジトリをどう扱うべきかを示す役割を持ちます。
GitHub公式ドキュメントでは、リポジトリ全体のカスタム指示は .github/copilot-instructions.md で指定でき、パス固有のカスタム指示は .github/instructions/NAME.instructions.md で指定できると説明されています。また、AIエージェント向けの指示として AGENTS.md をリポジトリ内に置けることも案内されています。(GitHub Docs)
GitHubのChangelogでも、Copilot coding agent が AGENTS.md のカスタム指示をサポートし、ルートの AGENTS.md やネストされた AGENTS.md を使えること、加えて .github/copilot-instructions.md や .github/instructions/**.instructions.md 形式も引き続きサポートすると説明されています。(The GitHub Blog)
実務上は、次のように使い分けると混乱しにくくなります。
| ファイル | 役割 | 書くべき内容の例 |
|---|---|---|
.github/copilot-instructions.md | Copilotやレビュー支援に渡す共通の品質基準 | SemVer、依存関係、エラー処理、ドキュメント整合性、unsafeコードの扱い |
AGENTS.md | AIコーディングエージェントが作業するための実務手順 | リポジトリ構造、依存関係の境界、テスト実行方法、禁止事項、事前確認コマンド |
README.md | 人間の利用者・評価者向けの概要説明 | ライブラリの目的、機能、Provider API、利用開始方法 |
diskann/README.md | 特定クレートや開発者向け詳細 | テストベースライン、生成ファイル、比較用ユーティリティ |
.github/copilot-instructions.mdで追加されたレビュー観点
新しい .github/copilot-instructions.md では、コードレビュー時に確認すべき観点が具体化されています。特に重要なのは、単なる「テストがあるか」ではなく、API互換性、依存関係、エラー処理、SIMDの移植性、unsafeコードの安全性までレビュー対象に含めている点です。(GitHub)
SemVerとAPI互換性
公開APIのシグネチャ変更、型の削除、re-exportの削除は破壊的変更として扱われます。公開挙動を変える場合は、PR説明に移行影響を書くことも求められています。(GitHub)
たとえば、次のような変更は「軽微な修正」として扱うべきではありません。
// 変更前
pub fn search(query: &[f32], k: usize) -> Result<Vec<Neighbor>, ANNError>
// 変更後
pub fn search(query: &[f32], limit: usize, filter: Filter) -> Result<Vec<Neighbor>, ANNError>このような変更を入れる場合は、PRに次の情報を明記する必要があります。
- 既存利用者がどのコードを書き換える必要があるか
- 互換ラッパーを残すか
- メジャーバージョン変更が必要か
- READMEやdoc commentのサンプルも更新したか
依存関係とビルド時間
新しい依存関係を追加する場合は、PR説明で理由を書くことが求められています。これは、AIエージェントが安易に便利なクレートを追加してしまうリスクを抑えるうえで重要です。(GitHub)
特にRustのワークスペースでは、依存関係の追加がビルド時間、CI時間、バイナリサイズ、ライセンス確認に影響します。レビューでは「その依存は本当に必要か」「標準ライブラリや既存依存で代替できないか」を確認すべきです。
エラー処理
回復可能なエラーに対して panic! を追加しないこと、Result で伝播すること、古い log_* 系コンストラクタより ANNError::new(ANNErrorKind::…, e) を優先することが示されています。(GitHub)
失敗しやすいのは、AIが「簡単な実装」として次のようなコードを提案するケースです。
let value = items.first().unwrap();入力が空になる可能性がある処理なら、これはレビューで止めるべきです。エラー内容に次元数、キー、対象インデックスなどの文脈を含め、デバッグしやすい形にする必要があります。
ドキュメント整合性
doc commentやREADMEの例は、実際のAPIシグネチャやシリアライズ形式と一致している必要があります。古いAPIへの参照や、コンパイルできないサンプルはバグとして扱う方針が示されています。(GitHub)
これはドキュメント更新だから軽い、という意味ではありません。AIエージェントが README の古いサンプルをもとにコードを生成すると、誤ったAPI利用が広がる可能性があります。README、doc comment、サンプルコード、社内ナレッジは同じタイミングで確認するのが安全です。
SIMDとプラットフォーム移植性
SIMDレーン幅を固定的に仮定せず、AVX2、AVX-512、ARM/NEONで正しく動くことが求められています。アーキテクチャ固有のintrinsicsに触れる場合は、diskann-wide/README.md に従ったクロスプラットフォーム検証が必要です。(GitHub)
RAGやベクトル検索基盤では、検証環境はx86、デプロイ先はArm、という構成も珍しくありません。ローカルだけで通った最適化をそのまま入れると、CIや本番で未対応命令により失敗する可能性があります。
unsafeコードの安全性
すべての unsafe ブロックに、具体的で検証可能な // SAFETY: コメントを置くことが求められています。曖昧な「this is safe」のような説明は不十分です。(GitHub)
悪い例は次のようなコメントです。
// SAFETY: this is safe
let value = unsafe { ptr.add(i).read() };レビューで期待されるのは、次のように安全条件が分かる説明です。
// SAFETY: i + width <= len を事前に検証しているため、読み取りは境界内に収まる。
let value = unsafe { ptr.add(i).read() };AGENTS.mdで明確になった開発時の境界線
AGENTS.md は、AIエージェントにとってのオンボーディングガイドです。今回追加されたファイルでは、リポジトリ構造、依存関係の階層、変更してはいけないファイル、事前確認が必要な変更、テスト実行方法、エラー処理方針などが整理されています。(GitHub)
特に注目すべきは、「Never」「Ask First」「Always」という判断基準が明確に分かれている点です。
Neverに入っている事項
AGENTS.md では、手作業で変更してはいけないものとして、diskann/tests/generated/ の直接編集、rust-toolchain.toml や .github/workflows/、.codecov.yml の無断変更、グローバルRayonスレッドプールの使用、rand::thread_rng の使用、既存テストの削除や弱体化、秘密情報のコミットなどが挙げられています。(GitHub)
AIエージェントを使う場合、ここは非常に重要です。エージェントはタスク達成のためにCI設定やテストを変更しようとすることがあります。今回のように「触ってはいけない場所」を明文化しておくと、意図しない変更をレビュー前に減らせます。
Ask Firstに入っている事項
新しいワークスペース依存関係の追加、diskann-* クレートの公開API変更、Tier依存関係ルールの変更、clippy.toml や rustfmt.toml の変更は、事前確認が必要な項目として示されています。(GitHub)
これは、人間の開発者にもそのまま役立つ判断基準です。たとえば「ベンチマーク用に新しいクレートを追加するだけ」と思っても、ワークスペース全体の依存関係やビルド時間に影響するなら、PR説明に理由を入れるべきです。
Alwaysに入っている事項
新しいソースファイルにはMITライセンスヘッダーを含めること、cargo fmt --all と cargo clippy --workspace --all-targets -- -Dwarnings を実行すること、関数シグネチャ変更時はdoc commentも更新すること、すべての unsafe ブロックに具体的な // SAFETY: コメントを入れることが示されています。(GitHub)
AIエージェントに作業させる場合は、依頼文の最後に次のような確認を加えると安全です。
変更後にAGENTS.mdのAlways項目を確認し、cargo fmt、cargo clippy、関連テストを実行してください。
公開APIや依存関係を変更した場合は、PR説明に移行影響と理由を記載してください。README更新から読み取れるDiskANNの位置付け
ルートの README.md では、DiskANN3が「検索、レコメンド、RAG、ベクトルDBプラットフォーム」に向けたベクトルインデックスライブラリであることが明記されています。また、Provider APIを実装することで新しいストアやデータベースに拡張できると説明されています。(GitHub)
これは、外部の開発者がDiskANNを評価するときの読み方にも影響します。従来の「高速なANNライブラリ」という理解だけでなく、既存のデータストアやベクトルDBに組み込むための基盤として見るべきです。
READMEでは、例として次のProvider実装が挙げられています。
| Provider | 読み取れる位置付け |
|---|---|
| In-memory provider | データベース用途ではなく、実装例・性能比較・検証向け |
| Disk provider | 旧DiskANNの性能特性を意識したディスクベース実装 |
| Garnet provider | Redis互換の高スループットなスケールアップ検索例 |
| Bf-tree provider | データベース内のB-tree接続例 |
評価担当者は、READMEを読んだうえで「自社のユースケースはライブラリ利用なのか、Provider実装なのか、既存DBへの組み込みなのか」を切り分けると検証計画を立てやすくなります。
diskann/README.mdで確認すべきテストベースライン
diskann/README.md では、開発者向けにテストベースラインの扱いが説明されています。テスト結果を diskann/tests/generated にJSONとして保存し、通常のテストフローで結果とベースラインを比較する仕組みです。差分が出ると、アルゴリズムの変化や回帰を確認するきっかけになります。(GitHub)
ベースラインを再生成するには、次の環境変数を使います。
DISKANN_TEST=overwriteただし、単に上書きして終わりでは不十分です。diskann/README.md では、チェックイン前に diskann/tests/generated を完全に削除してから再生成し、不要なベースラインが残らないようにすることも推奨されています。(GitHub)
実務では、次の流れで確認すると安全です。
| 手順 | 作業 | 目的 |
|---|---|---|
| 1 | 関連テストを通常実行する | 既存ベースラインとの差分を確認する |
| 2 | 期待されるアルゴリズム変更か判断する | 意図しない回帰を見逃さない |
| 3 | diskann/tests/generated を削除する | 使われなくなったJSONを残さない |
| 4 | DISKANN_TEST=overwrite で再生成する | 新しい期待値を作る |
| 5 | git diff でJSON差分を見る | recall、距離、件数などの変化をレビューする |
| 6 | PR説明に差分理由を書く | レビュアーが判断できるようにする |
影響範囲は「利用者」より「開発・レビュー運用」に大きい
今回の更新は、エンドユーザー向けの利用手順変更というより、開発プロセスへの影響が大きい更新です。PRはDraft状態で、少なくとも2件の承認レビューが必要な状態であることも確認できます。(GitHub)
影響範囲は次のように整理できます。
| 対象 | 影響度 | 理由 |
|---|---|---|
| DiskANNをライブラリとして使うだけの利用者 | 低 | API変更そのものではなく、主にドキュメントと開発指示の更新 |
| DiskANNをforkして改修する開発者 | 高 | 依存関係、公開API、テスト、unsafe、SIMDのレビュー基準が具体化されたため |
| GitHub CopilotやAIエージェントを使うチーム | 高 | AGENTS.md と .github/copilot-instructions.md により、AIが参照するルールが変わるため |
| CI/CD管理者 | 中 | Codecov、clippy、nextest、生成ベースラインの扱いを確認する必要があるため |
| 技術ドキュメント担当 | 中 | READMEの説明がDiskANN3とProvider API中心に整理され、社内資料の更新が必要になる可能性があるため |
移行・設定確認で見るべきポイント
旧agents.md参照をAGENTS.mdへ見直す
今回の変更では、旧 agents.md が AGENTS.md に移動されたコミットが含まれています。GitHubのファイル一覧でも AGENTS.md と agents.md の両方が差分対象として見えます。(GitHub)
Linuxのような大文字小文字を区別する環境では、agents.md と AGENTS.md は別ファイルです。ローカルでは動いてもCIで参照できない、というミスが起きやすいため、次のコマンドで参照を確認してください。
grep -R "agents.md" -n .
grep -R "AGENTS.md" -n .社内のAIエージェント設定、プロンプトテンプレート、オンボーディング資料、CIの補助スクリプトで agents.md を直接読んでいる場合は、AGENTS.md へ更新する必要があります。
.github/instructions.mdへの直接依存をやめる
削除対象になっている .github/instructions.md は、旧来の簡易チェックリストでした。内容は、ユニットテスト削除の理由、依存関係追加の妥当性、ビルド時間、ライセンスヘッダーなどに限られていました。(GitHub)
現在のGitHubドキュメントで案内されているパス固有のカスタム指示は .github/instructions/NAME.instructions.md 形式です。.github/instructions.md を社内運用で独自に読んでいる場合は、新しい .github/copilot-instructions.md か AGENTS.md へ寄せるのが安全です。(GitHub Docs)
PRテンプレートに移行影響と依存関係の説明欄を追加する
Copilot向け指示では、公開挙動を変える場合にPR説明で移行影響を説明すること、依存関係追加時に理由を書くことが求められています。(GitHub)
チームで使うPRテンプレートには、次の欄を追加するとレビューが楽になります。
### Migration impact
- Public API changes:
- Behavior changes:
- Compatibility shim or deprecation plan:
### Dependency impact
- New dependencies:
- Reason:
- Build time or binary size impact:
### Validation
- cargo fmt:
- cargo clippy:
- cargo test:
- Baseline regeneration:AIエージェントがPR本文を自動生成する場合も、このテンプレートを使わせると抜け漏れを減らせます。
Copilot Code Reviewの設定を確認する
GitHub公式ドキュメントでは、Copilot Code Reviewでカスタム命令を使うには、個人設定で利用が有効になっている必要があり、既定では有効とされています。(GitHub Docs)
チームで確認すべきポイントは次の3つです。
| 確認項目 | 確認理由 |
|---|---|
.github/copilot-instructions.md がリポジトリに存在するか | Copilotがリポジトリ全体の指示を参照できるようにするため |
| Copilot Code Reviewのカスタム命令利用が有効か | 追加したレビュー基準が実際のレビューに反映されるため |
AGENTS.md と内容が矛盾していないか | AIエージェントが相反する指示を受けないようにするため |
Codecovの警告は最終確認が必要
PR上のCodecovコメントでは、変更されたcoverable linesはすべてテストでカバーされていること、プロジェクトカバレッジが89.47%であることが示されています。一方で、レポートがmainより15コミット遅れているという警告も表示されています。(GitHub)
ドキュメント中心のPRであっても、最終マージ前には最新mainに追従した状態でCIとカバレッジを確認するのが安全です。特にAIエージェント向け指示はCI設定やテストの扱いに影響するため、PRがDraftからReady for reviewへ移るタイミングで再確認しましょう。
実務で起きやすい失敗と対策
| 失敗しやすいポイント | 起きる問題 | 対策 |
|---|---|---|
agents.md のまま参照している | CIやAIツールが新しい AGENTS.md を読めない | 大文字小文字を含めて参照先を検索・修正する |
| READMEだけを更新してdoc commentを放置する | AIや利用者が古いAPI例を使う | API変更時はREADME、doc comment、サンプルを同時に更新する |
| 依存関係をAIが勝手に追加する | ビルド時間やライセンス確認が増える | PR説明に追加理由を必須化する |
| テストベースラインを手編集する | 回帰検知の信頼性が落ちる | DISKANN_TEST=overwrite で再生成し、JSON差分をレビューする |
unsafe コメントが抽象的 | レビューで安全条件を検証できない | 境界、アライメント、非null、初期化済みなど具体条件を書く |
| x86だけでSIMDを確認する | ArmやAVX非対応環境で失敗する | AVX-512、Aarch64、x86-64基本環境を意識して検証する |
自分のリポジトリにも応用するなら
今回の更新は、DiskANNだけでなく、AIコーディングエージェントを使う多くの開発チームに応用できます。特に、AIがコードを書くだけでなくPR作成、レビュー、テスト修正まで関わる場合、ルールをチャットで毎回説明する運用は破綻しやすくなります。
自社リポジトリで導入するなら、まず次の3点だけでも整備すると効果があります。
## Repository boundaries
- Do not modify generated files by hand.
- Do not change CI workflows without approval.
- Do not add dependencies without explaining the reason.
## Required checks
- Run formatter.
- Run linter.
- Run relevant tests.
- Update documentation when public APIs change.
## Review focus
- Public API compatibility.
- Error handling.
- Security and secrets.
- Unsafe or platform-specific code.ポイントは、AIに「いい感じに直して」と依頼するのではなく、どこまで触ってよいか、何を実行すべきか、何を書き残すべきかをリポジトリ内に固定することです。今回のDiskANN更新は、その実例として参考になります。
次に取るべき行動
今回の Microsoft developer platform documentation update を受けて、まずやるべきことはコード修正ではなく確認です。DiskANNを参照している場合は、PRがDraftであることを前提に、マージ状況を確認したうえでREADMEと AGENTS.md の内容を読み直してください。AIエージェントやCopilotを使っているチームは、.github/copilot-instructions.md、AGENTS.md、旧 .github/instructions.md の参照有無を確認し、レビュー基準やPRテンプレートに反映するのが安全です。
特に、公開API、依存関係、テストベースライン、unsafeコード、SIMD、Rayonの扱いは、AIが変更しやすく、人間が見落としやすい領域です。今回の更新を「ドキュメント変更」と軽く見ず、AIを開発プロセスに組み込むためのガードレールとして点検しましょう。
コメント