STORYPACK GUIDE01 / 15

No-code mindset · Code-assisted making

내 이야기를
스토리팩으로

사이트를 새로 만드는 대신, 이미 작동하는 무대에 내 대본과 미리 준비한 이미지를 넣는 방법을 배웁니다.

대상 코딩이 처음인 누구나 도구 Claude Code 중심 결과 나만의 대화형 이야기

The one sentence

사이트는 극장,
스토리팩은 한 편의 공연 상자입니다.

01 / THEATER

사이트 본체

입장 화면, 채팅창, 서버처럼 모든 작품이 함께 쓰는 극장 시설입니다.

02 / SHOW BOX

스토리팩

대본, 배우 설정, 배경, 음악, 결말을 작품별로 모아 둔 독립 패키지입니다.

03 / ASSISTANT

Claude Code

규칙을 먼저 읽고, 여러분의 지시대로 공연 상자를 복사·수정·검사하는 작업 도우미입니다.

가장 중요한 구분

새 이야기를 만들 때는 극장을 공사하지 않습니다. 스토리팩만 새로 만듭니다.

Website anatomy

관객에게 보이는 곳과
뒤에서 일하는 곳

01 · BROWSER

화면 · 프론트엔드

작품 목록, 시작 버튼, 채팅, 이미지와 소리를 보여주는 객석입니다.

02 · SERVER

서버 · 백스테이지

스토리팩을 읽고 AI에게 질문하며 결과를 화면으로 보내는 조정실입니다.

03 · STORYPACK

콘텐츠 · 공연 상자

작품의 세계관, 캐릭터, 4개 챕터, 결말, 모든 에셋이 들어 있습니다.

04 · MEMORY

세션 · 진행 기록

어떤 선택을 했는지, 관계와 위험 수치가 얼마인지 기억합니다.

!
여러분이 주로 만질 곳은 03, 스토리팩뿐입니다.

화면과 서버는 모든 작품이 공유하므로, 초보 작업에서는 보호 구역으로 둡니다.

One turn, backstage

관객이 한마디 하면
뒤에서는 여섯 단계가 움직입니다.

01작품 선택

목록에서 스토리팩을 고릅니다.

02세션 생성

서버가 이번 관객의 진행 기록을 만듭니다.

03현재 장 읽기

세계관과 지금 필요한 챕터만 불러옵니다.

04AI 연출

GM이 상황을 판단하고 NPC가 답합니다.

05화면 연기

미리 준비한 배경·캐릭터·소리를 꺼냅니다.

06선택 기억

용기·신뢰·위험 같은 상태값을 저장합니다.

0
플레이 중에는 이미지를 새로 생성하지 않습니다.

속도가 빠르고, 비용이 예측 가능하며, 캐릭터 얼굴과 미술 스타일이 장면마다 흔들리지 않습니다.

Hierarchy, made simple

하이어라키는 어려운 말이 아니라
상자 안의 상자 순서입니다.

CATALOG전체 작품 목록
packs.json
ONE PACK한 작품 폴더
red_riding_hood
DEPARTMENTS대본 · 설정 · 에셋
FILES챕터 · 인물 · 이미지
DETAILS대사 · 선택 · 상태값
MATCH RULE 01

이름표가 같아야 합니다.

폴더명, manifest.id, 전체 목록의 ID가 정확히 같아야 작품이 나타납니다.

MATCH RULE 02

참조한 소품이 실제로 있어야 합니다.

대본이 bg_forest를 부르면 그 이름의 이미지가 에셋 창고에 있어야 합니다.

Storypack folder map

빨간 모자 샘플팩을
열어 보면 이렇게 생겼습니다.

red_riding_hood/
├─ manifest.json       작품의 이름표·출연진·결말
├─ poster.webp         목록에 보이는 포스터
├─ CLAUDE.md           Claude Code용 시작 안내
├─ AGENTS.md           반드시 지킬 작업 규칙
├─ prompts/
│  ├─ system/           🔴 출력 계약, 수정 금지
│  └─ content/          🟢 내 이야기
│     └─ story/         4챕터·분기·결말
└─ resources/
   ├─ backgrounds/      배경
   ├─ characters/       캐릭터
   ├─ scenes/ endings/  장면·결말 컷
   ├─ music/ effects/   BGM·효과음
   └─ resource_list.json  에셋 제작 주문서
폴더 자유 편집 잠금 미디어
manifest.json콜시트와 작품 표지. 제목, 소개, 출연진, AI 모델, 엔딩 조건을 한눈에 정리합니다.
prompts/content작가실. 오프닝, 세계관, 캐릭터 바이블, 챕터와 선택지를 씁니다.
prompts/system송출 규격. AI의 답을 사이트가 읽을 수 있는 형태로 맞추므로 초보자는 수정하지 않습니다.
resources미술·음향 창고. 플레이 전에 만든 이미지와 소리만 넣습니다.
AGENTS / CLAUDE제작 수칙. Claude Code가 작업 범위와 금지사항을 이해하도록 돕습니다.

