Generar documentación de escenas Cocos con IA: que el asistente de código entienda tu juego

Pides a Claude un componente nuevo y el código referencia nombres de nodos que no existen. Pides a Cursor una función y no sabe que ya tienes un prefab reutilizable. Explicas la estructura del proyecto y, dos días después, toca repetirlo.

En desarrollo de juegos con IA esto es habitual. Con proyectos web la IA va fluida; en Cocos Creator todo suena “raro”. No es que sea torpe: simplemente no ve la jerarquía de escenas, la estructura de nodos ni la configuración de componentes.

El problema de fondo: la IA y el motor de juego son herramientas separadas. La IA solo lee archivos de código, pero lo central en Cocos está en las escenas: esos JSON de .scene y .prefab que no puede interpretar directamente.

En este artículo comparto una solución práctica: CLAUDE.md + documentación de escenas para que la IA entienda de verdad tu proyecto. También incluyo plantillas de prompt que puedes copiar y usar para generar tu propia documentación.

1. Por qué la IA no entiende tu proyecto de juego

1.1 El “muro” entre la IA y el motor

Un artículo de Summer Engine lo resume bien: la IA y el motor son herramientas separadas. La IA no percibe jerarquía de escenas, scripts existentes ni estructura del proyecto. Cuando pides código, solo infiere a partir del contexto que le das — y suele ser insuficiente.

No es lo mismo que en desarrollo web. En web, la estructura vive en los archivos y la IA puede leerla. En juegos, mucha información clave está en el editor: jerarquía, posiciones, parámetros de componentes… cosas que el código no expresa.

1.2 La particularidad de Cocos Creator

En Cocos Creator, una escena (Scene) es organización lógica, no un archivo de código. Abres un .scene y ves JSON; la IA no lo parsea por iniciativa propia. La jerarquía (Hierarchy) es fruto del editor; los prefabs (Prefab) son recursos especiales.

Resultado incómodo: pides “modifica ScoreLabel bajo GameRoot” y la IA no sabe qué es GameRoot ni dónde está ScoreLabel. Tienes que describir toda la escena a mano. Agotador.

1.3 Límites de las soluciones actuales

CLAUDE.md ayuda, pero hay que escribirlo y mantenerlo. Cada cambio de escena exige actualización o la información caduca. MCP Server sube la exigencia: servicio WebSocket, puertos, permisos. Unity tiene Bezi, que indexa scripts, recursos y escenas para la IA en tiempo real; en Cocos aún no hay un equivalente claro.

La opción más realista sigue siendo documentar lo que la IA no ve para que pueda leerlo.

2. CLAUDE.md: que la IA recuerde tu proyecto

2.1 Qué es CLAUDE.md

CLAUDE.md es el archivo de contexto a nivel de proyecto de Claude Code, en la raíz. Cursor usa .cursorrules; GitHub Copilot, .github/copilot-instructions.md. La idea: dar a la IA contexto que no puede inferir del código.

Si tienes un componente ScoreManager, la IA entiende su lógica leyendo código. No sabe en qué nodo está montado ni con qué nodos interactúa. Eso va en CLAUDE.md.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

2.2 Qué incluir en CLAUDE.md para un juego

El blog de Mr. Phil Games sugiere estas categorías:

Información básica del proyecto: versión del motor, plataforma objetivo, tipo de juego. Así la IA sabe si usas Cocos 3.8 o 2.x, minijuego de WeChat o app nativa.

Resumen de escenas: qué hacen Boot, Game y la pantalla de resultados. Sin eso, “cargar recursos en Boot” no tiene sentido.

Convenciones de nodos clave: Canvas, GameRoot, UIRoot y otros nodos de nivel superior. La IA los usará al generar código.

Lista de componentes: componentes core ya implementados y su responsabilidad. Evita que reinvente la rueda.

2.3 Ejemplo de CLAUDE.md para Cocos Creator

Este es el CLAUDE.md de un demo de minijuego casual; puedes adaptarlo:

# Contexto del proyecto - Demo de minijuego

## Información básica
- Motor: Cocos Creator 3.8
- Tipo: minijuego casual
- Plataforma: minijuego de WeChat

## Estructura de escenas
- Boot.scene: escena de arranque y carga, monta GameManager
- Game.scene: escena principal, GameRoot + UIRoot
- Result.scene: pantalla de resultados, puntuación y botones

## Nodos clave
- Canvas: raíz de UI
- GameRoot: contenido del juego, monta GameLogic
- UIRoot: capa UI, ScoreLabel, PauseButton

## Componentes implementados
- GameManager: ciclo de vida del juego
- ScoreManager: cálculo y almacenamiento de puntuación
- AudioManager: reproducción de efectos

## Convenciones de código
- Toda la UI bajo Canvas
- Lógica de juego bajo GameRoot
- Componentes de gestión terminan en Manager

Con este archivo, la IA deja de preguntar “¿qué es GameManager?” o “¿dónde está GameRoot?”.

3. Documentación de escenas: generación automática en la práctica

3.1 Por qué hace falta documentación por escena

CLAUDE.md es visión general; no basta el detalle. Cada escena necesita su jerarquía y configuración de componentes documentadas: qué nodos hay y qué componente lleva cada uno.

Cometí un error clásico: pedí pausa y el código buscaba el nodo PauseButton. En mi proyecto está en UIRoot/PauseLayer/PauseButton, dos niveles más abajo. La IA no lo sabía; yo lo olvidé. Error en runtime.

La documentación de escenas evita eso: estructura clara para que la IA ubique nodos al revisar código.

3.2 Generar documentación con un prompt

Escribir todo a mano cansa; yo uso la IA. Plantilla lista para copiar:

Tengo un proyecto Cocos Creator 3.8. Ayúdame a generar documentación de escena.

Información del proyecto:
- Tipo de juego: minijuego casual
- Versión del motor: Cocos Creator 3.8

Genera la documentación según:
1. Nombre de escena: {scene_name}
2. Propósito: {scene_purpose}
3. Jerarquía principal (descríbela):
   - {node_structure}

Formato de salida:
- Resumen de la escena (una frase)
- Árbol de nodos (estructura de árbol, componentes anotados)
- Responsabilidades de componentes
- Notas al referenciar en código (trampas habituales)

Sustituye {scene_name}, {scene_purpose} y {node_structure} por tus datos reales.

3.3 Ejemplo práctico: documentación de Game.scene

Con ese prompt generé la documentación de Game.scene. Entrada:

1. Nombre de escena: Game.scene
2. Propósito: escena principal, capa de lógica y capa UI
3. Jerarquía principal:
   - Canvas (raíz UI)
     - UIRoot (contenedor UI)
       - ScoreLabel (puntuación, componente Label)
       - PauseButton (pausa, componente Button)
   - GameRoot (lógica del juego)
     - PlayerNode (jugador, PlayerController)
     - EnemyRoot (contenedor de enemigos)

Salida de la IA:

# Documentación de Game.scene

## Resumen
Escena principal: lógica del juego y presentación UI.

## Árbol de nodos
Canvas (raíz UI)
├── UIRoot (contenedor UI)
│   ├── ScoreLabel [Label] - puntuación
│   └── PauseButton [Button] - botón de pausa
└── GameRoot (lógica)
    ├── PlayerNode [PlayerController] - jugador
    └── EnemyRoot - enemigos

## Responsabilidades
| Componente | Nodo | Función |
|------|---------|------|
| PlayerController | PlayerNode | Entrada y movimiento del jugador |
| Label | ScoreLabel | Texto de puntuación |
| Button | PauseButton | Interacción de pausa |

