Como usar IA para gerar documentação de cenas Cocos e fazer o assistente entender seu jogo

Você pede ao Claude para escrever um novo componente, e o código gerado referencia um nome de nó que não existe. Você pede ao Cursor para adicionar uma funcionalidade, mas ele não sabe que já existe um prefab pronto para reutilizar. Depois de explicar toda a estrutura do projeto, dois dias depois precisa explicar tudo de novo.

Esse tipo de situação é muito comum quando usamos IA para auxiliar no desenvolvimento de jogos. Para projetos Web comuns, a IA costuma se sair bem. Mas, ao chegar no Cocos Creator, tudo começa a ficar “meio errado”. Não é porque ela seja burra; é porque ela simplesmente não consegue ver a hierarquia de cenas, a estrutura dos nós e a configuração dos componentes.

Por trás disso existe um problema fundamental: IA e engine de jogos são duas ferramentas independentes. A IA só consegue ler arquivos de código, enquanto o conteúdo central do Cocos fica em arquivos de cena. Aquelas estruturas JSON em .scene e .prefab não são algo que a IA consiga entender diretamente.

Neste artigo, vou compartilhar uma solução prática: usar um arquivo CLAUDE.md junto com documentação de cenas para fazer a IA realmente entender seu projeto de jogo. Também deixo um modelo de prompt reutilizável; basta adaptar para gerar sua própria documentação de cena.

1. Por que a IA não entende seu projeto de jogo

1.1 O problema da “parede de isolamento” entre IA e engine

O blog da Summer Engine explica isso muito bem: IA e engine são ferramentas separadas. A IA não tem percepção da hierarquia de cenas, dos scripts existentes nem da estrutura real do projeto. Quando você pede que ela escreva código, ela só consegue inferir com base no contexto que você fornece. O problema é que esse contexto quase sempre é insuficiente.

Isso é diferente do desenvolvimento Web. Em um projeto Web, a estrutura de código geralmente está nos arquivos, então a IA consegue ler e entender com relativa facilidade. Em um projeto de jogo, muitas informações importantes ficam escondidas dentro do editor: hierarquia de cenas, posição de nós, parâmetros de componentes. Esses dados não são expressos de forma clara apenas pelos arquivos de código.

1.2 A especificidade de projetos Cocos Creator

A cena (Scene) do Cocos Creator é uma estrutura de organização lógica, não um arquivo de código. Quando você abre um arquivo .scene, talvez veja um monte de JSON, mas a IA não interpreta automaticamente o significado dessa estrutura. A hierarquia de nós (Hierarchy) é resultado do que você montou arrastando e organizando elementos no editor. O prefab (Prefab) é ainda mais específico: na prática, é um arquivo de recurso.

Isso cria uma situação bem incômoda. Você pergunta à IA: “me ajude a modificar o ScoreLabel dentro de GameRoot”. A IA não sabe o que é GameRoot nem em qual nó ScoreLabel está. Você precisa descrever manualmente toda a estrutura da cena. É cansativo.

1.3 As limitações das soluções atuais

O arquivo CLAUDE.md é um caminho, mas precisa ser escrito manualmente, e o custo de manutenção é alto. Cada mudança na estrutura da cena exige atualização sincronizada; caso contrário, a informação fica desatualizada. A solução com MCP Server tem uma barreira ainda maior: exige desenvolver um serviço WebSocket extra e configurar várias peças. No Unity, já existem ferramentas de indexação em tempo real como Bezi, que conseguem alimentar a IA automaticamente com scripts, recursos e cenas. No Cocos, por enquanto, ainda não há algo equivalente.

Por isso, a solução mais realista continua sendo documentar: escrever aquilo que a IA não consegue enxergar, para que ela consiga ler.

2. Arquivo CLAUDE.md: faça a IA lembrar do seu projeto

2.1 O que é CLAUDE.md

CLAUDE.md é um arquivo de contexto em nível de projeto para o Claude Code, colocado na raiz do projeto. Há equivalentes semelhantes, como .cursorrules no Cursor e .github/copilot-instructions.md no GitHub Copilot. Sua função é simples: fornecer à IA o contexto que ela não consegue inferir apenas pelo código.