Inside the script room

이야기는 한 덩어리가 아니라
역할별 문서로 나눕니다.

OPENING

00_opening

첫 화면에서 무엇을 보여주고 누가 먼저 말할지 정합니다.

WORLD BIBLE

01 · 02

세계의 규칙과 등장인물의 성격·말투·관계를 정합니다.

STORY ARC

overview + chapter 1–4

전체 목표를 세우고 4막으로 나눠 사건과 선택을 배치합니다.

BRANCHING

clues_system

무엇을 발견하면 어떤 수치와 플래그가 바뀌는지 적습니다.

A
좋은 분기는 “다른 대사”보다 “다른 상태 변화”가 먼저입니다.

예: 지름길을 택하면 danger +2, 함께 준비하면 teamwork +1. 이 값이 마지막 엔딩을 고릅니다.

CHOICE관객의 선택
STATE용기 +1
위험 +2
STORY다음 장면의 반응
ENDING조건에 맞는 결말

Assets are prepared props

에셋은 무대 뒤에
미리 준비해 둔 소품입니다.

4배경 이미지
3캐릭터 이미지
4장면 컷
4엔딩 이미지
0현재 BGM·효과음
ORDER SHEET

resource_list.json

어떤 배경·캐릭터·소리가 필요한지 설명과 생성 프롬프트를 적는 제작 주문서입니다.

WAREHOUSE

실제 파일

webp 이미지와 mp3 소리를 각 폴더에 넣습니다. 이름은 주문서와 같아야 합니다.

CALL SHEET

04_resources.txt

AI 연출자에게 “지금 사용할 수 있는 소품 이름”만 알려주는 목록입니다.

주문서 → 실제 파일 → 사용 가능 목록, 세 곳의 이름이 일치해야 빈 화면이나 무음이 생기지 않습니다.

Claude Code is a production assistant

Claude Code는 알아서 만드는 마법이 아니라
수칙을 읽고 일하는 작업 도우미입니다.

YOU · STORY OWNER

사람이 정할 것

주제, 사람들이 느꼈으면 하는 경험, 주인공의 목표, 갈등, 중요한 선택, 원하는 결말의 의미를 정합니다.

CLAUDE · PRODUCTION ASSISTANT

Claude가 맡을 것

규칙 읽기, 템플릿 복사, 파일별 초안 작성, 이름 맞추기, 오류 검사와 수정 보고를 맡습니다.

1
첫 지시는 “만들어”가 아니라 “읽고, 계획만 보여줘”입니다.

Claude가 현재 구조와 보호 구역을 먼저 이해하면 사이트 본체를 잘못 고칠 가능성이 크게 줄어듭니다.

GOOD BRIEF

결과와 경계를 함께 말하기

  • 새 팩 ID와 한 줄 콘셉트
  • 4챕터와 3~4개 엔딩
  • src와 prompts/system은 수정 금지
  • 검증 결과까지 보고
RISKY BRIEF

“알아서 멋지게”만 말하기

  • 어떤 파일을 바꿀지 불명확
  • 기존 샘플을 덮어쓸 수 있음
  • 이미지 생성 비용을 바로 쓸 수 있음
  • 검사 없이 끝났다고 할 수 있음

Five sentences before files

파일을 열기 전에
이 다섯 문장만 완성하세요.

  1. 01플레이어는 누구인가?
  2. 02플레이어가 이번 이야기에서 얻고 싶은 것은?
  3. 03그것을 가로막는 인물·상황·시간 제한은?
  4. 04서로 다른 전략을 보여주는 세 가지 선택은?
  5. 05선택의 누적이 만드는 세 가지 이상 결말은?
EXAMPLE · RED RIDING HOOD

“할머니 댁에 무사히 도착해야 한다.”

플레이어는 빨간 모자다. 늑대와 숲의 갈림길이 방해한다. 준비·용기·협력·위험이 선택마다 바뀐다. 그 누적값이 현명한 귀환, 용감한 즉흥 대응, 지름길의 대가 같은 결말을 만든다.

이 다섯 문장이 분명하면 Claude는 파일을 잘 나눌 수 있습니다. 불분명하면 파일은 많아져도 이야기는 흐려집니다.

Prompt 01 · Inspect, then plan

Claude Code를 열면
이 프롬프트부터 붙여 넣습니다.

