> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GDK で AI コーディング エージェントを使用する

> AI コーディング エージェントに、正確でバージョンが一致した Microsoft Game Development Kit (GDK) のコンテキストを提供します。対象は、ドキュメント MCP サーバー、オフラインの Markdown ドキュメント、インストール済みのヘッダー、コマンドライン ツール、プロジェクト指示ファイルです。

GitHub Copilot、Claude Code、Codex、Cursor などの AI コーディング エージェントは、モデルが記憶している内容ではなく、ビルドに使用する GDK の API とドキュメントに基づいて作業すると、より適切な GDK コードを記述できます。この記事では、エージェントに提供できる GDK のコンテキストと、各ソースの設定方法について説明します。

このガイダンスは、開発用の Windows PC 上の Microsoft Game Development Kit (GDK) と XBOX 拡張機能付き Microsoft GDK (GDKX) に適用されます。

## 開始する前に

* GDK をインストールします。例では October 2026 GDK (エディション `261000`) を使用しています。`261000` は、ゲームのビルドに使用するエディションに置き換えてください。
* Model Context Protocol (MCP) サーバーへの接続、コンピューター上のファイルの読み取り、コマンドの実行のいずれかが可能なエージェントを使用します。ほとんどのコーディング エージェントは、これら 3 つすべてに対応しています。
* 機密コンテンツに対して組織が承認している AI ツールを確認します。GDKX のドキュメント、ヘッダー、ツールは機密情報です。

## エージェントに提供する GDK のコンテキストを選択する

| ソース | エージェントが取得する内容 | バージョン | アクセス |
| - | - | - | - |
| XBOX ドキュメント MCP サーバー | 公開されている XBOX ドキュメントの検索と取得 | 現在のオンライン ドキュメント | 公開 |
| `llms.txt`、`llms-full.txt`、Markdown ページ | 全ページのインデックス、ドキュメントの全文、または 1 ページ分の Markdown | 現在のオンライン ドキュメント | 公開 |
| オフラインの Markdown ドキュメント | Markdown ファイル形式の GDK ドキュメント | インストール済みの GDK と一致 | 公開ページと機密ページ |
| インストール済みのヘッダー | 正確な宣言と、一部のヘッダーに含まれるドキュメント コメント | インストール済みの GDK と一致 | インストールした GDK と同じ |
| コマンドライン ツール | ツール自体が出力する使用方法のテキストとエラーの説明 | インストール済みの GDK と一致 | インストールした GDK と同じ |
| [XBOX GDK サンプル](https://github.com/microsoft/Xbox-GDK-Samples) | ビルド可能な完全なサンプル | GDK リリースごとにタグ付け | 公開 |

オンラインのソースは、現在の GDK について説明しています。以前の GDK でビルドする場合は、インストール済みのヘッダーとオフラインのドキュメントもエージェントに提供して、使用している GDK に存在しない API をエージェントが使用しないようにします。

## XBOX ドキュメント MCP サーバーに接続する

`https://docs.xbox.com/mcp` にある XBOX ドキュメント MCP サーバーを使用すると、エージェントは公開されているドキュメントを検索して引用できます。API キーやサインインは必要ありません。たとえば Visual Studio Code では、プロジェクトの `.vscode/mcp.json` ファイルにサーバーを追加します。

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "xbox-docs": {
      "type": "http",
      "url": "https://docs.xbox.com/mcp"
    }
  }
}
```

Claude Code、GitHub Copilot CLI、Cursor、Codex、Claude の設定手順については、ホーム ページの [AI ツールでこれらのドキュメントを使用する](https://docs.xbox.com/ja-jp.md#xbox-home-ai-title) を参照してください。

MCP を使用できないエージェントは、別の形式でドキュメントを読み取れます。

* `https://docs.xbox.com/llms.txt` には、全ページが短い説明とともに一覧表示されます。
* `https://docs.xbox.com/llms-full.txt` には、ドキュメントの全文が 1 つのファイルに含まれています。
* 任意のページの URL の末尾に `.md` を追加すると、そのページを Markdown として取得できます。

## エージェントにオフラインのドキュメントを提供する

GDKX は、GDK エディションの `xbox\documentation` フォルダーにある `GDKDocumentationMarkdown.zip` に、GDK のドキュメントを Markdown ファイルとしてインストールします。これらのファイルはインストールした GDK と一致するため、そのバージョンに関して最も正確なドキュメント ソースになります。