Por exemplo, se você tem um componente chamado ScoreManager, a IA consegue ler o código e entender o que ele faz. Mas ela não sabe em qual nó esse componente está montado nem com quais nós interage. Essas são as informações que devem entrar no CLAUDE.md.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

2.2 O que escrever no CLAUDE.md de um projeto de jogo

O blog do Mr. Phil Games recomenda incluir estes tipos de informação:

Informações básicas do projeto: versão da engine, plataforma-alvo e tipo de jogo. Isso permite que a IA saiba se você está usando Cocos 3.8 ou 2.x, se é um minigame do WeChat ou um app.

Visão geral da estrutura de cenas: o que fazem a cena Boot, a cena Game e a página de resultado. Só assim a IA consegue entender o que você quer dizer com “carregar recursos na cena Boot”.

Regras de nomenclatura dos nós principais: nós de topo como Canvas, GameRoot e UIRoot. Ao gerar código, a IA passa a usar esses nomes automaticamente.

Lista de componentes: componentes principais já implementados e suas responsabilidades. Isso evita que a IA reinvente algo que o projeto já possui.

2.3 Exemplo de CLAUDE.md para um projeto Cocos Creator

Este é o CLAUDE.md de um pequeno jogo casual meu, que você pode usar como referência:

# Contexto do projeto - Demo de minigame

## Informações básicas
- Engine: Cocos Creator 3.8
- Tipo: jogo casual
- Plataforma: minigame do WeChat

## Estrutura de cenas
- Boot.scene: cena de carregamento inicial, com GameManager montado
- Game.scene: cena principal do jogo, contendo GameRoot + UIRoot
- Result.scene: página de resultado, exibindo pontuação e botões

## Nós principais
- Canvas: nó raiz da UI
- GameRoot: nó de conteúdo do jogo, com o componente GameLogic
- UIRoot: nó da camada de UI, contendo ScoreLabel e PauseButton

## Componentes já implementados
- GameManager: gerenciamento do ciclo de vida do jogo
- ScoreManager: cálculo e armazenamento de pontuação
- AudioManager: reprodução de efeitos sonoros

## Convenções de código
- Todos os nós de UI ficam dentro de Canvas
- Nós de lógica de jogo ficam dentro de GameRoot
- Componentes de gerenciamento terminam com Manager

Com esse arquivo, a IA deixa de perguntar “o que é GameManager?” ou “onde fica GameRoot?“.

3. Documentação de cenas: um método prático de geração automática

3.1 Por que precisamos de documentação de cenas

CLAUDE.md é uma visão geral do projeto, mas não tem granularidade suficiente. A hierarquia de nós e a configuração de componentes de cada cena precisam ser documentadas separadamente. A ideia é fazer a IA saber: “quais nós existem nesta cena e quais componentes estão montados em cada nó”.

Eu já caí nessa armadilha: pedi para a IA escrever uma função de pausa, e ela gerou código procurando o nó PauseButton. Só que, no meu projeto, esse nó estava em UIRoot/PauseLayer/PauseButton, duas camadas abaixo. A IA não sabia disso, e eu esqueci de avisar. Resultado: o código quebrava ao rodar.

A documentação de cenas existe para evitar esse tipo de problema. Quando a estrutura de cada cena está clara, a IA consegue localizar os nós corretamente ao analisar ou escrever código.

3.2 Usar um prompt para gerar documentação de cena automaticamente

Escrever toda essa documentação à mão é trabalhoso, então eu uso IA para gerar. Abaixo está um modelo de prompt que você pode copiar diretamente:

Tenho um projeto de jogo em Cocos Creator 3.8. Por favor, gere uma documentação de cena.

Informações do projeto:
- Tipo de jogo: jogo casual
- Versão da engine: Cocos Creator 3.8

Gere a documentação com base nas seguintes informações:
1. Nome da cena: {scene_name}
2. Finalidade da cena: {scene_purpose}
3. Hierarquia principal de nós (descreva):
   - {node_structure}