이 저장소에서 새 스토리팩을 만들고 싶어. 먼저 루트의 CLAUDE.md, public/game-packs/AGENTS.md, public/game-packs/red_riding_hood/AGENTS.md와 STORYPACK_SPEC.md를 읽어줘. 아직 어떤 파일도 수정하지 말고 다음만 보고해줘. 1. 사이트 본체와 스토리팩의 차이 2. 새 이야기를 만들 때 수정할 파일과 수정하면 안 되는 파일 3. docs/pack-template을 이용한 제작 순서 4. 내게 먼저 물어봐야 할 이야기 기획 질문 5개 기존 red_riding_hood 샘플과 src 폴더는 보존해줘.
CHECK 01

“아직 수정하지 말고”

첫 대화는 구조 확인과 계획에만 사용합니다.

CHECK 02

정본 파일을 지목

Claude가 추측하지 않고 실제 규칙을 읽게 합니다.

CHECK 03

보존 대상을 명시

샘플과 사이트 본체를 안전하게 지킵니다.

Prompt 02 · Build inside the guardrails

기획 답변 뒤에는
작업 범위를 정확히 잠급니다.

이제 새 스토리팩을 만들어줘. 팩 ID: night_train 한 줄 콘셉트: 막차에서 사라진 승객의 기억을 추적하는 미스터리 플레이어: 은퇴를 앞둔 열차 차장 핵심 상태값: trust, observation, time_left, danger 원하는 구조: 4챕터, 서로 다른 전략 3개, 엔딩 4개 작업 규칙: - docs/pack-template을 public/game-packs/night_train으로 복사할 것 - prompts/content와 필요한 manifest 필드만 이야기 내용에 맞게 수정할 것 - src/**와 prompts/system/**는 수정하지 말 것 - 이미지는 생성하지 말고 resource_list.json에 제작 계획만 작성할 것 - 기존 파일은 덮어쓰지 말 것 - 마지막에 packs.json에 등록하고 validate-pack을 실행할 것 - 변경 파일과 검사 결과를 쉬운 한국어로 보고할 것

예시의 팩 ID·콘셉트·플레이어·상태값만 여러분의 이야기로 바꾸면 됩니다. 팩 ID는 영문 소문자와 밑줄만 사용합니다.

Traffic-light safety model

모든 파일이 같은 위험도를
가진 것은 아닙니다.

초록 · 자유롭게

  • prompts/content/**
  • 세계관·인물·챕터·분기
  • resource_list.json의 제작 계획
  • 제목·소개·태그·엔딩 설명

노랑 · 검사와 함께

  • packs.json 작품 등록
  • 실제 이미지·음악 파일 배치
  • AI 모델과 토큰 설정
  • 수정 후 반드시 검증기 실행

빨강 · 멈추기

  • src/** 사이트 본체
  • prompts/system/** 출력 계약
  • 실제 API 키를 공개 폴더·문서에 입력
  • 승인 없이 유료 생성·기존 에셋 덮어쓰기

Validation before celebration

“파일을 만들었다”와
“작동한다”는 다릅니다.

새로 만든 night_train 스토리팩을 점검해줘. 1. node scripts/validate-pack.mjs night_train 실행 2. ERROR가 있으면 원인을 쉬운 말로 설명하고 팩 폴더 안에서만 수정 3. pack ID, 등장인물 이름, 상태 변수, 엔딩 조건, 리소스 ID가 서로 일치하는지 확인 4. ERROR가 0이 되면 무엇이 검증됐고 무엇은 실제 플레이로 확인해야 하는지 구분해 보고 src/**와 prompts/system/**는 수정하지 마.
✓
목록에 작품이 보이나?packs.json 등록과 ID 일치 확인
✓
캐릭터가 맞게 나오나?인물 이름과 파일명·프로필 확인
✓
4개 챕터가 이어지나?진행 범위와 전환 조건 확인
✓
선택이 결말에 닿나?상태 변수 철자와 엔딩 조건 확인
✓
빈 화면·무음이 없나?리소스 ID와 실제 파일 확인
✓
실제 플레이를 했나?검증기는 구조, 플레이는 경험을 검사

The finish line

코딩을 많이 아는 것이 목표가 아닙니다.
이야기를 작은 상자로 잘 나누고, Claude에게 경계와 검사를 함께 지시하는 것이 목표입니다.

01 · IMAGINE

다섯 문장으로 기획

플레이어, 욕망, 장애물, 선택, 결말을 먼저 정합니다.

02 · DELEGATE

규칙을 읽힌 뒤 제작

계획을 확인하고 스토리팩 안에서만 파일을 만들게 합니다.

03 · VERIFY

검증하고 직접 플레이

ERROR 0을 확인한 뒤, 사람이 이야기의 재미와 흐름을 판단합니다.

기억할 경로 public/game-packs/내_이야기 기억할 명령 node scripts/validate-pack.mjs 내_이야기
01 / 15