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

# Uso de agentes de codificación de IA con el GDK

> Proporcione a los agentes de codificación de IA contexto preciso del Microsoft Game Development Kit (GDK) que coincida con su versión: el servidor MCP de documentación, la documentación sin conexión en Markdown, los encabezados instalados, las herramientas de línea de comandos y un archivo de instrucciones del proyecto.

Los agentes de codificación de IA, como GitHub Copilot, Claude Code, Codex y Cursor, escriben mejor código del GDK cuando trabajan a partir de las API y la documentación del GDK con el que compila, en lugar de basarse en lo que recuerda su modelo. En este artículo se describe el contexto del GDK que puede proporcionar a un agente y cómo configurar cada fuente.

Esta guía se aplica al Microsoft Game Development Kit (GDK) y al Microsoft GDK con XBOX Extensions (GDKX) en un equipo de desarrollo con Windows.

## Antes de empezar

* Instale el GDK. En los ejemplos se usa el GDK de octubre de 2026 (edición `261000`). Reemplace `261000` por la edición con la que se compila su juego.
* Use un agente que pueda conectarse a un servidor de Model Context Protocol (MCP), leer archivos de su equipo o ejecutar comandos. La mayoría de los agentes de codificación pueden hacer las tres cosas.
* Averigüe qué herramientas de IA aprueba su organización para contenido confidencial. La documentación, los encabezados y las herramientas del GDKX son confidenciales.

## Elegir el contexto del GDK que se proporcionará al agente

