AI로 Cocos 씬 문서 생성하기: 코드 어시스턴트가 게임을 제대로 이해하게 만드는 법

Claude에게 새 컴포넌트를 작성하라고 했더니 존재하지 않는 노드 이름을 참조하는 코드를 생성합니다. Cursor에게 기능을 추가하라고 했더니 이미 재사용할 수 있는 프리팹이 있다는 사실을 모릅니다. 프로젝트 구조를 한 번 설명해도 며칠 지나면 다시 처음부터 말해야 합니다.

AI로 게임 개발을 보조할 때 이런 일은 너무 흔합니다. AI는 일반 Web 프로젝트 코드는 꽤 능숙하게 다루지만 Cocos Creator로 넘어오면 여러모로 어긋납니다. AI가 멍청해서가 아니라, 씬 계층과 노드 구조, 컴포넌트 설정을 애초에 볼 수 없기 때문입니다.

그 뒤에는 근본적인 문제가 있습니다. AI와 게임 엔진은 서로 독립된 도구입니다. AI는 코드 파일만 읽을 수 있지만 Cocos의 핵심 내용은 대부분 씬 파일 안에 있습니다. .scene과 .prefab의 JSON 구조를 AI가 직접 이해하기는 어렵습니다.

이 글에서는 실용적인 해결책을 공유합니다. CLAUDE.md 파일과 씬 설명 문서를 함께 사용해 AI가 게임 프로젝트를 제대로 이해하게 만드는 방법입니다. 그대로 복사해 사용할 수 있는 Prompt 템플릿도 함께 제공하니, 자신의 프로젝트에 맞는 씬 문서를 바로 만들 수 있습니다.

1. 왜 AI는 게임 프로젝트를 이해하지 못할까

1.1 AI와 엔진 사이의 “격리벽” 문제

Summer Engine의 한 블로그는 이 문제를 꽤 정확하게 짚었습니다. AI와 엔진은 분리된 도구입니다. AI는 씬 계층, 기존 스크립트, 프로젝트 구조를 전혀 감지하지 못합니다. 코드를 작성하게 하면 AI는 사용자가 제공한 컨텍스트를 바탕으로 추론할 뿐입니다. 문제는 우리가 제공하는 컨텍스트가 대개 충분하지 않다는 점입니다.

이는 Web 개발과 다릅니다. Web 프로젝트의 코드 구조는 대부분 파일 안에 있고, AI가 한 번 읽으면 어느 정도 이해할 수 있습니다. 하지만 게임 프로젝트는 어떨까요? 중요한 정보가 에디터 안에 많이 숨어 있습니다. 씬 계층, 노드 위치, 컴포넌트 매개변수는 코드 파일만으로 표현하기 어려운 내용입니다.

1.2 Cocos Creator 프로젝트의 특수성

Cocos Creator의 씬(Scene)은 논리적 조직 구조이지 코드 파일이 아닙니다. .scene 파일을 열면 JSON 덩어리가 보일 수 있지만, AI가 그 내용을 알아서 해석해 주지는 않습니다. 노드 계층(Hierarchy)은 에디터에서 드래그해 만든 결과물이고, 프리팹(Prefab)은 더 특수합니다. 본질적으로는 리소스 파일입니다.

그래서 난감한 상황이 생깁니다. AI에게 “GameRoot 아래의 ScoreLabel을 수정해 줘”라고 말해도 AI는 GameRoot가 무엇인지, ScoreLabel이 어느 노드에 붙어 있는지 모릅니다. 결국 사용자가 씬 구조 전체를 수동으로 설명해야 하고, 이는 꽤 피곤한 일입니다.

1.3 기존 방식의 한계