各ページは YAML フロントマターで始まります。`permissioned-type` の値は、ページのアクセス分類 (`public`、`private`、`secret` のいずれか) を示します。アーカイブのルートにある `site-map.md` ファイルには、ページの一覧が含まれています。

> [!WARNING]
>
> このアーカイブには機密ページが含まれています。アーカイブ全体は、機密の GDKX コンテンツに対して組織が承認している AI ツールでのみ使用してください。展開したファイルを、公開リポジトリや組織外のユーザーが読み取れる場所に追加しないでください。

1. ソース リポジトリの外にあるフォルダーにアーカイブを展開します。PowerShell で次のコマンドを実行します。

   ```powershell theme={null}
   $edition = '261000'
   $zip  = Join-Path $env:GameDK "$edition\xbox\documentation\GDKDocumentationMarkdown.zip"
   $dest = "$env:USERPROFILE\gdk-docs\$edition"
   Expand-Archive -Path $zip -DestinationPath $dest
   ```

2. AI ツールが機密コンテンツに対して承認されていない場合は、公開ページのみを残します。次のコマンドは、`permissioned-type` が `public` ではない Markdown ファイルをすべて削除します。このフィールドを持たないファイルも削除されます。

   ```powershell theme={null}
   Get-ChildItem $dest -Recurse -Filter *.md |
     Where-Object { -not (Get-Content $_.FullName -TotalCount 25 |
       Select-String -Quiet '^permissioned-type:\s*public\s*$') } |
     Remove-Item
   ```

3. エージェントにフォルダーへのアクセスを許可します。たとえば、フォルダーをエディターのワークスペースに追加するか、プロジェクト指示ファイルでフォルダーを指定します。

インストールする GDK エディションごとに、そのエディション名を付けたフォルダーにアーカイブを改めて展開してください。

## インストール済みのヘッダーとツールをエージェントに示す

GDK インストーラーは、インストール済みの GDK の場所をエージェントに伝える環境変数を設定します。

* `GameDK` は GDK のルート フォルダーです。コマンドライン ツールの `bin` フォルダーと、`%GameDK%261000\` などのインストール済みの各エディションのフォルダーが含まれています。
* `GameDKCoreLatest` と `GameDKXboxLatest` は、インストール済みの最新のエディションを指します。

複数のエディションを並行してインストールしている場合、最新のエディションがゲームのビルドに使用しているエディションであるとは限りません。これらの変数ではなく、`%GameDK%261000\` など、ゲームで使用しているエディションのフォルダーをエージェントに指定してください。

各エディションの下にあるフォルダーについては、[GDK のヘッダーとライブラリのディレクトリ構造](https://docs.xbox.com/ja-jp/build/gdk-and-engines/guides/gdk-directory-structure.md) を参照してください。API を使用する前に、PC の場合はエディションの `windows\include` フォルダー、XBOX 本体の場合は `xbox\include` フォルダーにあるヘッダーで宣言を確認するよう、エージェントに指示します。XBOX サービス API (XSAPI)、libHttpClient、PlayFab のヘッダーなど、一部のヘッダーには、各 API について説明するドキュメント コメントも含まれています。

`%GameDK%bin` にあるコマンドライン ツールは、`/?` を付けて実行すると使用方法を出力します。エージェントは、ツールのオプションを推測する代わりに、ツールを使用する前にそのツールの `/?` を実行できます。`HRESULT` を説明に変換するには、`xberror.exe` を使用します。

```cmd theme={null}
"%GameDK%bin\xberror.exe" 0x8015DC12
```

## バージョンが一致したサンプル コードをエージェントに提供する

[XBOX GDK サンプルの一覧](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/gdk-samples-list.md) を使用して、実装する機能のサンプルを見つけます。リポジトリとサンプルの README で、GDK のバージョン、ディレクトリ レイアウト、プラットフォームの要件を確認します。main ブランチがプロジェクトと一致しない場合は、互換性のある [サンプル リリース](https://github.com/microsoft/Xbox-GDK-Samples/releases) を選択します。

互換性のあるリリースをクローンまたはダウンロードし、該当するサンプルのソースと README のローカル パスをエージェントに提供します。サンプルの初期化、エラー処理、非同期処理の有効期間、クリーンアップのパターンに従うよう、エージェントに指示します。別の GDK レイアウトからプロジェクト設定をコピーするのではなく、インストール済みのヘッダーに照らして API を検証するよう、エージェントに指示してください。

## エージェントにコマンドラインからビルドさせる

ビルドを行うには、エージェントに Gaming Command Prompt と同じ環境が必要です。スタート メニューのショートカットで使用されている引数を指定して `GamingDesktopVars.cmd` を実行し、同じ `cmd` プロセスでビルドを実行します。

```cmd theme={null}
cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 261000 && msbuild MyGame.sln /p:Configuration=Debug /p:Platform=Gaming.Desktop.x64"
```

Visual Studio 2022 の場合は `GamingDesktopVS2022` を使用します。環境は別々のコマンド間で引き継がれないため、エージェントはスクリプトとビルドを一緒に実行する必要があります。

## プロジェクト指示ファイルを追加する

ほとんどのコーディング エージェントは、リポジトリのルートにある `AGENTS.md` や `.github/copilot-instructions.md` などのプロジェクト指示ファイルを読み取ります。このファイルを使用して、すべてのエージェント セッションに同じ GDK のコンテキストを提供します。次の例をもとに、山かっこで囲まれた値を置き換えてください。

```markdown AGENTS.md theme={null}
# GDK project instructions

