시작하기 전에
- 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
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 파일에는 페이지 목록이 있습니다.
-
소스 리포지토리 외부의 폴더에 아카이브를 추출합니다. PowerShell에서 다음 명령을 실행합니다.
-
AI 도구가 기밀 콘텐츠에 대해 승인되지 않은 경우 공개 페이지만 유지합니다. 다음 명령은
permissioned-type이public이 아닌 모든 Markdown 파일을 삭제하며, 해당 필드가 없는 파일도 삭제합니다. - 에이전트가 폴더에 액세스할 수 있도록 합니다. 예를 들어 편집기의 작업 영역에 폴더를 추가하거나 프로젝트 지침 파일에 폴더를 명시합니다.
에이전트가 설치된 헤더와 도구를 참조하도록 설정
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 프로세스에서 빌드를 실행하세요.
GamingDesktopVS2022를 사용하세요. 환경은 별도의 명령 간에 유지되지 않으므로 에이전트는 스크립트와 빌드를 함께 실행해야 합니다.
프로젝트 지침 파일 추가
대부분의 코딩 에이전트는 리포지토리 루트에 있는AGENTS.md 또는 .github/copilot-instructions.md와 같은 프로젝트 지침 파일을 읽습니다. 이 파일을 사용하여 모든 에이전트 세션에 동일한 GDK 컨텍스트를 제공하세요. 다음 예제에서 시작하여 꺾쇠괄호 안의 값을 바꾸세요.
AGENTS.md