CLAUDE.md 파일은 좋은 방향이지만 수동으로 작성해야 하므로 유지보수 비용이 있습니다. 씬 구조가 바뀔 때마다 함께 업데이트하지 않으면 정보가 금세 낡습니다. MCP Server 방식은 진입 장벽이 더 높습니다. 별도의 WebSocket 서비스를 개발하고 여러 설정을 맞춰야 합니다. Unity에는 Bezi처럼 스크립트, 리소스, 씬을 실시간으로 인덱싱해 AI에 제공하는 도구가 있지만, Cocos에는 아직 비슷한 도구가 많지 않습니다.

그래서 가장 현실적인 방법은 여전히 문서화입니다. AI가 보지 못하는 것을 글로 적어 AI가 읽을 수 있게 만드는 것입니다.

2. CLAUDE.md 파일: AI가 프로젝트를 기억하게 만들기

2.1 CLAUDE.md란 무엇인가

CLAUDE.md는 Claude Code의 프로젝트 단위 컨텍스트 파일이며 프로젝트 루트 디렉터리에 둡니다. Cursor의 .cursorrules, GitHub Copilot의 .github/copilot-instructions.md도 비슷한 역할을 합니다. 목적은 단순합니다. AI가 코드만으로 추론할 수 없는 컨텍스트를 제공하는 것입니다.

예를 들어 ScoreManager라는 컴포넌트가 있다면 AI는 코드를 읽고 그 역할을 알 수 있습니다. 하지만 이 컴포넌트가 어느 노드에 마운트되어 있는지, 어떤 노드와 상호작용하는지는 모릅니다. 이런 정보가 CLAUDE.md에 들어가야 합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

2.2 게임 프로젝트의 CLAUDE.md에는 무엇을 써야 할까

Mr. Phil Games의 블로그는 다음과 같은 정보를 작성하라고 제안합니다.

프로젝트 기본 정보: 엔진 버전, 대상 플랫폼, 게임 유형입니다. AI가 Cocos 3.8을 쓰는지 2.x를 쓰는지, WeChat 미니게임인지 App인지 파악할 수 있습니다.

씬 구조 개요: Boot 씬, Game 씬, 결과 페이지가 각각 무엇을 하는지입니다. AI가 이를 알아야 “Boot 씬에서 리소스를 로드한다”는 말의 의미를 이해할 수 있습니다.

핵심 노드 명명 규칙: Canvas, GameRoot, UIRoot 같은 최상위 노드입니다. AI가 코드를 생성할 때 이런 이름을 자연스럽게 사용하게 됩니다.

컴포넌트 목록: 이미 구현된 핵심 컴포넌트와 그 책임입니다. AI가 같은 기능을 다시 만들지 않도록 막을 수 있습니다.

2.3 Cocos Creator 프로젝트용 CLAUDE.md 예시

아래는 제가 만든 캐주얼 미니게임 프로젝트의 CLAUDE.md입니다. 참고용으로 사용할 수 있습니다.

# 프로젝트 컨텍스트 - 미니게임 Demo

## 기본 정보
- 엔진: Cocos Creator 3.8
- 유형: 캐주얼 미니게임
- 플랫폼: WeChat 미니게임

## 씬 구조
- Boot.scene: 시작 로딩 씬, GameManager 마운트
- Game.scene: 메인 게임 씬, GameRoot + UIRoot 포함
- Result.scene: 결과 페이지, 점수와 버튼 표시

## 핵심 노드
- Canvas: UI 루트 노드
- GameRoot: 게임 콘텐츠 노드, GameLogic 컴포넌트 마운트
- UIRoot: UI 레이어 노드, ScoreLabel과 PauseButton 포함

## 구현된 컴포넌트
- GameManager: 게임 생명주기 관리
- ScoreManager: 점수 계산과 저장
- AudioManager: 효과음 재생

## 코드 규칙
- 모든 UI 노드는 Canvas 아래에 둔다
- 게임 로직 노드는 GameRoot 아래에 둔다
- 컴포넌트 이름이 Manager로 끝나면 관리 클래스를 의미한다

