Générer la documentation de scène Cocos avec l'IA : faire comprendre votre jeu aux assistants de code

Vous demandez à Claude d’écrire un nouveau composant, et le code généré référence des noms de nœuds inexistants. Vous demandez à Cursor d’ajouter une fonctionnalité, et il ignore que vous avez déjà un prefab réutilisable. Chaque fois que vous expliquez la structure du projet, deux jours plus tard il faut tout recommencer.

En développement de jeux assisté par l’IA, ce genre de situation est très courant. L’IA s’en sort plutôt bien sur les projets Web classiques, mais dès qu’il s’agit de Cocos Creator, tout devient « bizarre ». Ce n’est pas qu’elle soit bête — elle ne voit tout simplement pas votre hiérarchie de scènes, la structure des nœuds ni la configuration des composants.

Le problème de fond : l’IA et le moteur de jeu sont deux outils séparés. L’IA ne peut lire que les fichiers de code, alors que l’essentiel de Cocos se trouve dans les fichiers de scène — la structure JSON des .scene et .prefab qu’elle ne peut pas interpréter directement.

Cet article partage une solution pratique : CLAUDE.md + documentation de scène, pour que l’IA comprenne vraiment votre projet de jeu. Vous y trouverez aussi des modèles de prompts reproductibles pour générer votre propre documentation de scène.

1. Pourquoi l’IA ne comprend pas votre projet de jeu

1.1 Le « mur d’isolement » entre l’IA et le moteur

Un billet de Summer Engine l’explique clairement : l’IA et le moteur sont des outils séparés. L’IA n’a aucune perception de la hiérarchie des scènes, des scripts existants ni de la structure du projet. Quand vous lui demandez d’écrire du code, elle ne peut qu’inférer à partir du contexte que vous fournissez — et ce contexte est souvent insuffisant.

Ce n’est pas comme le développement Web. La structure d’un projet Web est essentiellement dans les fichiers ; l’IA lit une fois et comprend. Pour un projet de jeu, une grande partie des informations clés est cachée dans l’éditeur — hiérarchie des scènes, position des nœuds, paramètres des composants — tout ce que les fichiers de code ne peuvent pas exprimer.

1.2 La spécificité des projets Cocos Creator

Une scène (Scene) dans Cocos Creator est une organisation logique, pas un fichier de code. Ouvrez un fichier .scene : vous verrez peut-être du JSON, mais l’IA ne va pas l’analyser. La hiérarchie (Hierarchy) est le fruit de glisser-déposer dans l’éditeur ; les prefabs (Prefab) sont encore plus particuliers — ce sont essentiellement des ressources.

Résultat embarrassant : vous demandez à l’IA « modifie ScoreLabel sous GameRoot », et elle ne sait pas ce qu’est GameRoot ni sur quel nœud se trouve ScoreLabel. Vous devez décrire toute la structure de la scène à la main — épuisant.

1.3 Les limites des solutions existantes

CLAUDE.md est une piste, mais il faut le rédiger à la main, avec un coût de maintenance élevé. Chaque modification de structure de scène exige une mise à jour, sinon l’information devient obsolète. La solution MCP Server est plus exigeante : développement d’un service WebSocket, configuration supplémentaire. Unity dispose d’outils comme Bezi qui indexent scripts, ressources et scènes en temps réel pour l’IA ; Cocos n’a pas encore d’équivalent.

La solution la plus réaliste reste donc la documentation — écrire ce que l’IA ne voit pas, pour qu’elle puisse le lire.

2. CLAUDE.md : faire mémoriser votre projet à l’IA

2.1 Qu’est-ce que CLAUDE.md

CLAUDE.md est le fichier de contexte au niveau projet de Claude Code, placé à la racine. Équivalents : .cursorrules pour Cursor, .github/copilot-instructions.md pour GitHub Copilot. Son rôle est simple : fournir à l’IA le contexte qu’elle ne peut pas déduire du code.

Par exemple, un composant ScoreManager — l’IA lit le code et sait ce qu’il fait. Mais elle ignore sur quel nœud il est monté et avec quels nœuds il interagit. C’est ce genre d’information que CLAUDE.md doit contenir.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

2.2 Que mettre dans CLAUDE.md pour un projet de jeu

Le blog de Mr. Phil Games recommande ces catégories :

Informations de base du projet : version du moteur, plateforme cible, type de jeu. L’IA saura si vous utilisez Cocos 3.8 ou 2.x, un mini-jeu WeChat ou une application mobile.

Aperçu de la structure des scènes : rôle respectif des scènes Boot, Game et page de résultats. Sans cela, l’IA ne comprend pas « charger les ressources dans la scène Boot ».

Conventions de nommage des nœuds principaux : Canvas, GameRoot, UIRoot, etc. L’IA utilisera ces noms en générant du code.

Liste des composants : composants principaux déjà implémentés et leurs responsabilités. Évite que l’IA réinvente la roue.

