> 생성: 2026-10-07 | 작성자: 연제의 Claude | 맥락: 에디터 데모 키트 — 미리캔버스 에디터 위에서 UX 검증용 데모를 여러 명이 함께 만들고(선택) 사내에 공개하기 위한 절차

# 데모 작업 가이드

개발 경험이 없어도 따라올 수 있도록 작성했습니다. 순서대로 진행하시면 됩니다.

이 키트로 만드는 것: **미리캔버스 에디터 화면 위에서 동작하는 UX 검증용 데모**와, 그 데모들을 모아 보여주는 첫 화면·상단바·정책 보기·코드 보기.

---

## 0부. 먼저 설정하세요

키트를 처음 받았으면 **아래 자리표시자를 먼저 채웁니다.** 클로드 코드에 `이 가이드 읽고 키트 초기 설정해줘. 스쿼드 이름은 ○○, 문의처는 ○○` 라고 하면 됩니다.

### 필수 — 로컬에서 데모를 만들기만 해도 필요한 것

| 자리표시자 | 뜻 | 어디에 있나 |
|---|---|---|
| `{{SQUAD}}` | 스쿼드 이름 (첫 화면 제목에 붙습니다) | `demo/index.html` |
| `{{CONTACT}}` | 문의처 — 이름 / 이메일 | `demo/index.html` 푸터 |

### 선택 — GitHub 로 함께 작업할 때

GitHub 는 선택입니다. 혼자 로컬에서 만들고 화면을 직접 보여 주는 것으로 충분하면 건너뜁니다. 여러 명이 함께 만들거나, 배포 시점을 기록으로 남기고 싶을 때 씁니다.

| 자리표시자 | 뜻 | 어디에 있나 |
|---|---|---|
| `{{OWNER}}` / `{{REPO}}` | 저장소 주인 / 이름 (`github.com/{{OWNER}}/{{REPO}}`) | 이 문서 1-2 |

### 선택 — 사내 주소로 공개할 때

배포도 선택입니다. `<앱이름>.miridih.app` 주소로 팀에 공유하려 할 때만 합니다.

| 자리표시자 | 뜻 | 어디에 있나 |
|---|---|---|
| `{{APP_NAME}}` | 앱 이름 = 주소 (`https://{{APP_NAME}}.miridih.app`). 소문자·숫자·하이픈, 3~30자 | `demo/deployment-manifest.yaml.template` → 복사한 `deployment-manifest.yaml` |

자리표시자가 남아 있는지는 한 번에 확인할 수 있습니다.

```bash
grep -rn "{{" demo/index.html demo/deployment-manifest.yaml 2>/dev/null
```

---

## 클로드 코드로 작업하는 방법

이 문서의 명령어를 직접 입력할 필요는 없습니다. 클로드 코드에 이 파일을 전달한 뒤 필요한 작업을 요청하시면 됩니다.

**새 데모 만들기는 스킬로 등록되어 있습니다.** `새 데모 만들어줘` 라고만 말하면, 클로드가 필요한 항목(이름·제목·설명·작업자·담당자 등)을 물어본 뒤 처리합니다. 명령어나 항목 이름을 기억할 필요가 없습니다. 스킬 파일은 키트의 `.claude/skills/new-demo/` 에 있으므로, 키트 폴더를 받으면 함께 설치됩니다.

| 작업 | 요청 예시 |
|---|---|
| 초기 설정 | `이 가이드 읽고 키트 초기 설정해줘. 스쿼드 이름은 ○○, 문의처는 ○○` |
| 새 데모 생성 | `새 데모 만들어줘. 이름 photo-crop, 제목 "AI 사진 자르기", 설명 "사진을 원하는 비율로 자르는 흐름 확인", PM ○○, PD ○○, FE ○○, 일자 26.10` |
| 다른 사람 데모를 출발점으로 | `other-demo 를 바탕으로 내 데모 photo-crop 만들어줘. 설명은 "…"` |
| 데모 베이스 업데이트 | `○○ 기능이 온고잉으로 확정됐어. 데모 베이스에 반영해줘` |
| 화면 확인 | `데모 띄워서 보여줘` |
| 배포 설정 (선택, 최초 1회) | `배포 설정해줘. 앱 이름은 ○○-demo` |
| 사내 공개 (선택) | `배포해줘` |