이 파일이 있으면 AI가 더 이상 “GameManager가 무엇인가요?”, “GameRoot는 어디에 있나요?”라고 묻지 않습니다.

3. 씬 설명 문서: 자동 생성 실전 방법

3.1 왜 씬 설명 문서가 필요한가

CLAUDE.md는 프로젝트 단위의 개요라서 세부 정보가 부족합니다. 각 씬의 노드 계층과 컴포넌트 설정은 별도로 문서화해야 합니다. AI가 “이 씬에는 어떤 노드가 있고, 각 노드에는 어떤 컴포넌트가 붙어 있는지” 알 수 있어야 합니다.

저도 예전에 비슷한 실수를 한 적이 있습니다. AI에게 일시정지 기능을 만들라고 했더니 PauseButton 노드를 찾는 코드를 생성했습니다. 그런데 제 프로젝트에서 이 노드는 실제로 UIRoot/PauseLayer/PauseButton에 있었고 계층이 두 단계 더 깊었습니다. AI는 이를 몰랐고 저도 말하는 것을 잊었습니다. 결국 코드는 실행 중 오류를 냈습니다.

씬 문서는 이런 일을 막기 위한 장치입니다. 각 씬의 구조를 명확히 적어 두면 AI가 코드를 확인할 때 정확한 위치를 찾을 수 있습니다.

3.2 Prompt로 씬 문서 자동 생성하기

문서를 손으로 모두 쓰는 것은 번거롭기 때문에 저는 AI로 생성합니다. 아래 Prompt 템플릿은 그대로 복사해서 사용할 수 있습니다.

Cocos Creator 3.8 게임 프로젝트가 있습니다. 씬 설명 문서를 생성해 주세요.

프로젝트 정보:
- 게임 유형: 캐주얼 미니게임
- 엔진 버전: Cocos Creator 3.8

아래 정보를 바탕으로 문서를 작성해 주세요:
1. 씬 이름: {scene_name}
2. 씬 용도: {scene_purpose}
3. 주요 노드 계층(설명):
   - {node_structure}

출력 형식:
- 씬 개요(씬의 용도를 한 문장으로 설명)
- 노드 계층 트리(트리 구조로 표시하고 컴포넌트 표기)
- 컴포넌트 책임 설명(각 컴포넌트가 무엇을 하는지)
- 코드 참조 시 주의 사항(실수하기 쉬운 부분)

사용할 때는 {scene_name}, {scene_purpose}, {node_structure}를 자신의 실제 내용으로 바꾸면 됩니다.

3.3 실전 예시: Game.scene 문서 생성

저는 이 Prompt로 Game.scene 문서를 만들었습니다. 입력은 다음과 같습니다.

1. 씬 이름: Game.scene
2. 씬 용도: 메인 게임 씬, 게임 로직 레이어와 UI 레이어 포함
3. 주요 노드 계층:
   - Canvas(UI 루트 노드)
     - UIRoot(UI 레이어 컨테이너)
       - ScoreLabel(점수 표시, Label 컴포넌트 마운트)
       - PauseButton(일시정지 버튼, Button 컴포넌트 마운트)
   - GameRoot(게임 로직 레이어)
     - PlayerNode(플레이어 캐릭터, PlayerController 마운트)
     - EnemyRoot(적 컨테이너)

AI가 출력한 문서는 다음과 같습니다.

# Game.scene 씬 설명 문서

## 씬 개요
메인 게임 씬으로, 게임의 핵심 로직과 UI 표시를 담당합니다.

## 노드 계층 트리
Canvas (UI 루트 노드)
├── UIRoot (UI 레이어 컨테이너)
│   ├── ScoreLabel [Label] - 점수 표시
│   └── PauseButton [Button] - 일시정지 버튼
└── GameRoot (게임 로직 레이어)
    ├── PlayerNode [PlayerController] - 플레이어 캐릭터
    └── EnemyRoot - 적 컨테이너