2.3 Exemple CLAUDE.md pour un projet Cocos Creator

Voici le CLAUDE.md d’un de mes projets de mini-jeu casual — à titre de référence :

# Contexte du projet - Démo mini-jeu

## Informations de base
- Moteur : Cocos Creator 3.8
- Type : mini-jeu casual
- Plateforme : mini-jeu WeChat

## Structure des scènes
- Boot.scene : scène de démarrage et chargement, GameManager monté
- Game.scene : scène principale, GameRoot + UIRoot
- Result.scene : page de résultats, score et boutons

## Nœuds principaux
- Canvas : racine UI
- GameRoot : contenu du jeu, composant GameLogic monté
- UIRoot : couche UI, ScoreLabel, PauseButton

## Composants implémentés
- GameManager : gestion du cycle de vie du jeu
- ScoreManager : calcul et stockage du score
- AudioManager : lecture des effets sonores

## Conventions de code
- Tous les nœuds UI sous Canvas
- Nœuds de logique de jeu sous GameRoot
- Composants de gestion nommés avec le suffixe Manager

Avec ce fichier, l’IA ne vous demandera plus « c’est quoi GameManager » ou « où est GameRoot ».

3. Documentation de scène : méthode de génération automatique

3.1 Pourquoi une documentation de scène est nécessaire

CLAUDE.md est une vue d’ensemble au niveau projet — pas assez détaillée. Chaque scène nécessite sa propre documentation : hiérarchie des nœuds, configuration des composants. L’IA doit savoir « quels nœuds dans cette scène, quels composants sur chaque nœud ».

J’ai déjà eu ce piège : demander à l’IA une fonction pause, et le code généré cherche le nœud PauseButton. Or mon nœud est dans UIRoot/PauseLayer/PauseButton — deux niveaux plus bas. L’IA ne le savait pas, j’avais oublié de le préciser, le code plantait au runtime.

La documentation de scène évite ce genre de problème : structure claire par scène, l’IA localise précisément lors de la génération de code.

3.2 Générer la documentation de scène avec un prompt

Rédiger à la main, c’est lourd — j’utilise l’IA pour générer. Voici le modèle de prompt, prêt à copier :

J'ai un projet de jeu Cocos Creator 3.8. Aide-moi à générer la documentation de scène.

Informations du projet :
- Type de jeu : mini-jeu casual
- Version du moteur : Cocos Creator 3.8

Génère la documentation à partir de :
1. Nom de la scène : {scene_name}
2. Usage de la scène : {scene_purpose}
3. Hiérarchie principale des nœuds (à décrire) :
   - {node_structure}

