Pular para o conteúdo principal
Agentes de codificação de IA, como GitHub Copilot, Claude Code, Codex e Cursor, escrevem um código do GDK melhor quando trabalham com base nas APIs e na documentação do GDK com o qual você faz o build, em vez de com base no que o modelo deles lembra. Este artigo descreve o contexto do GDK que você pode fornecer a um agente e como configurar cada fonte. Estas orientações se aplicam ao Microsoft Game Development Kit (GDK) e ao Microsoft GDK com XBOX Extensions (GDKX) em um computador de desenvolvimento Windows PC.

Antes de começar

  • Instale o GDK. Os exemplos usam o GDK de outubro de 2026 (edição 261000). Substitua 261000 pela edição com a qual seu jogo faz o build.
  • Use um agente que possa se conectar a um servidor Model Context Protocol (MCP), ler arquivos no seu computador ou executar comandos. A maioria dos agentes de codificação pode fazer as três coisas.
  • Descubra quais ferramentas de IA sua organização aprova para conteúdo confidencial. A documentação, os cabeçalhos e as ferramentas do GDKX são confidenciais.

Escolher o contexto do GDK a ser fornecido ao agente

As fontes online descrevem o GDK atual. Quando você fizer o build com um GDK anterior, forneça também ao agente os cabeçalhos instalados e a documentação offline, para que ele não use APIs que o seu GDK não tem.

Conectar o servidor MCP da documentação do XBOX

O servidor MCP da documentação do XBOX em https://docs.xbox.com/mcp permite que um agente pesquise e cite a documentação publicada. Não é necessário ter uma chave de API nem entrar. Por exemplo, no Visual Studio Code, adicione o servidor a um arquivo .vscode/mcp.json no seu projeto:
.vscode/mcp.json
Para ver as etapas de configuração do Claude Code, GitHub Copilot CLI, Cursor, Codex e Claude, consulte Use esta documentação com ferramentas de IA na página inicial. Agentes que não podem usar MCP podem ler a documentação em outros formatos:
  • https://docs.xbox.com/llms.txt lista todas as páginas com uma breve descrição.
  • https://docs.xbox.com/llms-full.txt contém o texto completo da documentação em um único arquivo.
  • Adicione .md ao final da URL de qualquer página para obter essa página como Markdown.

Fornecer ao agente a documentação offline

O GDKX instala a documentação do GDK como arquivos Markdown em GDKDocumentationMarkdown.zip, na pasta xbox\documentation da edição do GDK. Como os arquivos correspondem ao GDK que você instalou, eles são a fonte de documentação mais precisa para essa versão. Cada página começa com um frontmatter YAML. O valor permissioned-type indica a classificação de acesso da página: public, private ou secret. O arquivo site-map.md na raiz do arquivo compactado lista as páginas.
O arquivo compactado contém páginas confidenciais. Use o arquivo compactado completo somente com ferramentas de IA que sua organização aprova para conteúdo confidencial do GDKX. Não adicione os arquivos extraídos a um repositório público nem a qualquer local que pessoas de fora da sua organização possam ler.
  1. Extraia o arquivo compactado para uma pasta fora do seu repositório de código-fonte. No PowerShell, execute os comandos a seguir.
  2. Se a sua ferramenta de IA não for aprovada para conteúdo confidencial, mantenha apenas as páginas públicas. O comando a seguir exclui todos os arquivos Markdown cujo permissioned-type não seja public, incluindo arquivos que não têm o campo.
  3. Dê ao agente acesso à pasta. Por exemplo, adicione-a ao workspace do seu editor ou cite-a no arquivo de instruções do projeto.
Extraia o arquivo compactado novamente para cada edição do GDK que você instalar, em uma pasta com o nome dessa edição.

Direcionar o agente para os cabeçalhos e as ferramentas instalados

O instalador do GDK define variáveis de ambiente que fornecem ao agente o local do GDK instalado:
  • GameDK é a pasta raiz do GDK. Ela contém a pasta bin das ferramentas de linha de comando e uma pasta para cada edição instalada, como %GameDK%261000\.
  • GameDKCoreLatest e GameDKXboxLatest apontam para a edição instalada mais recente.
Quando mais de uma edição está instalada lado a lado, a edição mais recente pode não ser aquela com a qual seu jogo faz o build. Forneça ao agente a pasta da edição que seu jogo usa, como %GameDK%261000\, em vez dessas variáveis. Para ver as pastas em cada edição, consulte Estrutura de diretórios de cabeçalhos e bibliotecas do GDK. Instrua o agente a verificar as declarações nos cabeçalhos da pasta windows\include da edição, para PC, ou da pasta xbox\include, para consoles XBOX, antes de usar uma API. Alguns cabeçalhos, como os cabeçalhos da API de serviços do XBOX (XSAPI), do libHttpClient e do PlayFab, também incluem comentários de documentação que descrevem cada API. As ferramentas de linha de comando em %GameDK%bin exibem seu uso quando você as executa com /?. Um agente pode executar o /? de uma ferramenta antes de usá-la, em vez de adivinhar as opções dela. Para converter um HRESULT em uma descrição, use xberror.exe:

Fornecer ao agente código de exemplo compatível com a versão

Use a lista de exemplos do XBOX GDK para encontrar exemplos do recurso que você está implementando. Verifique os READMEs do repositório e do exemplo para saber a versão do GDK, o layout de diretórios e os requisitos de plataforma. Se o branch principal não corresponder ao seu projeto, escolha uma versão dos exemplos compatível. Clone ou baixe a versão compatível e forneça ao agente os caminhos locais do código-fonte e do README do exemplo relevante. Peça a ele que siga os padrões de inicialização, tratamento de erros, tempo de vida assíncrono e limpeza do exemplo. Faça o agente verificar as APIs nos cabeçalhos instalados em vez de copiar configurações de projeto de um layout de GDK diferente.

Permitir que o agente faça o build pela linha de comando

Para fazer o build, um agente precisa do mesmo ambiente de um Gaming Command Prompt. Execute GamingDesktopVars.cmd com os argumentos que o atalho do menu Iniciar usa e, em seguida, execute o build no mesmo processo cmd:
Use GamingDesktopVS2022 para o Visual Studio 2022. O ambiente não é mantido entre comandos separados, portanto, o agente deve executar o script e o build juntos.

Adicionar um arquivo de instruções do projeto

A maioria dos agentes de codificação lê um arquivo de instruções do projeto, como AGENTS.md ou .github/copilot-instructions.md, na raiz do seu repositório. Use-o para fornecer o mesmo contexto do GDK a todas as sessões do agente. Comece pelo exemplo a seguir e substitua os valores entre colchetes angulares.
AGENTS.md

Revisar o trabalho do agente

Antes de revisar uma alteração, peça ao agente que faça uma autorrevisão do trabalho dele. Por exemplo, forneça a ele este prompt:
A autorrevisão não substitui a sua revisão. Revise e teste o código escrito pelo agente como faria com qualquer outro código. Verifique as afirmações sobre suporte a plataformas, políticas e requisitos de certificação na documentação, e não na resposta do agente.

Confira também

Última modificação em 19 de novembro de 2026