## 컴포넌트 책임 설명
| 컴포넌트 | 마운트 노드 | 책임 |
|------|---------|------|
| PlayerController | PlayerNode | 플레이어 입력과 이동 로직 처리 |
| Label | ScoreLabel | 점수 텍스트 표시 |
| Button | PauseButton | 일시정지 버튼 상호작용 |

## 코드 참조 시 주의 사항
1. UI 노드를 찾을 때는 Canvas에서 시작해야 합니다. `this.node.getChildByName('Canvas').getChildByName('UIRoot')`
2. ScoreLabel은 UIRoot 아래에 있으며 Canvas 바로 아래에 있지 않습니다.
3. PlayerNode는 GameRoot 아래에 있으며 Canvas와 같은 레벨입니다.

이 문서를 프로젝트의 docs/ 디렉터리에 넣고 CLAUDE.md에 자세한 씬 구조는 docs/Game.scene.md 참고라는 한 줄을 추가합니다.

3.4 문서 업데이트와 유지보수 전략

문서는 한 번 쓰고 끝나는 것이 아닙니다. 씬 구조가 바뀌면 문서도 함께 바뀌어야 합니다. 현재 제가 쓰는 방식은 다음과 같습니다.

씬 구조를 수정할 때마다 문서도 바로 업데이트합니다. 대략 5분이면 끝나며, AI에게 프로젝트 구조를 매번 다시 설명하는 것보다 훨씬 낫습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

어떤 팀은 문서 생성을 CI/CD 흐름에 넣어 자동으로 트리거합니다. 하지만 작은 팀이라면 수동 업데이트가 더 현실적이라고 봅니다. 씬 구조가 매일 크게 바뀌는 것은 아니기 때문입니다.

4. MCP Server 방식: AI가 엔진과 직접 상호작용하게 만들기

4.1 MCP Server란 무엇인가

MCP(Model Context Protocol)는 AI가 JSON-RPC 인터페이스를 통해 외부 도구와 상호작용할 수 있게 하는 프로토콜입니다. Skywork AI는 Cocos Creator MCP Server를 만들었고, 이를 통해 AI가 에디터와 직접 통신할 수 있습니다.

쉽게 말하면 AI에게 씬 구조를 수동으로 알려 줄 필요가 없습니다. AI가 직접 에디터에 물어볼 수 있습니다.

4.2 MCP Server로 무엇을 할 수 있나

Skywork AI의 블로그에 따르면 Cocos MCP Server는 다음 기능을 지원합니다.

• AI가 도구 호출을 통해 씬 정보를 가져오기
• AI가 에디터 안에서 직접 노드 만들기
• AI가 프리팹 내용 읽기
• AI가 컴포넌트 설정 조회하기

이는 CLAUDE.md보다 훨씬 강력합니다. 정보가 실시간이기 때문입니다. 씬을 수정하면 문서를 동기화하지 않아도 AI가 즉시 알 수 있습니다.

4.3 MCP Server의 진입 장벽과 한계

하지만 MCP Server에도 장벽은 있습니다.

복잡한 설정: WebSocket 서비스를 시작하고 포트와 권한을 설정해야 합니다. 잘못하면 반나절은 붙잡고 있어야 할 수 있습니다.

제한적인 AI 지원: 현재 MCP 프로토콜은 Claude Code만 지원하며 Cursor와 Copilot은 아직 지원하지 않습니다.

부족한 문서: Cocos MCP Server의 문서와 커뮤니티 자료가 많지 않아 문제가 생겼을 때 찾아보기 어렵습니다.

따라서 개인 개발자로서 빠르게 문제를 해결하고 싶다면 CLAUDE.md와 씬 문서를 함께 쓰는 방식이 더 적합합니다. MCP는 장기적으로 투자할 기술 역량이 있는 팀에 더 잘 맞습니다.

4.4 MCP와 CLAUDE.md 함께 사용하기

사실 이 두 방식은 대체 관계가 아니라 상호 보완 관계입니다.