직접 수행해야 하는 항목은 **배포 토큰 발급** 하나입니다(배포할 때만). 비밀 값이므로 클로드가 대신 발급받을 수 없습니다. 절차는 [3-2](#3-2-배포-토큰-발급)를 참고하십시오.

이후 내용은 각 단계에서 무엇이 일어나는지 확인하거나, 직접 작업할 때 참고하시면 됩니다.

---

## 용어 정리

본문에 반복해서 등장하는 용어입니다.

| 용어 | 의미 |
|---|---|
| **데모 베이스** | `demo/base-editor.html` 파일입니다. 데모 로직이 없는 빈 에디터 화면으로, 새 데모는 이 파일을 복사해 시작합니다 |
| **데모 셸** | 데모 화면 위에 붙는 상단바(홈 · 지금 동작 · 컨트롤 · 정책 보기 · 코드 보기)입니다. `demo/assets/demo-shell/` 에 있습니다 |
| **데모 정보 파일** | `demo/assets/demo-shell/demos/<이름>.js`. 그 데모의 동작 목록·정책 글·파일 목록이 들어 있습니다 |
| **AI 프레젠테이션 오버레이** | 에디터 안 "AI 프레젠테이션" 카드를 누르면 전체화면으로 뜨는 실물 화면(`demo/aip/`)입니다. 모든 데모가 하나를 공유합니다 |
| **저장소 (repository)** | (선택) 파일을 함께 보관하는 서버상의 폴더입니다. 변경 이력이 모두 기록됩니다 |
| **clone / commit / push / pull** | (선택) 저장소를 내 컴퓨터로 복사 / 변경을 한 단위로 저장 / 서버로 올림 / 서버의 최신을 받음 |
| **배포 (deploy)** | (선택) 내 컴퓨터의 파일을 사내 주소(`<앱이름>.miridih.app`)에 올려 공개하는 작업입니다 |

**push 와 배포는 별개의 작업입니다.** push 는 코드를 팀원에게 공유하는 것이고, 배포는 화면을 사내에 공개하는 것입니다. 각각 따로 수행하며, 둘 다 선택입니다.

---

## 1부. 최초 환경 설정

### 1-1. 필수 — 설치 확인

```bash
node -v                       # 버전 번호가 출력되면 정상입니다 (new-demo.sh 가 목록을 읽을 때 사용)
python3 --version             # 버전 번호가 출력되면 정상입니다 (new-demo.sh 가 카드를 넣을 때 사용)
```

Windows 에서 `python3` 가 없으면 python.org 에서 설치한 뒤 Git Bash 를 다시 여십시오. 터미널은 macOS 는 기본 터미널, Windows 는 Git Bash 를 사용합니다.

### 1-2. 선택 — 저장소 복사 (clone)

GitHub 로 함께 작업할 때만 합니다. 저장소 주인(`{{OWNER}}`)에게 GitHub 아이디를 전달하고 초대를 요청한 뒤, 초대 메일을 수락합니다.

```bash
git clone git@github.com:{{OWNER}}/{{REPO}}.git
cd {{REPO}}
```

위 방식이 동작하지 않으면 아래를 사용합니다. GitHub 아이디와 함께 비밀번호 대신 토큰을 요구합니다.

```bash
git clone https://github.com/{{OWNER}}/{{REPO}}.git
```

GitHub 를 쓰지 않으면 키트 폴더를 그대로 두고 작업합니다. 그래도 `git init` 으로 로컬 저장소만 만들어 두면 배포 때 "커밋 xxx 기준" 표기가 생겨 어느 시점 화면인지 알 수 있습니다.

### 1-3. 선택 — 배포 스킬 설치

사내 주소로 공개할 때만 합니다. `miridih-internal-deploy.zip` 을 받아 아래를 실행합니다.

```bash
mkdir -p ~/.claude/skills
unzip -o ~/Downloads/miridih-internal-deploy.zip -d ~/.claude/skills/
chmod +x ~/.claude/skills/miridih-internal-deploy/scripts/*.sh
```

zip 파일은 사내 위키 「내가 만든 앱 직접 배포 하기」 페이지에 첨부되어 있습니다. 키트에는 이 스킬이 들어 있지 않습니다(사내 공용 도구라 키트와 별도로 갱신됩니다).

배포에는 `jq` 와 `curl` 도 필요합니다. `command -v jq curl` 로 경로가 출력되면 정상이고, `jq` 가 없으면 macOS 에서는 `brew install jq` 로 설치합니다.

---

## 2부. 작업 흐름

### 2-1. 작업 시작 — pull 우선 (GitHub 를 쓸 때)

```bash
git pull
```

팀원이 올린 최신 내용을 받아옵니다. **이 과정을 생략하면 이후 충돌이 발생합니다.** GitHub 를 쓰지 않으면 건너뜁니다.

### 2-2. 로컬 화면 확인

파일을 브라우저에서 직접 열면(`file://`) 일부 기능이 동작하지 않습니다. 로컬 서버를 실행한 뒤 확인하십시오.

```bash
cd demo
python3 -m http.server 8899
```

브라우저에서 `http://localhost:8899` 로 접속합니다. 확인이 끝나면 터미널에서 `Ctrl+C` 로 서버를 종료합니다.

### 2-3. 변경 사항 저장과 공유 (GitHub 를 쓸 때)

```bash
git add .
git commit -m "무엇을 왜 바꿨는지 한 줄"
git push
```

`push` 까지 완료해야 팀원이 확인할 수 있습니다.

---

## 3부. 사내 공개 (배포 · 선택)

### 3-1. 배포 설정 (최초 1회)

키트에는 배포 설정이 **템플릿으로만** 들어 있습니다. 스쿼드마다 앱 이름이 다르기 때문입니다.

```bash
cd demo
cp deployment-manifest.yaml.template deployment-manifest.yaml
```

복사한 파일의 `{{APP_NAME}}` 과 `CHANGEME` 를 전부 채웁니다. 채울 것은 앱 이름 · 소유자(이메일 @ 앞부분, 이메일, 팀) · 생성 시각 · 목적 · Cloudflare Account ID · 재검토일입니다. Account ID 는 Cloudflare 대시보드 → Workers & Pages 오른쪽에 있으며 시크릿이 아닙니다. 그다음 배포 스킬로 나머지 설정 파일을 생성합니다.

```bash
bash ~/.claude/skills/miridih-internal-deploy/scripts/generate-wrangler-config.sh . <앱이름> --strategy static
```

`wrangler.jsonc` 와 `.miridih/router.js` 가 만들어집니다. 이 두 파일은 손으로 만들지 않습니다. `deployment-manifest.yaml` 과 `wrangler.jsonc` 는 `.assetsignore` 에 있어 사이트로 공개되지 않습니다.

하나라도 빠지면 `deploy.sh` 가 0단계에서 무엇을 해야 하는지 알려주고 멈춥니다.

### 3-2. 배포 토큰 발급

토큰은 개인별로 발급받습니다. **공용 토큰 사용은 사내 정책상 금지**되어 있으며, 타인과 공유해서는 안 됩니다. 발급에는 약 30초가 소요됩니다.

1. 슬랙 **#axe-anything** 채널에서 `/mivault-cf-token` 을 입력합니다
2. 입력창이 표시되면 사용 목적을 한 줄로 작성합니다 (예: `{{SQUAD}} 데모 배포`)
3. **mivault 봇 DM** 으로 토큰이 전달됩니다. 이 값은 **60분 후 자동으로 삭제**됩니다
4. 삭제 전에 본인 터미널에서 아래를 실행합니다

```bash
bash ~/.claude/skills/miridih-internal-deploy/scripts/setup-credentials.sh
```

안내에 따라 값을 붙여넣습니다. 토큰 입력 시 화면에 아무것도 표시되지 않는 것은 정상 동작입니다.

> **참고 사항**
> - 토큰 유효기간은 **3일**입니다. 만료 하루 전과 당일에 DM 이 발송되며, **[연장]** 버튼을 누르면 동일한 값으로 연장됩니다
> - 한 사람당 활성 토큰은 **1개**입니다
> - 배포는 **사무실 또는 VPN 환경**에서만 가능합니다. 토큰이 사무실 IP 에 연결되어 있습니다

### 3-3. 배포 절차

배포는 두 단계로 진행합니다.

```bash
cd demo

bash deploy.sh          # ① 공개될 내용을 확인하고 중단
bash deploy.sh --go     # ② 실제 배포
```

**①을 먼저 실행합니다.** 무엇이 공개될지 보여준 뒤 중단하므로, 내용을 확인하고 ②를 실행하십시오.

### 3-4. 배포 스크립트 검사 항목

| 단계 | 검사 내용 |
|---|---|
| 0 | **배포 설정** — `deployment-manifest.yaml` 과 `wrangler.jsonc` 가 있고 자리표시자가 남아 있지 않은지. 없으면 할 일을 알려주고 멈춥니다 |
| 1 | **커밋되지 않은 변경** — 배포는 현재 폴더의 파일을 그대로 올립니다. 작업 중인 코드도 함께 공개됩니다 (git 이 아니면 건너뜀) |
| 1-2 | **GitHub 최신 여부** — 팀원이 올린 내용을 받지 않은 상태이면 **배포를 거부합니다** (원격 저장소가 없으면 건너뜀) |
| 1-3 | **데모 베이스 변경 기록** — 베이스를 수정했는데 첫 화면 기록이 없으면 경고합니다 |
| 1-4 | **가이드 파일 동기화** — 이 문서를 `demo/demo-guide.md` 로 복사합니다 (첫 화면의 내려받기 링크) |
| 2 | 화면에 표시되는 "커밋 xxx 기준" 갱신 (git 이 아니면 `no-git`) |
| 3 | 비밀 값(토큰·비밀번호)이 코드에 포함되었는지 검사 |
| 4 | 업로드 (변경된 파일만, 약 5초) |
| 5 | 업로드된 파일과 로컬 파일 대조 |

### 3-5. 배포가 거부된 경우

**"GitHub에 내가 안 받은 커밋이 N개 있습니다"** 라는 메시지가 표시되면, 그대로 배포할 경우 해당 작업이 사이트에서 사라집니다. 최신 내용을 받은 뒤 다시 배포하십시오.

```bash
git pull
bash deploy.sh --go
```

### 3-6. 배포 권한

배포는 누구나 수행할 수 있습니다. 단 GitHub 를 쓴다면 반드시 `git pull` 을 먼저 실행하십시오. 스크립트가 확인하지만 습관으로 두는 편이 안전합니다.

현재 사이트에 반영된 코드 시점은 화면 상단바 오른쪽의 **"커밋 xxxxxxx 기준"** 에서 확인할 수 있습니다.

---

## 4부. 준수 사항

### 금지 사항

| 항목 | 사유 |
|---|---|
| 토큰을 저장소에 커밋 | 비밀 값입니다. 배포 스크립트가 검사하지만, 처음부터 포함하지 않아야 합니다 |
| 토큰을 슬랙·문서·채팅에 게시 | 게시 시점에 노출된 것으로 간주되어 회수 및 재발급 대상이 됩니다 |
| 토큰을 팀원과 공유 | 사내 정책상 금지입니다. 개인별로 발급받으십시오 |
| `git pull` 없이 배포 (GitHub 를 쓸 때) | 다른 사람의 작업이 사이트에서 사라집니다 |

### 새 데모의 출발점

여러 명이 각자 다른 파일을 복제하면 에디터 화면이 서로 달라집니다. 이를 방지하기 위해 출발점을 하나로 고정했습니다.

| 명령 | 출발점 | 사용 시점 |
|---|---|---|
| `bash new-demo.sh <이름> "<제목>"` | 데모 베이스 `base-editor.html` | 대부분의 경우. 에디터 화면에서 무언가를 검증할 때 |
| `... --from <기존데모>` | 해당 데모의 화면 | **다른 사람이 만든 데모**를 출발점으로 삼을 때 |
| `... --blank` | 빈 HTML | 에디터가 아닌 별도 화면을 만들 때 |

**판단 기준은 하나입니다. 에디터 화면에서 검증하는 작업이면 데모 베이스에서 출발합니다.** 기존 데모를 복제하는 것은 다른 사람이 만든 데모를 출발점으로 삼는 경우로 한정하십시오.

`--from` 은 화면뿐 아니라 동작 목록, 정책 설명, 카드 설명까지 함께 물려받습니다. 달라진 부분만 수정하면 됩니다.

인수 없이 실행하면 판단 기준과 복제 가능한 데모 목록이 표시됩니다.

```bash
bash new-demo.sh
```

### 데모를 고칠 때와 복제할 때

| 상황 | 방법 |
|---|---|
| 내가 만드는 데모를 다듬는 중 — 문구·버그·피드백 반영, 안 추가 | **그 데모를 그대로 고칩니다.** 링크를 이미 공유했더라도 마찬가지입니다 |
| **다른 사람이 만든 데모**를 출발점으로 내 데모를 만들려는 경우 | **복제합니다.** 그 사람의 데모를 건드리지 않기 위한 것입니다 |
| 주제가 다른 새 데모 | 데모 베이스에서 시작합니다 |

같은 안을 다듬는 과정에서 화면이 달라지는 것은 정상입니다. 데모 상단바에 **"커밋 xxxxxxx 기준"** 이 표시되므로, 보는 사람도 언제 시점의 화면인지 확인할 수 있습니다.

다른 사람의 데모를 출발점으로 삼을 때는 아래와 같이 복제합니다. 원본 데모와 링크는 그대로 유지됩니다.

```bash
cd demo
bash new-demo.sh photo-crop "AI 사진 자르기" --from other-demo --by "본인 이름"
```

### 안 비교(A/B)는 한 데모 안에서 합니다

**A안·B안을 비교하려고 데모를 복제하지 않습니다.** 한 데모 안에서 상단바로 전환합니다.

| 설정 위치 | 내용 |
|---|---|
| `demos/<데모이름>.js` 의 `controls` | 상단바 컨트롤. **자기 데모 파일에서 직접 선언합니다** |
| `actions[].group` | 동작을 묶는 단위. `'공통'` · `'A안'` · `'B안'` 처럼 나누면 정책·코드 화면에서도 그대로 구분됩니다 |

**필요한 컨트롤은 자기 데모 파일에서 조립합니다.** 공용 파일(`shell.js`)을 고칠 필요가 없습니다.

```js
controls: [
  { type: 'seg',    label: '안 선택', store: 'myMode', reload: true,
    options: [['off','끄기'], ['a','A안'], ['b','B안'], ['c','C안']] },
  { type: 'toggle', label: '자동 검색', store: 'myAuto', default: '1' },
  { type: 'select', label: '단계', store: 'myStep', options: [['s1','01 첫 화면']] },
  { type: 'button', label: '다시 보기', send: 'demo:replay' }
]
```

| 종류 | 화면에 보이는 것 | 개수 제한 |
|---|---|---|
| `seg` | 버튼 묶음 | 없음 (A/B/C… 몇 개든) |
| `select` | 드롭다운 | 없음 |
| `toggle` | 켜기 / 끄기 | — |
| `button` | 단일 버튼 | — |

동작 방식은 두 가지입니다.

| 항목 | 하는 일 |
|---|---|
| `store` | 고른 값을 저장합니다. 데모 화면 안 스크립트가 이 값을 읽어 동작을 바꿉니다 |
| `reload: true` | 값을 바꾼 뒤 화면을 새로고침합니다 |
| `send: '이벤트이름'` | 화면 안으로 신호를 보냅니다. 화면 스크립트에서 `document.addEventListener('이벤트이름', …)` 로 받습니다 |

항목 규격은 `assets/demo-shell/shell.js` 의 "컨트롤 C" 주석에 정리되어 있습니다.

**데모 베이스에는 단계 바로가기 껍데기(`'dev-jump'`)가 기본으로 붙어 있습니다.** 키트에서는 단계 목록이 비어 있어 비활성으로 보입니다. 여러 단계로 된 흐름을 만들었다면 `shell.js` 의 `DEV_STEPS` 에 단계를 채우면 동작합니다 — 고른 값을 `sessionStorage` 에 심고 화면을 새로고침하므로, 화면 쪽 스크립트가 그 값을 읽어 그 단계로 가게 만듭니다.

A/B 를 덧붙일 때는 단계 바로가기를 그대로 두고 배열에 함께 적습니다.

```js
controls: [
  'dev-jump',                                    // 단계 바로가기 유지
  { type: 'seg', label: '안 선택', store: 'myMode', reload: true,
    options: [['off','끄기'], ['a','A안'], ['b','B안']] },
  { type: 'button', label: '다시 보기', send: 'demo:replay' }
]
```

상단바에 이렇게 표시됩니다.

```
< 홈 | 내 데모     데브모드 [단계 바로가기… ▾]  안 선택 [끄기][A안][B안]  [다시 보기]   정책 보기 | 코드 보기
```

### 데모 베이스 수정 시 유의 사항

`base-editor.html` 은 앞으로 만드는 모든 데모의 출발점입니다. 이 파일을 수정하면 다음과 같이 반영됩니다.

- **이후에 만드는 데모**에만 반영됩니다
- **이미 만든 데모는 변경되지 않습니다.** 각 데모가 자체 화면 사본을 사용하기 때문이며, 공유된 링크의 화면이 갑자기 달라지지 않도록 의도한 구조입니다

따라서 데모 베이스에는 **확정된 사항만** 포함합니다. 에디터 재현 개선 사항 또는 온고잉이 확정된 기능이 해당하며, 검증 중인 안이나 특정 데모의 소재는 포함하지 않습니다.

수정한 경우 **첫 화면에 기록을 남기십시오.** 별도 공지 없이도 팀원이 사이트에서 확인할 수 있도록 하기 위한 것입니다. `index.html` 의 `BASE-INFO` 구간에 세 곳이 있습니다.

| 위치 | 작성 내용 |
|---|---|
| `<span class="last">` | 마지막 변경 날짜와 담당자 |
| 포함된 기능 묶음 | 확정되어 포함된 기능. 처음엔 `.base-none` 한 줄이고, 생기면 `<ul class="base-has base-rows">` 로 바꿔 `<li>` 를 추가합니다 |
| 기록 묶음 | 변경 기록. 처음엔 `.base-none` 한 줄이고, 생기면 `<ul class="base-log base-rows">` 로 바꿔 **맨 위에** `<li>` 를 추가합니다 (날짜 · 내용 · 담당자) |

`<li>` 모양은 `index.html` 의 BASE-INFO 주석에 적혀 있습니다. 기록을 남기지 않으면 배포 시 경고가 표시됩니다.

```
1-3) 데모 베이스 변경 기록
   base-editor.html 을 고쳤는데 첫 화면의 변경 기록은 그대로입니다
   → index.html 의 BASE-INFO 구간에 한 줄 적어주세요 (날짜 · 무엇이 · 누가)
```

### 데모 베이스 업데이트 절차

온고잉이 확정된 기능을 데모 베이스에 반영하는 작업입니다. 클로드에게 아래와 같이 요청하시면 됩니다.

```
○○ 기능이 온고잉으로 확정됐어. 데모 베이스에 반영해줘
```

각 단계에서 수행되는 작업은 다음과 같습니다.

| 단계 | 작업 내용 |
|---|---|
| 1 | 해당 기능의 코드를 데모에서 분리합니다. 비교용 다른 안(B안 등)과 데모 소재는 제외하고 확정된 부분만 가져옵니다 |
| 2 | 특정 데모에만 해당하는 전제를 제거합니다 (예: 특정 소재의 구조를 가정한 부분) |
| 3 | 데모 소재에 의존하지 않도록 정리합니다. 베이스가 기능을 제공하고, 각 데모가 자신의 상황을 전달하는 구조로 만듭니다 |
| 4 | `base-editor.html` 에 해당 파일을 추가합니다 |
| 5 | 베이스를 단독으로 열어 오류가 없는지 확인하고, 새 데모를 생성해 기능이 함께 적용되는지 검증합니다 |
| 6 | 첫 화면 `BASE-INFO` 에 기록을 남깁니다 |

기존 데모는 변경되지 않습니다. 각 데모가 자체 화면 사본을 사용하기 때문입니다.

**수정 전에 팀과 공유하십시오.** 이후 만드는 모든 데모에 적용되는 사항이므로, 무엇을 왜 확정했는지에 대한 합의가 필요합니다.

### AI 프레젠테이션 단계 자체를 바꾸는 데모

에디터 화면(`*-screen.html`)은 데모마다 사본이지만, 그 안에 뜨는 **AI 프레젠테이션 오버레이(`aip/` 폴더)는 모든 데모가 하나를 공유합니다.** 오버레이의 단계(홈·질문·내용 구성·디자인 선택·로딩)를 바꾸는 데모는 `aip/` 의 공용 파일을 고치지 않고 아래 방법으로 끼어듭니다.

| 단계 | 작업 내용 |
|---|---|
| 1 | 자기 화면 파일(`<데모이름>-screen.html`)에서 iframe 주소를 `aip/index.html?demo=<데모이름>` 으로 바꿉니다 (`const SRC = ...` 한 줄) |
| 2 | `aip/demos/<데모이름>/step.js` 와 `step.css` 를 만듭니다. 공용 진입 파일이 이 두 파일만 추가로 읽습니다 |
| 3 | `step.js` 안에서 바꿀 단계의 진입 함수를 덮어씁니다. 기존 부품(말풍선·팝오버 스타일·로딩 전환)은 그대로 씁니다 |
| 4 | 데이터가 필요하면 같은 폴더에 둡니다 |

`?demo=` 가 없는 다른 데모에는 아무 변화가 없습니다. 공용 파일(`aip/assets/...`)을 직접 고치면 모든 데모와 베이스 화면이 함께 바뀌므로 하지 않습니다.

### 다른 흐름(진입점)을 추가하는 스쿼드

AI 프레젠테이션은 AIP 스쿼드의 진입점입니다. 다른 스쿼드가 자기 흐름(여러 단계로 된 별도 화면)을 에디터 안에서 보여 주려면 이 오버레이를 고치지 않고 **자기 진입점을 따로 만듭니다.**

| 단계 | 작업 내용 |
|---|---|
| 1 | 띄울 화면을 `demo/` 안에 둡니다 (예: `demo/<흐름이름>/index.html`). 밖을 참조하면 다른 컴퓨터와 배포에서 빈 프레임이 됩니다 |
| 2 | 자기 화면 사본에서 진입 버튼(예: AI 도구 패널의 카드)을 추가하고, AI 프레젠테이션과 같은 방식(전체화면 iframe + 프레임 밖 닫기 버튼)으로 띄웁니다. `base-editor.html` 의 `openPptOverlay` 블록이 그대로 본보기입니다 |
| 3 | 임베드 여부에 따라 모양을 바꾸려면 **프레임 안 화면이** `window.self !== window.top` 으로 스스로 판단합니다 |
| 4 | 상단바 단계 바로가기를 쓰려면 `shell.js` 의 `DEV_STEPS` 에 자기 단계를 채우고, 화면 쪽에서 `sessionStorage` 값을 읽어 그 단계로 가게 합니다 |

그 진입점이 스쿼드 안에서 확정되면 데모 베이스에 반영합니다("데모 베이스 업데이트 절차").

### 파일 담당 구분

같은 파일을 두 사람이 동시에 수정하면 나중에 저장한 내용이 앞의 내용을 덮습니다. 아래와 같이 담당을 나누면 충돌하지 않습니다.

| 파일 | 담당 구분 |
|---|---|
| `demo/base-editor.html` | 데모 베이스 화면. 모든 새 데모의 출발점 — 수정 시 첫 화면에 기록 필요 |
| `demo/base.html`, `demos/base.js` | 데모 베이스를 상단바와 함께 표시하는 페이지 (`/base`) |
| `demo/<데모이름>-screen.html` | 각 데모의 화면 — 담당자별로 분리되어 충돌하지 않습니다 |
| `demo/aip/index.html`, `demo/aip/assets/` | AI 프레젠테이션 오버레이 공용 파일 — **한 사람만**. 단계를 바꾸는 데모는 `aip/demos/<데모이름>/` 에 둡니다 |
| `demo/assets/demo-shell/demos/<데모이름>.js` | 각 데모의 정보 파일 — 담당자별로 분리되어 충돌하지 않습니다 |
| `demo/assets/demo-shell/shell.js`, `shell.css`, `code.html` | 데모 허브 공용 UI — **한 사람만** |
| `demo/index.html` | 첫 화면. 카드 추가는 `new-demo.sh` 가 수행합니다 |
| `demo/assets/demo-shell/demo-data.js` | 데모 정보의 그릇과 조회 도우미 — 공용, **한 사람만** |
| `demo/new-demo.sh`, `demo/deploy.sh` | 생성·배포 스크립트 — 공용, **한 사람만** |
| `demo/tokens/` | 미리캔버스 디자인 토큰(MDS). 손으로 고치지 않습니다 |

GitHub 를 쓴다면 작업 시작 전에 `git status` 로 다른 사람이 수정 중인 파일이 있는지 확인하십시오.

### 첫 화면 카드 항목

첫 화면의 데모 카드에는 아래 항목이 표시됩니다. **데모를 만들 때 함께 입력하는 것이 원칙입니다.** 나중에 `index.html` 을 직접 수정하면 누락되기 쉽고, 여러 명이 같은 파일을 고쳐 충돌합니다.

| 항목 | 입력 방법 | 미입력 시 |
|---|---|---|
| 제목 | 생성 시 필수 | — |
| 데모 작업자 | `--by "이름"` | git 계정명이 들어갑니다 (실명으로 수정 필요) |
| 설명 | `--desc "한두 문장"` | `TODO` 로 표시됩니다 |
| 관련 문서 | `--doc "URL"` | `없음` |
| 진행 일자 | `--date "26.10"` | `—` |
| PM · PD · FE | `--pm` `--pd` `--fe "이름"` | `—` |

클로드에게 `새 데모 만들어줘` 라고 요청하면 위 항목을 물어봅니다. 항목 이름을 기억할 필요는 없습니다.

직접 실행하는 경우는 아래와 같습니다. **설명(`--desc`)은 필수**이며, 없으면 스크립트가 무엇을 넣어야 하는지 알려주고 중단합니다. 기존 데모를 복제하는 경우(`--from`)는 원본 설명을 물려받으므로 생략할 수 있습니다.

```bash
bash new-demo.sh photo-crop "AI 사진 자르기" \
  --desc "사진을 원하는 비율로 자르는 흐름을 확인한다" \
  --by "홍길동" --pm "김PM" --pd "홍길동" --fe "이FE" \
  --doc "https://miridih.atlassian.net/wiki/x/…" --date "26.10"
```

`--desc` 는 카드 설명과 데모 정보 파일의 정책 요약에 함께 반영됩니다. 생성이 끝나면 미입력 항목을 알려주므로, 확인 후 보완하십시오.

### 데모 작업자 표기

여러 명이 데모를 만들면 문의 대상이 드러나지 않습니다. 이를 위해 카드에 `데모 작업자` 항목을 둡니다.

| 항목 | 대상 |
|---|---|
| **데모 작업자** | 이 데모(프로토타입)를 제작한 사람 |
| PM · PD · FE | 해당 기능의 담당자 |

두 항목은 다를 수 있습니다. 카드에서는 설명 앞의 태그로 표시됩니다.

```html
<p class="desc"><span class="by">제작: 홍길동</span>설명 문장…</p>
```

생성 시 `--by "이름"` 으로 지정하십시오. 생략하면 git 계정명이 입력되며, 이 경우 스크립트가 경고를 표시합니다.

### 동작 변경 시 설명 갱신

데모마다 정보 파일이 하나씩 있습니다 — `demo/assets/demo-shell/demos/<데모이름>.js`. 동작 목록, 정책 설명, 파일 목록이 이 파일에 들어 있으며, 담당자별로 분리되어 있어 충돌하지 않습니다.

동작을 변경한 뒤 이 파일을 갱신하지 않으면 사이트의 "정책 보기"와 "코드 보기"에 이전 설명이 표시됩니다. 새 동작을 추가한 경우 `actions[]` 에 항목을 넣으십시오. 누락하면 상단바 "지금 동작", 정책 화면, 코드 화면 어디에도 표시되지 않습니다.

`actions[].find` 는 코드에서 해당 위치를 찾는 검색 문자열입니다. 줄 번호를 사용하지 않는 이유는 소스가 한 줄만 변경되어도 위치가 어긋나기 때문입니다.

### 상단바 "지금 동작"도 함께 채우십시오

동작을 추가했다면 `live` 도 채우기를 권합니다. 상단바에 **지금 화면에서 무슨 동작이 진행 중인지** 표시되고, 그 이름이 정책 화면·코드 화면과 같아서 **화면에서 본 것을 코드로 바로 찾아갈 수 있습니다.** 데모 허브를 만든 목적이 이것입니다.

```js
actions: [
  { group: '공통', name: '자동 검색', live: 'photo-panel', … }
],

live: [
  { see: '.panel[data-panel="사진"]', is: 'photo-panel' }   // 이 요소가 화면에 보이면
]
```

| 규칙 | 판정 방법 |
|---|---|
| `see: '선택자'` | 그 요소가 **화면에 실제로 보이면** (DOM 에 있어도 닫혀 있으면 아닙니다) |
| `cls: '클래스'` | `body` 에 그 클래스가 있으면 |
| `in: '#프레임'` | 중첩 프레임 안을 볼 때 함께 적습니다 (예: 오버레이 안) |
| `when: '선택자'` | 그 요소가 화면에 보일 때만 이 규칙을 판단합니다 (예: 오버레이가 열려 있을 때만) |
| `prop: '변수.경로'` | 화면 스크립트의 변수가 참이면 (예: `'__ed.selected'` — 요소가 선택된 상태) |
| `is` | `actions[].live` 와 같은 값이어야 합니다 |

**위에서부터 먼저 맞는 규칙**을 사용하므로, 좁은 조건을 위에 두십시오. 아무 규칙도 맞지 않으면 `idleLabel` 이 표시됩니다.

`live` 를 비워 두면 상단바에 "지금 동작"이 아예 표시되지 않습니다. 값이 바뀔 수 없는 글자를 띄우지 않기 위한 것입니다.

---

## 5부. 문제 해결

| 증상 | 조치 |
|---|---|
| 첫 화면 제목이 `{{SQUAD}}` 로 보임 | 초기 설정 전입니다. 0부를 따라 자리표시자를 채우십시오 |
| 에디터 화면이 깨져 보임 (글꼴·색이 다름) | `file://` 로 직접 열었거나 `demo/tokens/` 가 없는 경우입니다. 2-2 처럼 로컬 서버로 여십시오 |
| "AI 프레젠테이션" 카드를 누르면 AIP 화면이 뜸 | 정상입니다. AIP 스쿼드의 진입점이며, 다른 흐름을 띄우려면 4부 "다른 흐름(진입점)을 추가하는 스쿼드"를 보십시오 |
| 상단바 "데브모드" 드롭다운이 비활성 | 정상입니다. 단계 목록이 비어 있어서이며, `shell.js` 의 `DEV_STEPS` 에 채우면 동작합니다 |
| `deploy.sh` 가 0단계에서 멈춤 | 배포 설정 전입니다. 화면의 안내대로 템플릿을 복사해 채우고 설정 파일을 생성하십시오 (3-1) |
| 저장소가 열리지 않음 (404) | 초대를 받지 않았거나 수락하지 않은 상태입니다. 저장소 주인(`{{OWNER}}`)에게 요청하십시오 |
| 사이트가 열리지 않음 | 사내망 또는 VPN 연결을 확인하십시오. 외부망에서 접속되지 않는 것은 정상입니다 |
| 배포 시 토큰 오류 | 3일이 지나 만료된 경우입니다. `#axe-anything` 에서 `/mivault-cf-token` 으로 재발급하십시오 |
| 토큰 DM 을 확인하지 못한 경우 | `/mivault-cf-token` 으로 재발급합니다. 이전 값은 즉시 무효화됩니다 |
| "24시간에 5회" 메시지 표시 | 발급 한도에 도달한 상태입니다. `@devops.help` 에 한도 초기화를 요청하십시오 |
| 배포 후에도 이전 화면이 표시됨 | 강력 새로고침을 실행하십시오 (macOS `Cmd+Shift+R`, Windows `Ctrl+Shift+R`) |
| 기타 | 배포 관련은 `@devops.help`, 키트 자체는 `{{CONTACT}}` 에게 문의하십시오 |

---

## 참고 자료

| 구분 | 위치 |
|---|---|
| 키트 소개 (무엇이 들어 있는지 · 시작 5단계) | 키트 루트 `README.md` |
| 사내 배포 가이드 | 위키 「내가 만든 앱 직접 배포 하기」 |
| 토큰 발급 가이드 | 위키 「[사용자] Cloudflare 토큰 발급 사용자 가이드」 |
| 상단바 컨트롤 규격 | `demo/assets/demo-shell/shell.js` "컨트롤 C" 주석 |
| 데모 정보 파일 항목 뜻 | `demo/assets/demo-shell/demo-data.js` 맨 위 주석 |