- This game uses the Microsoft Game Development Kit (GDK) <edition, for example 261000 (October 2026)>.
  Target platforms: <Gaming.Desktop.x64, Gaming.Xbox.Scarlett.x64>.
- Before you use a GDK API, check its declaration in the headers of this edition:
  %GameDK%<edition>\windows\include for PC and %GameDK%<edition>\xbox\include for XBOX consoles.
  Don't use an API that the headers for the target platform don't declare.
- Search the XBOX docs with the xbox-docs MCP server. For the documentation of this GDK
  edition, read the Markdown files in <%USERPROFILE%\gdk-docs\261000>.
- Use the sample source and README in <local path to a compatible XBOX GDK sample>.
  Check its GDK version, directory layout, and platform requirements before adapting code.
- Build: cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 <edition> && msbuild <solution> /p:Platform=Gaming.Desktop.x64"
- Run a GDK tool with /? before you use it. Translate HRESULT values with xberror.
- Before handing back a change, review the diff for correctness and unintended changes.
  Run the build and relevant tests. Report the commands, results, and anything you couldn't verify.
- Don't copy confidential GDKX content into public files or into tools that aren't approved for it.
```

## エージェントの作業をレビューする

変更をレビューする前に、エージェントに自身の作業をセルフレビューするよう依頼します。たとえば、次のプロンプトを指定します。

```text theme={null}
Review your diff against the task and project instructions before handing it back.
Check HRESULT handling, asynchronous completion or cancellation, resource cleanup,
and API availability in the installed GDK edition for each target platform.
Look for unintended behavior changes and missing tests for the changed behavior.
Fix the issues you find, then run the build and relevant tests for the affected targets.
Report remaining concerns, the exact commands and results, and anything you couldn't verify.
Don't claim a build, test, or platform check passed unless you ran it successfully.
```

セルフレビューは、あなた自身によるレビューの代わりにはなりません。エージェントが記述したコードも、他のコードと同様にレビューしてテストしてください。プラットフォームのサポート、ポリシー、サーティフィケーションの要件に関する主張は、エージェントの回答ではなくドキュメントで確認してください。

## 関連項目

* [GDK のヘッダーとライブラリのディレクトリ構造](https://docs.xbox.com/ja-jp/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [GDK プロジェクト テンプレートを使用した新しいタイトルの開発の開始](https://docs.xbox.com/ja-jp/build/gdk-and-engines/guides/gdk-project-templates.md)
* [GitHub の XBOX GDK サンプル](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [エージェントから XBOX CLI を使用する](https://docs.xbox.com/ja-jp/tools/xbox-cli/cli-for-agents.md)
- [XBOX パートナー オンボーディング](https://docs.xbox.com/ja-jp/home/onboarding.md)
- [本体向け Microsoft Game Development Kit (GDK) で Clang を使用する](https://docs.xbox.com/ja-jp/tools/tools-console/visualstudio/vs-clang.md)
- [game_chat_audio_encoding_bitrate](https://docs.xbox.com/ja-jp/reference/chat/gamechat2/enums/game_chat_audio_encoding_bitrate.md)
- [GDK のヘッダーとライブラリのディレクトリ構造](https://docs.xbox.com/ja-jp/build/gdk-and-engines/guides/gdk-directory-structure.md)
