> ## 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) 및 Microsoft GDK with XBOX Extensions (GDKX)에 적용됩니다.

## 시작하기 전에

* GDK를 설치합니다. 예제에서는 2026년 10월 GDK(에디션 `261000`)를 사용합니다. `261000`을 게임 빌드에 사용하는 에디션으로 바꾸세요.
* MCP(Model Context Protocol) 서버에 연결하거나, 컴퓨터의 파일을 읽거나, 명령을 실행할 수 있는 에이전트를 사용합니다. 대부분의 코딩 에이전트는 세 가지를 모두 수행할 수 있습니다.
* 조직에서 기밀 콘텐츠에 사용하도록 승인한 AI 도구를 확인합니다. GDKX 문서, 헤더, 도구는 기밀입니다.

## 에이전트에 제공할 GDK 컨텍스트 선택

| 소스 | 에이전트가 얻는 정보 | 버전 | 액세스 |
| - | - | - | - |
| XBOX 문서 MCP 서버 | 게시된 XBOX 문서에 대한 검색 및 조회 | 현재 온라인 문서 | 공개 |
| `llms.txt`, `llms-full.txt` 및 Markdown 페이지 | 모든 페이지의 인덱스, 문서 전체 텍스트 또는 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/ko.md#xbox-home-ai-title)을 참조하세요.

MCP를 사용할 수 없는 에이전트는 다른 형식으로 문서를 읽을 수 있습니다.

* `https://docs.xbox.com/llms.txt`에는 모든 페이지가 간단한 설명과 함께 나열되어 있습니다.
* `https://docs.xbox.com/llms-full.txt`에는 문서의 전체 텍스트가 하나의 파일에 포함되어 있습니다.
* 페이지 URL 끝에 `.md`를 추가하면 해당 페이지를 Markdown으로 가져올 수 있습니다.

## 에이전트에 오프라인 문서 제공

GDKX는 GDK 문서를 GDK 에디션의 `xbox\documentation` 폴더에 있는 `GDKDocumentationMarkdown.zip`에 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/ko/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를 확인하도록 에이전트에 지시하세요.

## 에이전트가 명령줄에서 빌드하도록 설정

빌드하려면 에이전트에 게이밍 명령 프롬프트와 동일한 환경이 필요합니다. 시작 메뉴 바로 가기에서 사용하는 인수로 `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/ko/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [GDK 프로젝트 템플릿을 사용하여 새 타이틀 개발 시작](https://docs.xbox.com/ko/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/ko/tools/xbox-cli/cli-for-agents.md)
- [XBOX Development Kit 관리용 DevKit Agent](https://docs.xbox.com/ko/tools/tools-console/devkitagent/devkitagent-overview.md)
- [안전 및 파괴적 작업](https://docs.xbox.com/ko/tools/xbox-cli/safety.md)
- [XBOX CLI](https://docs.xbox.com/ko/tools/xbox-cli/index.md)
- [PlayFab GSDK(Game Server SDK)와 게임 서버 통합](https://docs.xbox.com/ko/services/playfab/multiplayer/servers/integrating-game-servers-with-gsdk.md)