| Fuente | Qué obtiene el agente | Versión | Acceso |
| - | - | - | - |
| Servidor MCP de la documentación de XBOX | Búsqueda y recuperación en la documentación publicada de XBOX | Documentación en línea actual | Público |
| `llms.txt`, `llms-full.txt` y páginas en Markdown | Un índice de todas las páginas, el texto completo de la documentación o una página en Markdown | Documentación en línea actual | Público |
| Documentación sin conexión en Markdown | La documentación del GDK como archivos Markdown | Coincide con el GDK instalado | Páginas públicas y confidenciales |
| Encabezados instalados | Declaraciones exactas y, en algunos encabezados, comentarios de documentación | Coincide con el GDK instalado | Coincide con el GDK que instaló |
| Herramientas de línea de comandos | Texto de uso y descripciones de errores de las propias herramientas | Coincide con el GDK instalado | Coincide con el GDK que instaló |
| [Ejemplos del GDK de XBOX](https://github.com/microsoft/Xbox-GDK-Samples) | Ejemplos completos que se pueden compilar | Etiquetados por versión del GDK | Público |

Las fuentes en línea describen el GDK actual. Si compila con un GDK anterior, proporcione también al agente los encabezados instalados y la documentación sin conexión, para que no use API que su GDK no tiene.

## Conectar el servidor MCP de la documentación de XBOX

El servidor MCP de la documentación de XBOX en `https://docs.xbox.com/mcp` permite que un agente busque y cite la documentación publicada. No requiere una clave de API ni iniciar sesión. Por ejemplo, en Visual Studio Code, agregue el servidor a un archivo `.vscode/mcp.json` de su proyecto:

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

Para ver los pasos de configuración de Claude Code, GitHub Copilot CLI, Cursor, Codex y Claude, consulte [Usar esta documentación con herramientas de IA](https://docs.xbox.com/es.md#xbox-home-ai-title) en la página principal.

Los agentes que no pueden usar MCP pueden leer la documentación en otros formatos:

* `https://docs.xbox.com/llms.txt` enumera todas las páginas con una breve descripción.
* `https://docs.xbox.com/llms-full.txt` contiene el texto completo de la documentación en un solo archivo.
* Agregue `.md` al final de la URL de cualquier página para obtener esa página en Markdown.

## Proporcionar al agente la documentación sin conexión

El GDKX instala la documentación del GDK como archivos Markdown en `GDKDocumentationMarkdown.zip`, en la carpeta `xbox\documentation` de la edición del GDK. Como los archivos coinciden con el GDK que instaló, son la fuente de documentación más precisa para esa versión.

Cada página comienza con frontmatter YAML. El valor `permissioned-type` indica la clasificación de acceso de la página: `public`, `private` o `secret`. El archivo `site-map.md` de la raíz del archivo comprimido enumera las páginas.

> [!WARNING]
>
> El archivo comprimido contiene páginas confidenciales. Use el archivo comprimido completo solo con herramientas de IA que su organización apruebe para contenido confidencial del GDKX. No agregue los archivos extraídos a un repositorio público ni a ninguna ubicación que puedan leer personas ajenas a su organización.

1. Extraiga el archivo comprimido en una carpeta fuera de su repositorio de código fuente. En PowerShell, ejecute los siguientes comandos.

   ```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. Si su herramienta de IA no está aprobada para contenido confidencial, conserve solo las páginas públicas. El siguiente comando elimina todos los archivos Markdown cuyo `permissioned-type` no sea `public`, incluidos los archivos que no tienen ese 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. Conceda al agente acceso a la carpeta. Por ejemplo, agréguela al área de trabajo de su editor o indíquela en el archivo de instrucciones del proyecto.

Vuelva a extraer el archivo comprimido para cada edición del GDK que instale, en una carpeta con el nombre de esa edición.

## Indicar al agente los encabezados y las herramientas instalados

El instalador del GDK establece variables de entorno que indican al agente la ubicación del GDK instalado:

* `GameDK` es la carpeta raíz del GDK. Contiene la carpeta `bin` de herramientas de línea de comandos y una carpeta para cada edición instalada, como `%GameDK%261000\`.
* `GameDKCoreLatest` y `GameDKXboxLatest` apuntan a la edición instalada más reciente.

Si hay más de una edición instalada en paralelo, es posible que la edición más reciente no sea la que usa su juego para compilar. Proporcione al agente la carpeta de la edición que usa su juego, como `%GameDK%261000\`, en lugar de estas variables.

Para conocer las carpetas de cada edición, consulte [Estructura de directorios de encabezados y bibliotecas del GDK](https://docs.xbox.com/es/build/gdk-and-engines/guides/gdk-directory-structure.md). Indique al agente que, antes de usar una API, compruebe las declaraciones en los encabezados de la carpeta `windows\include` de la edición para PC, o de su carpeta `xbox\include` para consolas XBOX. Algunos encabezados, como los de la API de servicios de XBOX (XSAPI), libHttpClient y PlayFab, también incluyen comentarios de documentación que describen cada API.

Las herramientas de línea de comandos de `%GameDK%bin` muestran su uso cuando se ejecutan con `/?`. Un agente puede ejecutar `/?` en una herramienta antes de usarla, en lugar de adivinar sus opciones. Para traducir un `HRESULT` a una descripción, use `xberror.exe`:

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

## Proporcionar al agente código de ejemplo que coincida con su versión

Use la [lista de ejemplos del GDK de XBOX](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/gdk-samples-list.md) para encontrar ejemplos de la característica que está implementando. Consulte los archivos README del repositorio y de los ejemplos para conocer la versión del GDK, la estructura de directorios y los requisitos de plataforma. Si la rama principal no coincide con su proyecto, elija una [versión de los ejemplos](https://github.com/microsoft/Xbox-GDK-Samples/releases) compatible.

Clone o descargue la versión compatible y proporcione al agente las rutas locales al código fuente y al archivo README del ejemplo correspondiente. Pídale que siga los patrones de inicialización, control de errores, duración asincrónica y limpieza del ejemplo. Indique al agente que compruebe las API con los encabezados instalados en lugar de copiar la configuración del proyecto de una estructura de GDK diferente.

## Permitir que el agente compile desde la línea de comandos

Para compilar, un agente necesita el mismo entorno que un Gaming Command Prompt. Ejecute `GamingDesktopVars.cmd` con los argumentos que usa el acceso directo del menú Inicio y, a continuación, ejecute la compilación en el mismo proceso de `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 Visual Studio 2022. El entorno no se conserva entre comandos independientes, por lo que el agente debe ejecutar el script y la compilación juntos.

## Agregar un archivo de instrucciones del proyecto

La mayoría de los agentes de codificación leen un archivo de instrucciones del proyecto, como `AGENTS.md` o `.github/copilot-instructions.md`, en la raíz del repositorio. Úselo para proporcionar el mismo contexto del GDK en todas las sesiones del agente. Parta del siguiente ejemplo y reemplace los valores entre corchetes 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 el trabajo del agente

Antes de revisar un cambio, pida al agente que revise su propio trabajo. Por ejemplo, proporciónele esta indicación:

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

La autorrevisión no reemplaza su revisión. Revise y pruebe el código escrito por el agente como lo haría con cualquier otro código. Compruebe las afirmaciones sobre compatibilidad de plataformas, directivas y requisitos de certificación en la documentación, no en la respuesta del agente.

## Consulte también

* [Estructura de directorios de encabezados y bibliotecas del GDK](https://docs.xbox.com/es/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [Inicio del desarrollo de un nuevo título con las plantillas de proyecto del GDK](https://docs.xbox.com/es/build/gdk-and-engines/guides/gdk-project-templates.md)
* [Ejemplos del GDK de XBOX en GitHub](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [Índice de temas de NDA para el desarrollo de consolas con el GDK de XBOX](https://docs.xbox.com/es/nda/nda-overview.md)
- [Uso de contenedores de C# para las API del GDK en el proyecto de Unity](https://docs.xbox.com/es/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [Uso de herramientas sin instalar el Microsoft GDK](https://docs.xbox.com/es/build/console-features/build-without-install/tools-usage-withoutinstall.md)
- [Implementación de Game Saves con el GDK de octubre de 2025](https://docs.xbox.com/es/services/playfab/player-progression/game-saves/october-2025-gdk-changes.md)
- [Uso de Clang con Microsoft Game Development Kit (GDK)](https://docs.xbox.com/es/tools/tools-pc/visualstudio/gr-vs-clang.md)