## Notas al referenciar en código
1. Buscar UI desde Canvas: `this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel está bajo UIRoot, no directamente bajo Canvas
3. PlayerNode está bajo GameRoot, al mismo nivel que Canvas

Guarda el archivo en docs/ y en CLAUDE.md añade: Estructura detallada: docs/Game.scene.md.

3.4 Actualización y mantenimiento

Documentar una vez no basta. Si cambia la escena, cambia el doc. Mi flujo:

Tras modificar la escena, actualizo el doc en unos 5 minutos — menos trabajo que volver a explicárselo todo a la IA.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Algunos equipos automatizan en CI/CD. Para equipos pequeños, manual suele ser más práctico: la estructura no cambia a diario.

4. MCP Server: que la IA hable con el motor

4.1 Qué es MCP Server

MCP (Model Context Protocol) permite a la IA interactuar con herramientas externas vía JSON-RPC. Skywork AI tiene un MCP Server para Cocos Creator: la IA se comunica con el editor.

En pocas palabras: la IA no depende de que le describas la escena; puede consultar al editor.

4.2 Qué puede hacer MCP Server

Según el blog de Skywork AI, el MCP de Cocos permite:

• Obtener información de escenas mediante tool calls
• Crear nodos en el editor
• Leer contenido de prefabs
• Consultar configuración de componentes

Supera a CLAUDE.md en frescura: cambias la escena y la IA lo sabe al instante, sin sincronizar docs.

4.3 Barrera de entrada y límites

MCP Server no es gratis en esfuerzo:

Configuración compleja: WebSocket, puertos, permisos. Puede llevar horas.

Soporte de IA limitado: hoy MCP está bien integrado en Claude Code; Cursor y Copilot aún no.

Documentación escasa: pocos recursos de comunidad para el MCP de Cocos.

Si eres desarrollador individual y quieres resultados rápidos, CLAUDE.md + documentación de escenas encaja mejor. MCP tiene más sentido en equipos con capacidad técnica a largo plazo.

4.4 MCP y CLAUDE.md juntos

No compiten; se complementan:

• CLAUDE.md: contexto estático — visión del proyecto, convenciones, criterios de diseño
• MCP: interacción dinámica — escenas en tiempo real, creación de nodos

Con MCP configurado, CLAUDE.md sigue siendo útil. MCP responde “qué hay ahora”, no “por qué se diseñó así” ni “cómo se nombran las cosas”. Eso sigue en CLAUDE.md.

5. Resumen práctico y próximos pasos

5.1 Solución mínima (puedes empezar hoy)

Si solo quieres que la IA entienda el proyecto, tres pasos:

Paso 1: crea CLAUDE.md con información básica — motor, tipo de juego, resumen de escenas.

Paso 2: usa la plantilla del capítulo 3 para documentar Boot, Game y Result.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Paso 3: guarda los docs en docs/ y referencia en CLAUDE.md.

Media hora y listo. Cuando la IA pregunte por la estructura, comparte los documentos.

5.2 Opción avanzada (equipos con desarrollo)

Si puedes invertir más:

Configura Cocos MCP Server: implementación open source de Skywork AI; la documentación es razonable.

Script de exportación de escenas: extensión de Cocos que exporte estructura a JSON o Markdown, más preciso que describir a mano.

Actualización automática: integra el export en el build para refrescar CLAUDE.md.

Requiere trabajo de desarrollo; encaja en equipos medianos o grandes.

5.3 Objetivo a largo plazo

Lo ideal: que la IA entienda un juego como entiende un repo web. Editor e IA integrados; documentación como estándar del sector.

Unity ya tiene herramientas como Bezi; Cocos probablemente seguirá. Mientras tanto, documentar sigue siendo lo más fiable.

Conclusión

El obstáculo central de la IA en juegos: no ve lo del editor. Jerarquía, nodos, componentes — invisible para el modelo. La salida es documentar lo invisible.

CLAUDE.md es contexto de proyecto; la documentación de escenas es el detalle. Juntos, la IA ubica nodos y entiende responsabilidades. Con capacidad de desarrollo, MCP Server añade información en tiempo real.

Prueba hoy: crea CLAUDE.md y genera tu primera documentación de escena con el prompt de este artículo. Si tienes otras experiencias, compártelas en los comentarios.