Requisitos de formato:
- Visão geral da cena (uma frase explicando sua finalidade)
- Árvore de hierarquia de nós (exibida em formato de árvore, com componentes marcados)
- Descrição das responsabilidades dos componentes (o que cada componente faz)
- Cuidados ao referenciar no código (pontos propensos a erro)

Ao usar, substitua {scene_name}, {scene_purpose} e {node_structure} pelo conteúdo real do seu projeto.

3.3 Exemplo prático: gerar documentação de Game.scene

Usei esse prompt para gerar a documentação de uma Game.scene. A entrada foi:

1. Nome da cena: Game.scene
2. Finalidade da cena: cena principal do jogo, contendo a camada de lógica do jogo e a camada de UI
3. Hierarquia principal de nós:
   - Canvas (nó raiz da UI)
     - UIRoot (contêiner da camada de UI)
       - ScoreLabel (exibição de pontuação, com componente Label)
       - PauseButton (botão de pausa, com componente Button)
   - GameRoot (camada de lógica do jogo)
     - PlayerNode (personagem do jogador, com PlayerController)
     - EnemyRoot (contêiner de inimigos)

A documentação gerada pela IA foi:

# Documentação da cena Game.scene

## Visão geral da cena
Cena principal do jogo, responsável pela lógica central do jogo e pela exibição da UI.

## Árvore de hierarquia de nós
Canvas (nó raiz da UI)
├── UIRoot (contêiner da camada de UI)
│   ├── ScoreLabel [Label] - exibição da pontuação
│   └── PauseButton [Button] - botão de pausa
└── GameRoot (camada de lógica do jogo)
    ├── PlayerNode [PlayerController] - personagem do jogador
    └── EnemyRoot - contêiner de inimigos

## Responsabilidades dos componentes
| Componente | Nó montado | Responsabilidade |
|------|---------|------|
| PlayerController | PlayerNode | Processa entrada do jogador e lógica de movimento |
| Label | ScoreLabel | Exibe o texto da pontuação |
| Button | PauseButton | Interação do botão de pausa |

