메인 콘텐츠로 건너뛰기
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 컨텍스트 선택

온라인 소스는 현재 GDK를 설명합니다. 이전 GDK로 빌드하는 경우 설치된 헤더와 오프라인 문서도 에이전트에 제공하여 사용 중인 GDK에 없는 API를 에이전트가 사용하지 않도록 하세요.

XBOX 문서 MCP 서버 연결

https://docs.xbox.com/mcp의 XBOX 문서 MCP 서버를 사용하면 에이전트가 게시된 문서를 검색하고 인용할 수 있습니다. API 키나 로그인이 필요하지 않습니다. 예를 들어 Visual Studio Code에서는 프로젝트의 .vscode/mcp.json 파일에 서버를 추가합니다.
.vscode/mcp.json
Claude Code, GitHub Copilot CLI, Cursor, Codex, Claude의 설정 단계는 홈페이지의 AI 도구에서 이 문서 사용을 참조하세요. 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 파일에는 페이지 목록이 있습니다.
아카이브에는 기밀 페이지가 포함되어 있습니다. 전체 아카이브는 조직에서 기밀 GDKX 콘텐츠에 사용하도록 승인한 AI 도구에서만 사용하세요. 추출한 파일을 공개 리포지토리나 조직 외부 사용자가 읽을 수 있는 위치에 추가하지 마세요.
  1. 소스 리포지토리 외부의 폴더에 아카이브를 추출합니다. PowerShell에서 다음 명령을 실행합니다.
  2. AI 도구가 기밀 콘텐츠에 대해 승인되지 않은 경우 공개 페이지만 유지합니다. 다음 명령은 permissioned-type이 public이 아닌 모든 Markdown 파일을 삭제하며, 해당 필드가 없는 파일도 삭제합니다.
  3. 에이전트가 폴더에 액세스할 수 있도록 합니다. 예를 들어 편집기의 작업 영역에 폴더를 추가하거나 프로젝트 지침 파일에 폴더를 명시합니다.
설치하는 GDK 에디션마다 해당 에디션 이름으로 된 폴더에 아카이브를 다시 추출하세요.

에이전트가 설치된 헤더와 도구를 참조하도록 설정

GDK 설치 프로그램은 설치된 GDK의 위치를 에이전트에 알려 주는 환경 변수를 설정합니다.
  • GameDK는 GDK 루트 폴더입니다. 이 폴더에는 명령줄 도구가 있는 bin 폴더와 %GameDK%261000\과 같이 설치된 각 에디션의 폴더가 있습니다.
  • GameDKCoreLatest 및 GameDKXboxLatest는 가장 최근에 설치된 에디션을 가리킵니다.
여러 에디션이 나란히 설치된 경우 가장 최근 에디션이 게임 빌드에 사용하는 에디션이 아닐 수 있습니다. 이러한 변수 대신 %GameDK%261000\과 같이 게임에서 사용하는 에디션 폴더를 에이전트에 제공하세요. 각 에디션 아래의 폴더에 대해서는 GDK 헤더 및 라이브러리 디렉터리 구조를 참조하세요. API를 사용하기 전에 PC의 경우 에디션의 windows\include 폴더, XBOX 콘솔의 경우 xbox\include 폴더 아래에 있는 헤더에서 선언을 확인하도록 에이전트에 지시하세요. XBOX 서비스 API(XSAPI), libHttpClient, PlayFab 헤더와 같은 일부 헤더에는 각 API를 설명하는 문서 주석도 포함되어 있습니다. %GameDK%bin의 명령줄 도구는 /?와 함께 실행하면 사용법을 출력합니다. 에이전트는 도구의 옵션을 추측하는 대신 도구를 사용하기 전에 해당 도구의 /?를 실행할 수 있습니다. HRESULT를 설명으로 변환하려면 xberror.exe를 사용하세요.

에이전트에 버전이 일치하는 샘플 코드 제공

XBOX GDK 샘플 목록을 사용하여 구현 중인 기능의 예제를 찾으세요. 리포지토리 및 샘플 README에서 GDK 버전, 디렉터리 레이아웃, 플랫폼 요구 사항을 확인하세요. main 분기가 프로젝트와 맞지 않으면 호환되는 샘플 릴리스를 선택하세요. 호환되는 릴리스를 복제하거나 다운로드하고 관련 샘플의 소스와 README에 대한 로컬 경로를 에이전트에 제공하세요. 샘플의 초기화, 오류 처리, 비동기 수명, 정리 패턴을 따르도록 에이전트에 요청하세요. 다른 GDK 레이아웃의 프로젝트 설정을 복사하는 대신 설치된 헤더를 기준으로 API를 확인하도록 에이전트에 지시하세요.

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

빌드하려면 에이전트에 게이밍 명령 프롬프트와 동일한 환경이 필요합니다. 시작 메뉴 바로 가기에서 사용하는 인수로 GamingDesktopVars.cmd를 실행한 다음 동일한 cmd 프로세스에서 빌드를 실행하세요.
Visual Studio 2022의 경우 GamingDesktopVS2022를 사용하세요. 환경은 별도의 명령 간에 유지되지 않으므로 에이전트는 스크립트와 빌드를 함께 실행해야 합니다.

프로젝트 지침 파일 추가

대부분의 코딩 에이전트는 리포지토리 루트에 있는 AGENTS.md 또는 .github/copilot-instructions.md와 같은 프로젝트 지침 파일을 읽습니다. 이 파일을 사용하여 모든 에이전트 세션에 동일한 GDK 컨텍스트를 제공하세요. 다음 예제에서 시작하여 꺾쇠괄호 안의 값을 바꾸세요.
AGENTS.md

에이전트의 작업 검토

변경 사항을 검토하기 전에 에이전트에 작업을 자체 검토하도록 요청하세요. 예를 들어 다음 프롬프트를 제공합니다.
자체 검토가 사용자의 검토를 대신하지는 않습니다. 에이전트가 작성한 코드도 다른 코드와 마찬가지로 검토하고 테스트하세요. 플랫폼 지원, 정책, 인증 요구 사항에 대한 주장은 에이전트의 답변이 아니라 문서에서 확인하세요.

참고 항목

마지막 수정일 2026년 11월 19일