• CLAUDE.md는 정적 컨텍스트를 제공합니다. 프로젝트 개요, 명명 규칙, 설계 의도 같은 정보입니다.
• MCP는 동적 상호작용을 제공합니다. 실시간 씬 정보 조회, 노드 생성 같은 작업입니다.

MCP를 구성했더라도 CLAUDE.md는 여전히 유용합니다. MCP는 “지금 무엇이 있는지”에는 답할 수 있지만, “왜 이렇게 설계했는지”, “명명 규칙이 무엇인지”는 AI에게 알려 주지 못합니다. 이런 내용은 여전히 CLAUDE.md에 써야 합니다.

5. 실전 정리와 실행 제안

5.1 최소 실행 가능 솔루션: 오늘 바로 시작하기

AI가 프로젝트를 이해하게 만드는 것이 목적이고 고급 설정이 필요 없다면 세 단계면 충분합니다.

1단계: CLAUDE.md 파일을 만들고 프로젝트 기본 정보를 작성합니다. 엔진 버전, 게임 유형, 씬 구조 개요를 넣습니다.

2단계: 이 글의 3장에서 제공한 Prompt 템플릿으로 핵심 씬 3개의 설명 문서를 생성합니다. Boot, Game, Result 정도면 충분합니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

3단계: 씬 문서를 docs/ 디렉터리에 넣고 CLAUDE.md에서 참조하도록 합니다.

30분 안에 끝낼 수 있습니다. 이후 AI가 프로젝트 구조를 물어보면 문서를 바로 넘겨주면 됩니다.

5.2 고급 방식: 개발 역량이 있는 팀

더 많이 투자할 의향이 있다면 다음처럼 할 수 있습니다.

Cocos MCP Server 구성: Skywork AI의 오픈소스 구현을 사용합니다. 문서는 비교적 명확합니다. 구성 후에는 AI가 실시간으로 씬 정보를 가져올 수 있습니다.

씬 내보내기 스크립트 개발: Cocos 확장을 작성해 씬 구조를 JSON 또는 Markdown으로 자동 내보냅니다. 수동 설명보다 더 정확합니다.

자동 업데이트: 내보내기 스크립트를 빌드 흐름에 넣어 빌드할 때마다 CLAUDE.md를 자동으로 업데이트합니다.

이 방식은 어느 정도 개발 작업이 필요하므로 중대형 팀에 적합합니다.

5.3 장기 목표

이상적인 상태는 AI가 Web 프로젝트를 이해하듯 게임 프로젝트도 제대로 이해하는 것입니다. 에디터와 AI가 깊게 통합되고, 게임 개발 문서화가 업계 표준이 되는 상태입니다.

Unity에는 이미 Bezi 같은 실시간 인덱싱 도구가 있으니 Cocos도 아마 따라올 것입니다. 하지만 그전까지는 문서화가 가장 믿을 만한 방법입니다.

결론

AI 보조 게임 개발에는 근본적인 장애물이 있습니다. AI는 에디터 안의 내용을 볼 수 없습니다. 씬 계층, 노드 구조, 컴포넌트 설정을 알지 못합니다. 해결책은 문서화입니다. AI가 보지 못하는 것을 글로 적어 두는 것입니다.

CLAUDE.md는 프로젝트 단위 컨텍스트이고, 씬 설명 문서는 더 세밀한 보완 자료입니다. 둘을 함께 쓰면 AI가 노드를 정확히 찾고 컴포넌트의 책임을 이해할 수 있습니다. 개발 역량이 있다면 MCP Server를 구성해 AI가 실시간으로 씬 정보를 가져오게 할 수도 있습니다.

오늘 바로 시도해 보세요. CLAUDE.md 파일을 만들고 이 글의 Prompt로 첫 번째 씬 문서를 생성해 보십시오. 다른 실전 경험이 있다면 댓글로 공유해 주세요.