## Cuidados ao referenciar no código
1. Ao procurar nós de UI, comece por Canvas: `this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel fica dentro de UIRoot, não diretamente em Canvas
3. PlayerNode fica dentro de GameRoot, no mesmo nível de Canvas

Coloque essa documentação no diretório docs/ do projeto e adicione uma linha de referência no CLAUDE.md: veja a estrutura detalhada da cena em docs/Game.scene.md.

3.4 Estratégia de atualização e manutenção da documentação

Depois de escrita, a documentação não fica pronta para sempre. Quando a estrutura da cena muda, a documentação também precisa mudar. Hoje, meu fluxo é simples:

Sempre que termino de alterar a estrutura de uma cena, atualizo a documentação junto. Leva algo em torno de 5 minutos e poupa muito mais tempo do que explicar tudo de novo para a IA.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Algumas equipes colocam a geração de documentação dentro do fluxo de CI/CD, com acionamento automático. Mas, para equipes pequenas, acho a atualização manual mais prática. Afinal, a estrutura de cenas não muda radicalmente todos os dias.

4. Solução com MCP Server: fazer a IA interagir diretamente com a engine

4.1 O que é MCP Server

MCP (Model Context Protocol) é um protocolo que permite à IA interagir com ferramentas externas por meio de uma interface JSON-RPC. A Skywork AI criou um Cocos Creator MCP Server, permitindo que a IA se comunique diretamente com o editor.

Em termos simples: a IA não precisa que você conte manualmente a estrutura da cena; ela pode perguntar ao editor por conta própria.

4.2 O que um MCP Server consegue fazer

Segundo o blog da Skywork AI, o Cocos MCP Server oferece suporte a funções como:

• Obter informações da cena por chamadas de ferramentas da IA
• Criar nós diretamente no editor
• Ler conteúdo de prefabs
• Consultar configurações de componentes

Isso é muito mais forte do que CLAUDE.md, porque a informação é em tempo real. Se você altera a cena, a IA consegue saber imediatamente, sem precisar sincronizar documentação.

4.3 Barreiras e limitações do MCP Server

Mesmo assim, o MCP Server também tem barreiras:

Configuração complexa: é preciso iniciar um serviço WebSocket, configurar porta e permissões. Se algo não encaixar, você pode perder bastante tempo ajustando.

Suporte limitado por parte das IAs: no momento, apenas o Claude Code oferece suporte ao protocolo MCP; Cursor e Copilot ainda não suportam.

Pouca documentação: a documentação e os recursos de comunidade do Cocos MCP Server ainda são poucos, então problemas podem ser difíceis de pesquisar.

Por isso, se você é um desenvolvedor individual e quer resolver o problema rapidamente, a combinação CLAUDE.md + documentação de cenas tende a ser mais adequada. MCP combina melhor com equipes tecnicamente preparadas para investir no longo prazo.

4.4 Usar MCP e CLAUDE.md em conjunto

Na prática, as duas abordagens não se substituem; elas se complementam:

• CLAUDE.md fornece contexto estático: visão geral do projeto, regras de nomenclatura e decisões de design
• MCP fornece interação dinâmica: obtenção de informações da cena em tempo real e criação de nós

Mesmo que você configure MCP, CLAUDE.md continua útil. MCP só consegue responder “o que existe agora”; ele não explica para a IA “por que foi projetado assim” ou “qual é a convenção de nomenclatura”. Essas informações ainda precisam estar no CLAUDE.md.

5. Resumo prático e recomendações de ação

5.1 Solução mínima viável, que você pode começar hoje

Se seu objetivo é apenas fazer a IA entender o projeto, sem configuração avançada, três passos resolvem:

Primeiro passo: crie o arquivo CLAUDE.md e registre as informações básicas do projeto: versão da engine, tipo de jogo e visão geral da estrutura de cenas.

Segundo passo: use o modelo de prompt do capítulo 3 deste artigo para gerar documentação das 3 cenas principais. Boot, Game e Result já são suficientes.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Terceiro passo: coloque a documentação das cenas no diretório docs/ e adicione referências no CLAUDE.md.

Em meia hora, você consegue concluir isso. Depois, quando a IA perguntar sobre a estrutura do projeto, basta entregar a documentação.

5.2 Solução avançada para equipes com capacidade de desenvolvimento

Se você estiver disposto a investir mais, pode seguir este caminho:

Configurar o Cocos MCP Server: a implementação open source da Skywork AI tem uma documentação razoavelmente clara. Depois de configurada, a IA consegue obter informações da cena em tempo real.

Desenvolver um script de exportação de cenas: escreva uma extensão do Cocos para exportar automaticamente a estrutura da cena para JSON ou Markdown. Isso é mais preciso do que descrever manualmente.

Automatizar atualizações: adicione o script de exportação ao fluxo de build, atualizando o CLAUDE.md automaticamente a cada construção.

Essa abordagem exige algum trabalho de desenvolvimento e combina melhor com equipes médias ou grandes.

5.3 Objetivo de longo prazo

O estado ideal é a IA realmente entender projetos de jogos, da mesma forma que entende projetos Web. O editor se integraria profundamente à IA, e a documentação do desenvolvimento de jogos se tornaria um padrão do setor.

O Unity já conta com ferramentas de indexação em tempo real como Bezi. É provável que o Cocos também avance nessa direção. Até lá, documentar continua sendo a solução mais confiável.

Conclusão

O desenvolvimento de jogos assistido por IA tem uma barreira fundamental: a IA não enxerga o conteúdo dentro do editor. Hierarquia de cenas, estrutura de nós e configuração de componentes são informações que ela não conhece. A solução é documentar: escrever aquilo que a IA não consegue ver.

CLAUDE.md funciona como contexto de projeto, enquanto a documentação de cenas complementa em nível granular. Juntos, eles permitem que a IA localize nós com precisão e entenda as responsabilidades dos componentes. Se você tiver capacidade de desenvolvimento, também pode configurar um MCP Server para permitir que a IA obtenha informações da cena em tempo real.

Experimente hoje: crie um arquivo CLAUDE.md e use o prompt deste artigo para gerar a primeira documentação de cena. Se você tiver outras práticas úteis, fique à vontade para compartilhar nos comentários.