> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md).

# AI와 함께하는 바이브 코딩

Creator Hub와 공식 Decentraland SDK Skills(npx skills add decentraland/sdk-skills)를 사용하여 AI 비서와 함께 Decentraland 씬을 만드세요.

원하는 것을 설명해서 Decentraland 씬을 만드세요. AI 어시스턴트가 SDK7 코드, ECS 아키텍처, 프로젝트 구조를 대신 처리해 줍니다.

처음 제작하는 사람이든 숙련된 개발자든, AI 지원 "바이브 코딩"을 사용하면 몇 시간 대신 몇 분 만에 아이디어를 실행 중인 씬으로 만들 수 있습니다.

{% hint style="info" %}
**💡 팁**: 시작하려면 TypeScript를 알 필요가 없습니다. AI 어시스턴트는 평이한 언어 설명만으로 작동하는 씬 코드를 생성할 수 있습니다.
{% endhint %}

## 바이브 코딩이란 무엇인가요?

바이브 코딩은 모든 코드를 직접 한 줄씩 작성하는 대신 AI 어시스턴트와 대화하면서 씬을 만드는 것을 의미합니다. "클릭 가능한 문과 배경 음악이 있는 중세 선술집"처럼 원하는 것을 설명하면, AI가 올바르고 배포 가능한 SDK7 코드를 작성합니다.

이 방식은 어떤 숙련도에서도 잘 작동합니다:

* **초보자 및 비개발자** — 수동으로 코드를 작성하지 않고도 처음부터 작동하는 씬까지 만들 수 있습니다.
* **숙련된 개발자** — 보일러플레이트를 건너뛰세요. AI가 멀티플레이어 동기화, UI 스캐폴딩, 배포 설정을 처리하는 동안, 당신은 창의적인 결정에 집중할 수 있습니다.
* **팀 및 스튜디오** — 전체 개발 리소스를 투입하기 전에 씬 콘셉트를 빠르게 프로토타이핑하세요.

## Creator Hub에서 AI 어시스턴트 사용하기

가장 빠르게 시작하는 방법은 Creator Hub에 내장된 [AI 어시스턴트](/creator/content-creator-ko/scene-editor/extend-with-code/ai-assistant.md). 열려 있는 씬을 보고, 엔티티, 컴포넌트, 스마트 아이템, 코드를 대신 편집해 주며, 미리보기를 실행해 스스로의 작업을 확인할 수도 있습니다. 아래의 스킬을 프로젝트에 자동으로 설치하므로, 코딩 CLI에 로그인하는 것 외에는 설정할 것이 없습니다.

실험 기능이며 기본적으로 꺼져 있습니다.

## 코드 편집기와 AI를 결합하기

