> ## 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.

# Usar agentes de codificação de IA com o GDK

> Forneça aos agentes de codificação de IA um contexto preciso e compatível com a versão do Microsoft Game Development Kit (GDK): o servidor MCP da documentação, a documentação offline em Markdown, os cabeçalhos instalados, as ferramentas de linha de comando e um arquivo de instruções do projeto.

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

| Fonte | O que o agente recebe | Versão | Acesso |
| - | - | - | - |
| Servidor MCP da documentação do XBOX | Pesquisa e recuperação na documentação publicada do XBOX | Documentação online atual | Público |
| `llms.txt`, `llms-full.txt` e páginas em Markdown | Um índice de todas as páginas, o texto completo da documentação ou uma página como Markdown | Documentação online atual | Público |
| Documentação offline em Markdown | A documentação do GDK como arquivos Markdown | Corresponde ao GDK instalado | Páginas públicas e confidenciais |
| Cabeçalhos instalados | Declarações exatas e comentários de documentação em alguns cabeçalhos | Corresponde ao GDK instalado | Corresponde ao GDK que você instalou |
| Ferramentas de linha de comando | Texto de uso e descrições de erros fornecidos pelas próprias ferramentas | Corresponde ao GDK instalado | Corresponde ao GDK que você instalou |
| [Exemplos do XBOX GDK](https://github.com/microsoft/Xbox-GDK-Samples) | Exemplos completos e prontos para build | Marcados por versão do GDK | Público |

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:

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

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](https://docs.xbox.com/pt-BR.md#xbox-home-ai-title) 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.

> [!WARNING]
>
> 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.

   ```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. 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.

   ```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. 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](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/gdk-directory-structure.md). 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`:

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

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

Use a [lista de exemplos do XBOX GDK](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/gdk-samples-list.md) 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](https://github.com/microsoft/Xbox-GDK-Samples/releases) 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`:

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

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.

```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.
```

## 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:

```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.
```

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

* [Estrutura de diretórios de cabeçalhos e bibliotecas do GDK](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [Iniciar o desenvolvimento de um novo título usando modelos de projeto do GDK](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/gdk-project-templates.md)
* [Exemplos do XBOX GDK no GitHub](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [Usar a XBOX CLI a partir de agentes](https://docs.xbox.com/pt-BR/tools/xbox-cli/cli-for-agents.md)
- [Biblioteca de codificação xWMA e ferramenta de linha de comando](https://docs.xbox.com/pt-BR/build/console-features/audio/tools/xwmaencoder/index.md)
- [Estrutura de diretórios de cabeçalhos e bibliotecas do GDK](https://docs.xbox.com/pt-BR/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [Biblioteca de codificação XMA2 e ferramenta de linha de comando](https://docs.xbox.com/pt-BR/build/console-features/audio/tools/xma2encoder/index.md)
- [Implementação do Game Saves com o GDK de outubro de 2025](https://docs.xbox.com/pt-BR/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