Format de sortie attendu :
- Aperçu de la scène (une phrase sur l'usage)
- Arborescence des nœuds (structure en arbre, composants annotés)
- Responsabilités des composants (rôle de chaque composant)
- Points d'attention pour les références de code (pièges courants)

Remplacez {scene_name}, {scene_purpose} et {node_structure} par vos valeurs réelles.

3.3 Exemple pratique : documentation Game.scene

J’ai utilisé ce prompt pour générer la documentation de Game.scene. Entrée :

1. Nom de la scène : Game.scene
2. Usage : scène principale du jeu, couche logique et couche UI
3. Hiérarchie principale :
   - Canvas (racine UI)
     - UIRoot (conteneur UI)
       - ScoreLabel (affichage du score, composant Label)
       - PauseButton (bouton pause, composant Button)
   - GameRoot (couche logique)
     - PlayerNode (joueur, composant PlayerController)
     - EnemyRoot (conteneur d'ennemis)

Documentation produite par l’IA :

# Documentation de scène Game.scene

## Aperçu de la scène
Scène principale du jeu, logique centrale et affichage UI.

## Arborescence des nœuds
Canvas (racine UI)
├── UIRoot (conteneur UI)
│   ├── ScoreLabel [Label] - affichage du score
│   └── PauseButton [Button] - bouton pause
└── GameRoot (couche logique)
    ├── PlayerNode [PlayerController] - personnage joueur
    └── EnemyRoot - conteneur d'ennemis

## Responsabilités des composants
| Composant | Nœud | Responsabilité |
|------|---------|------|
| PlayerController | PlayerNode | entrées joueur, déplacement |
| Label | ScoreLabel | affichage du texte du score |
| Button | PauseButton | interaction bouton pause |

## Points d'attention pour les références de code
1. Pour les nœuds UI, partir de Canvas : `this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel est sous UIRoot, pas directement sous Canvas
3. PlayerNode est sous GameRoot, au même niveau que Canvas

Placez ce document dans docs/ du projet et ajoutez dans CLAUDE.md : voir docs/Game.scene.md pour la structure détaillée des scènes.

3.4 Stratégie de mise à jour et de maintenance

La documentation n’est pas figée. Si la structure des scènes change, la documentation doit suivre. Ma pratique actuelle :

Après chaque modification de structure de scène, mise à jour rapide de la documentation — environ 5 minutes, bien moins pénible que tout réexpliquer à l’IA.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Certaines équipes intègrent la génération de documentation dans un pipeline CI/CD. Pour une petite équipe, la mise à jour manuelle reste plus réaliste — la structure des scènes ne change pas tous les jours.

4. Solution MCP Server : l’IA interagit directement avec le moteur

4.1 Qu’est-ce qu’un MCP Server

MCP (Model Context Protocol) est un protocole permettant à l’IA d’interagir avec des outils externes via une interface JSON-RPC. Skywork AI a développé un Cocos Creator MCP Server : l’IA communique directement avec l’éditeur.

En bref : l’IA n’a pas besoin que vous décriviez la structure des scènes — elle peut interroger l’éditeur elle-même.

4.2 Ce que le MCP Server peut faire

Selon le blog de Skywork AI, le Cocos MCP Server prend en charge :

• L’IA obtient les informations de scène via des appels d’outils
• L’IA crée des nœuds directement dans l’éditeur
• L’IA lit le contenu des prefabs
• L’IA interroge la configuration des composants

C’est bien plus puissant que CLAUDE.md, car l’information est en temps réel. Vous modifiez une scène, l’IA le sait immédiatement — sans synchroniser la documentation.

4.3 Seuil d’entrée et limites du MCP Server

Le MCP Server n’est pas sans contraintes :

Configuration complexe : démarrer un service WebSocket, configurer ports et permissions — parfois une demi-journée de galère.

Support IA limité : seul Claude Code supporte aujourd’hui le protocole MCP ; Cursor et Copilot pas encore.

Documentation rare : peu de ressources communautaires pour le Cocos MCP Server — dépannage difficile.

Pour un développeur solo qui veut une solution rapide, CLAUDE.md + documentation de scène convient mieux. MCP vise plutôt une équipe avec des compétences techniques sur le long terme.

4.4 MCP et CLAUDE.md : usage combiné

Ces deux approches ne se remplacent pas — elles se complètent :

• CLAUDE.md : contexte statique — vue d’ensemble, conventions de nommage, principes de conception
• MCP : interaction dynamique — informations de scène en temps réel, création de nœuds

Même avec MCP, CLAUDE.md reste utile. MCP répond à « qu’y a-t-il maintenant », pas à « pourquoi cette conception » ou « quelles sont les conventions de nommage ». Cela reste à écrire dans CLAUDE.md.

5. Synthèse pratique et recommandations

5.1 Solution minimale viable (commencer aujourd’hui)

Pour que l’IA comprenne votre projet sans configuration avancée, trois étapes :

Étape 1 : créer CLAUDE.md avec les informations de base — version du moteur, type de jeu, aperçu des scènes.

Étape 2 : utiliser les modèles de prompts du chapitre 3 pour documenter 3 scènes principales — Boot, Game, Result — suffisant pour démarrer.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

Étape 3 : placer la documentation dans docs/ et ajouter les références dans CLAUDE.md.

En une demi-heure, c’est fait. Ensuite, quand l’IA pose des questions sur la structure du projet, envoyez-lui directement la documentation.

5.2 Solution avancée (équipes avec compétences de développement)

Si vous pouvez investir davantage :

Configurer Cocos MCP Server : implémentation open source de Skywork AI, documentation relativement claire. Une fois configuré, l’IA obtient les informations de scène en temps réel.

Développer un script d’export de scènes : extension Cocos qui exporte automatiquement la structure vers JSON ou Markdown — plus précis qu’une description manuelle.

Mise à jour automatisée : intégrer le script d’export au pipeline de build pour mettre à jour CLAUDE.md à chaque build.

Cette approche demande un effort de développement — adaptée aux équipes de taille moyenne ou grande.

5.3 Objectif à long terme

L’idéal : l’IA comprend vraiment un projet de jeu comme un projet Web. Fusion profonde éditeur + IA, documentation de développement de jeux comme standard du secteur.

Unity a déjà des outils comme Bezi ; Cocos devrait suivre. En attendant, la documentation reste l’approche la plus fiable.

Conclusion

L’obstacle fondamental du développement de jeux assisté par l’IA : l’IA ne voit pas le contenu de l’éditeur. Hiérarchie des scènes, structure des nœuds, configuration des composants — tout cela lui est invisible. La solution : documenter ce que l’IA ne voit pas.

CLAUDE.md est le contexte au niveau projet ; la documentation de scène est le complément granulaire. Ensemble, l’IA localise précisément les nœuds et comprend les responsabilités des composants. Si vous avez des compétences de développement, configurez aussi un MCP Server pour des informations de scène en temps réel.

Essayez dès aujourd’hui : créez un CLAUDE.md et générez votre première documentation de scène avec les prompts de cet article. Si vous avez d’autres retours d’expérience, partagez-les en commentaire.