다음과 같은 범용 AI 코드 편집기를 사용하세요 [Cursor](https://www.cursor.com/) 또는 GitHub Copilot이나 Claude AI가 있는 VS Code를 사용하세요. Decentraland는 이러한 도구가 SDK를 이해할 수 있도록 컨텍스트 폴더를 제공합니다.

1. Creator Hub를 열고 씬을 만들거나 여세요.
2. 다음의 **< > CODE** 버튼을 눌러 코드 편집기를 여세요.
3. 편집기의 내장 AI 어시스턴트(Cursor의 채팅, Copilot 등)를 사용해 코드를 생성하거나 수정하세요.

## 모든 AI 에이전트를 위한 스킬 설치

스킬은 Decentraland SDK와 함께 작업하는 방법을 AI 에이전트에게 가르치는, 미리 준비된 지시 세트입니다. 각 스킬은 씬 만들기, 3D 모델 추가, 멀티플레이어 설정처럼 특정 주제를 다루므로, AI는 당신이 일일이 설명하지 않아도 올바른 패턴, API, 제약 조건을 이미 알고 있습니다. 스킬을 설치하면 실수는 줄고 첫 프롬프트부터 더 나은 결과를 얻을 수 있습니다.

```bash
# 인터랙티브 선택기에서 설치할 Decentraland 스킬을 선택하세요
npx skills add decentraland/sdk-skills

# 또는 모든 Decentraland 스킬을 설치하세요
npx skills add decentraland/sdk-skills --all

# 또는 특정 스킬을 선택하세요
npx skills add decentraland/sdk-skills --skill create-scene

# 전역으로 설치(모든 프로젝트에서 사용 가능)
npx skills add decentraland/sdk-skills -g
```

이것은 스킬 파일을 에이전트의 설정에 복사하여 Decentraland의 패턴과 제약 조건을 알 수 있게 합니다.

## 스킬 업데이트

새 스킬은 시간이 지나면서 추가되고, 기존 스킬도 개선됩니다. 최신 버전을 받으려면 설치 명령을 다시 실행할 때 `--all`:

```bash
# 설치된 모든 스킬을 업데이트하고 새로 추가된 스킬도 다운로드
npx skills add decentraland/sdk-skills --all
```

다시 실행하면 `add` 는 저장소를 다시 가져오므로, 이미 가지고 있는 스킬을 새로 고치고 처음 설치한 이후에 추가된 스킬도 설치합니다. 스킬을 전역으로 설치했다면, 이 명령에도 `-g` 를 추가하세요.

{% hint style="warning" %}
**📔 참고**: 다음은 사용하지 마세요 `npx skills update` 이 명령은 이미 기기에 있는 스킬만 새로 고치므로, 마지막 설치 이후 저장소에 추가된 스킬은 조용히 건너뜁니다. 항상 `npx skills add decentraland/sdk-skills --all` 대신 사용하세요.
{% endhint %}

## 사용 가능한 AI 스킬

에이전트에 스킬을 설치하면 다음 기능을 사용할 수 있습니다:

| 스킬                     | 기능                                             |
| ---------------------- | ---------------------------------------------- |
| `sdk-scenes`           | 에이전트 지침과 모든 주제별 스킬 인덱스가 있는 진입점                 |
| `create-scene`         | 새 SDK7 씬 프로젝트를 처음부터 스캐폴딩                       |
| `migrate-sdk6-to-sdk7` | 레거시 SDK6 씬을 SDK7로 포팅                           |
| `add-3d-models`        | 3D 모델 추가 (`.glb`/`.gltf`) 위치 지정, 크기 조절, 충돌체 포함 |
| `add-interactivity`    | 포인터 이벤트, 트리거, 레이캐스트                            |
| `build-ui`             | React-ECS를 사용하는 2D 화면 공간 UI — HUD, 메뉴, 대화상자    |
| `animations-tweens`    | Animator와 SDK tweens를 사용한 GLTF 모델 애니메이션        |
| `multiplayer-sync`     | CRDT 네트워킹을 사용하는 P2P 멀티플레이어                     |
| `authoritative-server` | 서버 검증형 씬을 위한 헤드리스 멀티플레이어 서버(BETA)              |
| `audio-video`          | 효과음, 음악, 오디오 스트리밍, 비디오 플레이어                    |
| `audio-analysis`       | 오디오 반응형 씬을 위한 실시간 진폭 및 주파수 데이터                 |
| `deploy-scene`         | Genesis City(LAND 기반)으로 씬 배포                   |
| `deploy-worlds`        | Worlds(개인 3D 공간)으로 씬 배포                        |
| `optimize-scene`       | 성능 최적화, 씬 제한, 모범 사례                            |
| `camera-control`       | 카메라 모드 감지, 시네마틱 카메라, 가상 카메라                    |
| `composites`           | 정적 씬 콘텐츠를 위한 복합 파일 형식 참고                       |
| `lighting-environment` | 동적 조명, 그림자, 스카이박스, 안개, 환경 설정                   |
| `particle-system`      | 파티클 효과 — 불, 연기, 불꽃, 눈, 불꽃놀이                    |
| `npcs`                 | 플레이어가 아닌 캐릭터 — NPC Toolkit 라이브러리 및 수동 접근 방식    |
| `player-avatar`        | 플레이어 위치, 프로필, 아바타 커스터마이징, 부착물                  |
| `player-physics`       | 물리력 — 임펄스, 넉백, 지속적인 힘                          |
| `nft-blockchain`       | NFT 표시 및 블록체인/암호화폐 상호작용                        |
| `advanced-rendering`   | 빌보드, TextShape, PBR 재질, 비디오 재질                 |
| `advanced-input`       | 시스템 수준 입력 폴링 및 플레이어 이동 제어                      |
| `scene-runtime`        | 교차 영역 런타임 API — 비동기 작업, HTTP, 메시징              |
| `script-components`    | Creator Hub용 스크립트 컴포넌트 클래스                     |
| `game-design`          | 게임 디자인 패턴, 씬 제한, 성능 예산                         |
| `unity-explorer-mcp`   | 실행 중인 Explorer를 조작해 인월드에서 씬을 테스트하고 검증          |

참고: 이 스킬 중 일부는 무료 에셋 카탈로그에서 3D 모델이나 기타 에셋을 가져오는 작업을 포함합니다. AI 에이전트는 씬 프로젝트에 새 에셋을 다운로드하기 전에 항상 사용자에게 확인을 받아야 합니다.

## AI가 인월드에서 당신의 씬을 보게 하기

보통 AI가 코드를 작성하고 *당신은* 미리보기를 실행하고, 살펴본 뒤, 무엇이 잘못됐는지 보고합니다. Decentraland 데스크톱 클라이언트는 그 과정을 닫아 줄 수 있습니다. 선택 사항인 **MCP 서버** 가 포함되어 있어, AI 에이전트가 실행 중인 Explorer를 직접 보고 제어할 수 있습니다. 에이전트는 스스로 스크린샷을 찍고, 씬의 콘솔 출력을 읽고, 플레이어를 돌아다니게 하고, 오브젝트를 클릭하고, 씬이 실제로 요구된 대로 작동하는지 확인한 다음, 발견한 문제를 고치고 다시 살펴봅니다.

이것은 바이브 코딩을 "설명, 대기, 검토"에서 에이전트가 대부분 스스로 실행할 수 있는 루프로 바꿔 줍니다.

{% hint style="info" %}
**💡 팁**: 다음을 설치하세요 `unity-explorer-mcp` 이 기능을 시도하기 전에 스킬을

```bash
npx skills add decentraland/sdk-skills --skill unity-explorer-mcp
```

{% endhint %}

### 필요한 것

* 그 **Decentraland 데스크톱 클라이언트** 설치됨( Creator Hub가 미리보기용으로 실행하는 것과 동일한 클라이언트).
* HTTP를 통해 MCP 서버에 연결할 수 있는 AI 에이전트 — Claude Code, Cursor, Cline, MCP를 지원하는 확장 기능이 있는 VS Code 등.
* 씬에 최신 SDK가 있어야 합니다: 실행하세요 `npm i @dcl/sdk@latest` 만약 `--mcp` 아래 플래그가 알 수 없는 옵션으로 거부된다면.

### 1. MCP 서버를 활성화한 상태로 씬 실행하기

씬 폴더에서:

```bash
npm run start -- --mcp
```

이것은 `npm run start` 가 항상 하는 일을 수행합니다 — 씬을 `http://127.0.0.1:8000` 에서 제공하고, 파일을 저장할 때마다 핫 리로드합니다 — 그리고 추가로 MCP 서버가 다음에서 대기하도록 데스크톱 클라이언트를 실행합니다 `http://127.0.0.1:8123/unity-explorer-mcp`.

클라이언트가 열리면 로그인하세요. 에이전트는 로그인 화면을 통과하고 월드가 로드된 후에만 작업을 시작할 수 있습니다.

### 2. AI 에이전트를 서버에 연결하기

에서 **Claude Code**, 한 번만 등록하세요:

```bash
claude mcp add --transport http --scope user explorer http://127.0.0.1:8123/unity-explorer-mcp
```

에서 **다른 MCP 클라이언트의 경우**, 해당 클라이언트 문서의 방식에 따라 다음 세부 정보를 사용해 서버를 추가하세요:

| 설정  | 값                                                               |
| --- | --------------------------------------------------------------- |
| 전송  | 스트리밍 가능 HTTP(stdio 아님 — 실행할 명령이 없고, 서버는 실행 중인 클라이언트 내부에서 동작합니다) |
| URL | `http://127.0.0.1:8123/unity-explorer-mcp`                      |
| 인증  | 없음                                                              |
| 이름  | `explorer`                                                      |

많은 클라이언트는 이를 위해 JSON 구성 파일을 사용합니다(`.cursor/mcp.json`, `mcp.json`등 — 정확한 키 이름은 클라이언트 문서를 확인하세요):

```json
{
  "mcpServers": {
    "explorer": {
      "type": "http",
      "url": "http://127.0.0.1:8123/unity-explorer-mcp"
    }
  }
}
```

서버를 등록한 뒤 AI 클라이언트를 다시 시작하거나 다시 불러와서 연결을 인식하게 하세요. 에이전트가 Explorer 도구를 사용할 수 없다고 말한다면, 보통 원인은 에이전트가 시작될 때 클라이언트가 실행 중이지 않았기 때문입니다 — Explorer를 연 상태에서 서버를 다시 연결하세요(Claude Code에서는 `/mcp`를 실행하세요).

{% hint style="info" %}
**이게 안전한가요?** 서버는 클라이언트를 `--mcp`와 함께 실행할 때만 동작하고, 자신의 컴퓨터에서 온 연결(`127.0.0.1`)만 허용하며, 웹페이지에서 오는 요청은 거부합니다. 인터넷에 노출되는 것은 없고, 일반적인 클라이언트 실행에서는 완전히 꺼져 있습니다.
{% endhint %}

### 3. 원하는 것을 요청하고, 검증하게 하세요

서버가 연결되면 평소처럼 작업을 요청하세요 — 차이점은 이제 에이전트가 자신의 결과를 직접 확인할 수 있다는 점입니다:

> "클릭하면 열리는 보물상자를 parcel 중앙에 추가한 다음, 가서 직접 클릭해서 뚜껑 애니메이션이 재생되는지 확인하세요."

> "네온사인이 너무 어두워 보여요. 스크린샷을 찍고, 발광 강도를 조정한 뒤, 전후 비교를 보여 주세요."

> "엘리베이터에 뭔가 문제가 있어요. 플랫폼 위로 걸어가 로그를 보고, 왜 움직이지 않는지 알려 주세요."

내부적으로는 에이전트가 다음을 할 수 있습니다:

* **참고** — 스크린샷을 찍고, 씬의 `console.log` 출력과 오류를 읽고, 씬이 로드되었는지 또는 충돌했는지 확인하고, 씬의 엔티티를 나열하고 해당 컴포넌트를 검사하며, 플레이어와 카메라 위치를 읽습니다.
* **제어** — 플레이어를 이동시키고 텔레포트하며, 실제 충돌을 통과해 특정 방향으로 걸어가고, 카메라를 조준하고, 특정 샷을 위해 자유 카메라를 배치하고, 카메라 모드를 전환하고, 씬 오브젝트를 클릭하고, 채팅 메시지와 `/commands`를 보내고, 이모트를 트리거하고, 씬을 다시 불러옵니다.
* **측정** — Decentraland의 제한에 맞춰 씬 콘텐츠의 실시간 수치(삼각형 수, 엔티티, 텍스처, 재질 등)를 읽고, 어떤 3D 모델이 어느 시점에서 가장 큰 부담을 주는지 순위를 매기며, 플레이어가 어느 위치에서든 실제로 경험하는 프레임률을 샘플링합니다.

### 이를 사용해 씬을 최적화하세요

에이전트는 볼 수 있을 뿐 아니라 측정도 할 수 있으므로, 성능 작업을 직접 맡길 수 있습니다. 다음을 기준으로 씬을 확인할 수 있습니다 [씬 제한 사항](/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md), 어떤 3D 모델이 가장 무거운지 식별하고, 특정 위치에서 프레임률을 측정하며, 가장 중요한 것은 변경 후 다시 측정하여 개선 효과를 입증하는 것입니다:

> "내 씬이 Decentraland의 콘텐츠 제한 안에 있는지 확인하고, 어떤 예산이 한계치에 가장 가까운지 알려 주세요."

> "분수 근처에서 씬이 끊기는 느낌이에요. 거기에 서서 프레임률을 측정하고, 그 지점에서 어떤 모델이 가장 비용이 큰지 알려 주세요."

> "씬을 최적화하세요: 프레임률을 떨어뜨리는 원인을 찾아 고치고, 전후 측정값을 보여 주세요."

최상의 결과를 위해 `optimize-scene` 스킬을 함께 `unity-explorer-mcp`설치하세요. 그러면 에이전트도 Decentraland의 최적화 모범 사례를 알게 됩니다. 이 워크플로에 대한 자세한 내용은 [성능 최적화](/creator/content-creator-ko/sdk7/optimizing/performance-optimization.md#optimize-with-ai) 을 참조하세요. Blender MCP 서버와 함께 사용하여 3D 모델 자체의 수정을 자동화하는 방법도 포함되어 있습니다.

### 팁

* **주장보다 증거를 요청하세요.** "스크린샷으로 확인하세요" 또는 "로그에서 확인하세요"가 이 워크플로의 핵심입니다. 좋은 에이전트는 둘 다 교차 확인합니다. 픽셀은 맞아 보여도 내부 상태는 깨져 있을 수 있고, 그 반대도 마찬가지입니다.
* **스크린샷은 토큰을 소모합니다.** 에이전트가 보는 각 스크린샷은 컨텍스트의 일부를 소비합니다. 시간에 따른 애니메이션, 여러 지점의 탐색처럼 긴 시각적 확인이 필요하다면, 프레임을 파일로 캡처해 달라고 하고 중요한 것만 읽게 하세요.  `unity-explorer-mcp` 스킬에는 정확히 이를 수행하는 스크립트가 포함되어 있습니다.
* **한 번만 저장하고, 연속해서 다섯 번 저장하지 마세요.** 짧은 간격의 연속 저장은 클라이언트가 반쯤 작성된 번들을 불러와 씬을 완전히 떨어뜨리게 만들 수 있으며, 이 경우 복구하려면 클라이언트를 재시작해야 합니다. 에이전트가 편집 내용을 한 번의 저장으로 묶도록 하세요.
* **클라이언트를 열어 두세요.** 닫아 버리면 연결이 끊기고 에이전트는 눈을 잃습니다. 같은 명령으로 다시 실행하면 복구됩니다.
* **로컬 씬 개발에서는 텔레포트가 다르게 동작합니다.** 와 함께 parcel 사이를 이동하는 것은 `/goto` 허용되지 않으므로, 에이전트는 텔레포트 대신 씬 내부에서 플레이어의 위치를 다시 잡아야 합니다.

## 효과적인 프롬프트를 위한 팁

AI에서 최상의 결과를 얻으려면 명확하고 구체적인 프롬프트를 주는 것이 중요합니다. 몇 가지 팁은 다음과 같습니다:

### 원하는 것을 구체적으로 말하세요

예를 들면:

> "내 씬을 더 좋게 만들어 줘"

대신 다음처럼 해보세요:

> "위치 (8, 0, 8)에 문을 추가하고, 클릭하면 회전 애니메이션으로 열리며, 삐걱거리는 효과음을 재생하게 해 줘"

### 기존 항목을 참조하세요

> "테이블 위의 빨간 버튼이 엘리베이터를 위로 올라가게 해 줘"

### 한 번에 하나씩 요청하세요

복잡한 요청은 단계로 나누세요:

1. "오른쪽 상단에 점수판 UI를 추가해 줘"
2. "플레이어가 목표를 클릭할 때마다 증가하는 카운터를 추가해 줘"
3. "점수판에 카운터 값을 표시해 줘"

### 반복하고 다듬으세요

각 변경 후:

1. 씬 미리보기(클릭 **미리보기** Creator Hub에서, 또는 `npm run start` 명령줄에서)
2. 무엇이 작동하고 무엇이 작동하지 않는지 확인하세요
3. AI에게 조정할 내용을 말하세요: "NPC를 왼쪽으로 2미터 이동시키고 플레이어를 바라보게 해 줘"

### 예시 프롬프트

새로 클론한 [sdk7-scene-template](https://github.com/decentraland/sdk7-scene-template/).

#### 프롬프트 예시 1

```
현재 씬 코드를 전부 버리고, 1 parcel 안에 작고 단순한 미로 게임을 만들어 주세요. 벽은 큐브여도 되고, 충돌이 있어야 합니다.

플레이어가 A 지점에서 실제로 미로에 들어가면 게임이 시작되고, B 지점에서 나가면 끝나야 합니다(미로의 유일한 출구).

미로에 서로 다른 3개의 문을 추가해 주세요. 이 문들은 포인터 입력으로 상호작용해서 열고 통과해야 합니다.

플레이어가 실제로 플레이하고 승리할 수 있는지 검증해야 합니다
```

#### 프롬프트 예시 2

```
현재 씬 코드를 전부 버리고 간단한 플랫포머 게임을 만들어 주세요.

완성으로 간주하기 전에 게임을 승리할 수 있는지 반드시 검증해야 합니다.
```

## AI가 도와줄 수 있는 것

* 설명만으로 새 씬 스캐폴딩
* 3D 모델 추가 및 배치
* 클릭 핸들러 및 상호작용 작성
* UI 구축(HUD, 메뉴, 대화상자)
* 멀티플레이어 동기화 설정
* 치트 방지를 위한 멀티플레이어 서버 구성
* 오디오, 비디오, 스트리밍 추가
* 애니메이션 및 트윈 생성
* 씬 성능 최적화
* 배포를 위한 씬 준비
* 기존 코드의 문제 디버깅
* 실행 중인 Explorer에서 씬을 테스트하고 시각적으로 검증(참조 [AI가 인월드에서 당신의 씬을 보게 하기](#let-the-ai-see-your-scene-in-world))

## 제한 사항

AI 도구는 강력하지만, 다음 사항을 기억하세요:

* **항상 미리보기** — AI가 생성한 코드는 기대한 모습과 정확히 같지 않을 수 있습니다. 미리보기를 실행해 확인하세요.
* **씬 제한은 여전히 적용됩니다** — AI는 Decentraland의 [씬 제한 사항](/creator/content-creator-ko/sdk7/optimizing/scene-limitations.md) (삼각형 수, 파일 크기, parcel 경계)를 우회할 수 없습니다.
* **복잡한 게임 로직** — 정교한 게임 메커니즘의 경우, AI를 단계별로 안내하거나 출력을 수동으로 다듬어야 할 수 있습니다.
* **맞춤형 3D 모델** — AI는 기존 무료 에셋을 참조하거나 당신이 제공한 모델을 불러올 수는 있지만, 처음부터 3D 모델을 만들 수는 없습니다(동시에 Blender 공식 MCP 서버 같은 다른 도구를 사용할 경우는 예외).

## 다음 단계

* [SDK 빠른 시작](/creator/content-creator-ko/sdk7/getting-started/sdk-101.md) — SDK7 기초 배우기
* [코드와 결합](/creator/content-creator-ko/scene-editor/extend-with-code/overview.md) — 시각적 편집과 코드를 섞어 사용하기
* [멀티플레이어 서버](/creator/content-creator-ko/sdk7/networking/authoritative-servers.md) — 서버 권한형 멀티플레이어
* [씬 예시](https://studios.decentraland.org/resources?sdk_version=SDK7) — 영감을 얻기 위해 예시 씬 둘러보기
* [유용한 자료](/creator/content-creator-ko/sdk7/getting-started/useful-resources.md) — 워크플로를 더 빠르게 만드는 더 많은 AI 도구, 에셋 라이브러리, 애드온


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.