Analyst
STEP 0: 시놉시스 사전 분석
원작의 강점과 장편 전환 보완점을 먼저 정리합니다. 이 결과는 이후 모든 단계의 기준 문서가 됩니다.
- 입력: `config.yaml`, 시놉시스, 선택 레퍼런스
- 점검: 구조, 영상적 묘사, 서브텍스트, 이미지 시스템, 캐릭터, 복선, 장편 호흡
- 출력: `output/step_00_critique.md`
GitHub repository based guide
시놉시스를 장편 영화 시나리오로 바꾸는 파일 기반 작업 매뉴얼
`sero12journey/synopsis-to-scenario`는 1~3페이지 시놉시스를 한국어 장편 영화 시나리오로 확장하기 위한 Claude Code 직접 실행형 멀티 에이전트 워크플로우입니다. 이 매뉴얼은 저장소의 README, CLAUDE.md, 프롬프트, 스크립트, 설계 문서를 바탕으로 실제 사용 순서대로 재구성했습니다.
4
Orchestrator, Analyst, Writer, Critic
0-8
분석부터 시각적 개고까지 9단계
A/B/C
사람 승인 체크포인트
70-85
90분 장편 기준 목표 씬 수
What it is
이 저장소는 웹앱이 아니라 실행 규칙과 프롬프트 묶음입니다
Python은 프로젝트 폴더 초기화와 `.docx` 변환 같은 보조 작업만 담당합니다. 실제 창작 워크플로우는 Claude Code가 프롬프트 파일과 이전 산출물을 읽고, 단계별 Markdown 결과물을 저장하는 방식으로 진행됩니다.
입력
시놉시스, 장르·톤·테마 설정, 선택 레퍼런스
↓
Orchestrator
실행 순서, 상태 저장, 체크포인트, 피드백 라우팅
Analyst
사전 분석, 막 구조, 비트시트
Writer
이미지 시스템, 인물, 트리트먼트, 씬 리스트, 초고
Critic
구조·시각성·체크포인트 리뷰, 시각적 개고
↓
출력
단계별 Markdown 산출물, 최종 시나리오 Markdown, 선택 `.docx` 변환본
Setup
설치와 프로젝트 초기화
저장소를 받은 뒤 프로젝트 이름으로 작업 폴더를 만들고, `config.yaml`과 `state.json`을 준비합니다.
1. 저장소 준비
로컬에 저장소를 둡니다
git clone https://github.com/sero12journey/synopsis-to-scenario.git
cd synopsis-to-scenario
2. 프로젝트 초기화
작품별 작업 폴더를 만듭니다
python scripts/init_project.py my-project실행 후 `projects/my-project/config.yaml`, `projects/my-project/state.json`, `input/`, `input/references/`, `output/` 폴더가 생성됩니다.
Inputs
입력 자료 준비
첫 실행 품질은 `config.yaml`의 명확성, 시놉시스 파일, 레퍼런스 배치에 크게 좌우됩니다.
`config.yaml`에 채울 항목
title: "작품 가제"
source_format: "webtoon"
target_duration: 90
genre: ["심리 스릴러", "미스터리"]
tone: "로맨스에서 스릴러로 전환"
theme_direction: "믿음이 집착으로 변하는 순간"
synopsis_file: "synopsis.md"
reference_files: ["screenplay_theory.md"]파일 배치
- `projects/my-project/input/synopsis.md`에 1~3페이지 시놉시스를 둡니다.
- 작법 레퍼런스가 있으면 `input/references/`에 둡니다.
- 저장소에 포함되지 않은 선택 파일 `prompts/writer/step_07_examples.md`가 있으면 초고 문체 기준점으로 사용할 수 있습니다.
- 상업적 사용은 라이선스 조건을 먼저 확인합니다.
실제 설정 파일명은 `config_schema.yaml`을 기준으로 맞춥니다.
설계/가이드 일부에서는 `synopsis_doc`, `reference_docs` 같은 이름도 보이지만, 현재 템플릿은 `synopsis_file`, `reference_files`를 사용합니다.
Workflow
0단계부터 8단계까지 진행하기
각 단계는 이전 산출물을 읽고 다음 산출물을 만듭니다. 버튼을 눌러 단계별 목적, 입력, 결과물을 확인하세요.
Analyst
STEP 1: 막 구조와 러닝타임 설계
90분 장편을 기준으로 3막 구조와 씬 수 분포를 설계합니다.
- 입력: STEP 0 사전 분석
- 기준: 한국 시나리오는 페이지보다 씬 수가 1차 지표
- 출력: `output/step_01_act_structure.md`
Analyst
STEP 2: 비트시트
Blake Snyder 기반 15비트 구조로 사건, 전환점, 미드포인트, 결말 이미지를 배치합니다.
- 입력: STEP 0, STEP 1
- 이후: 체크포인트 A에서 구조 확정 여부를 판단
- 출력: `output/step_02_beat_sheet.md`
Writer
STEP 3: 이미지 시스템 설계
반복 이미지, 공간 메타포, 시각적 모티프를 설계해 영화적 일관성을 만듭니다.
- 입력: STEP 0~2
- 원칙: 관객이 의식하면 설교가 되므로 상징은 잠재적으로 작동해야 함
- 출력: `output/step_03_image_system.md`
Writer
STEP 4: 인물 재설계
인물의 시각적 식별자, 행동적 소개, 능동성, 입체적 적대자를 정리합니다.
- 입력: STEP 0~3
- 이후: 체크포인트 B에서 이미지 전략과 인물을 확정
- 출력: `output/step_04_characters.md`
Writer
STEP 5: 트리트먼트
구조와 인물을 15~20페이지 분량의 산문형 설계도로 확장합니다.
- 입력: STEP 0~4 전체
- 주의: 이후 초고에서 임의 삭제하지 않을 장면 설계도
- 출력: `output/step_05_treatment.md`
Writer
STEP 6: 씬 리스트
트리트먼트를 70~85개 씬으로 분해해 막별 집필 가능한 청사진으로 만듭니다.
- 입력: STEP 5, STEP 3, STEP 4
- 이후: 체크포인트 C에서 초고 전 최종 검토
- 출력: `output/step_06_scene_list.md`
Writer
STEP 7: 시나리오 1고
한 번에 전체를 쓰지 않고 막 1, 막 2a, 막 2b, 막 3으로 나눠 씁니다.
- 입력: 트리트먼트, 씬 리스트, 이미지 시스템, 캐릭터
- 중간 점검: 각 막 집필 뒤 사용자 승인 또는 수정 요청
- 출력: `act1`, `act2a`, `act2b`, `act3`, `step_07_first_draft_full.md`
Critic → Writer
STEP 8: 시각적 개고
Critic이 1고를 진단한 뒤 Writer가 진단 결과를 반영해 최종본을 만듭니다.
- 입력: 1고 합본, 이미지 시스템, STEP 0 사전 분석
- 기준: 보이는 것만 쓰기, 설명 과다 제거, 이미지 일관성
- 출력: `output/final_screenplay.md`
STEP 5/6은 프롬프트 파일명을 기준으로 실행하세요.
README와 프롬프트 파일은 `STEP 5 트리트먼트`, `STEP 6 씬 리스트` 순서입니다. 현재 `state_schema.json`의 일부 name 라벨은 이 순서와 다르게 보일 수 있습니다.
Human gates
체크포인트에서 사람이 결정합니다
Critic은 리뷰를 제공하지만, 최종 승인·수정·중단 결정은 사용자가 합니다. Writer가 자기 결과물을 평가하지 않도록 역할을 분리한 것이 이 저장소의 핵심 설계입니다.
| 체크포인트 | 위치 | 검토 내용 | 사용자 선택 |
|---|---|---|---|
| A 구조 확정 | STEP 2 이후 | 막 균형, 미드포인트, 주인공 능동성, 15비트 완성도, STEP 0 보완점 반영 | 승인, 수정 요청, 중단 |
| B 비주얼/인물 확정 | STEP 4 이후 | 이미지 시스템, 캐릭터 식별자, 적대자 입체성, 공간/모티프 전략 | 승인, 수정 요청, 중단 |
| C 초고 전 최종 리뷰 | STEP 6 이후 | 트리트먼트, 씬 리스트, 씬 수, 구조-장면 대응, 초고 진입 가능성 | 승인, 수정 요청, 중단 |
체크포인트에서 사용할 답변 예시
승인합니다. STEP 3으로 진행해주세요.수정 요청입니다.
STEP 1에서 2막 후반의 씬 수를 줄이고,
STEP 2에서 주인공이 직접 선택하는 비트를 하나 더 강화해주세요.Resume and revise
재개와 수정 요청
진행 상태는 `projects/{name}/state.json`에 저장됩니다. 새 세션에서는 CLAUDE.md와 state.json을 읽고 이어서 진행합니다.
이어하기
새 Claude Code 세션에서
워크플로우 이어서 진행해 주세요.
프로젝트는 projects/my-project 입니다.Orchestrator는 `state.json`의 `current_step`을 기준으로 이어서 진행합니다.
수정 요청
수정은 캐스케이딩됩니다
체크포인트에서 STEP N을 수정하면 N을 다시 실행하고, 그 다음 단계부터 체크포인트 직전까지 다시 생성한 뒤 리뷰를 재실행합니다. 저장소 기준 최대 수정 횟수는 체크포인트당 3회입니다.
Export
최종 시나리오를 `.docx`로 변환
최종 Markdown이 `projects/my-project/output/final_screenplay.md`에 생성되면, 보조 스크립트로 Word 문서로 변환할 수 있습니다.
필요 패키지 설치
pip install python-docx변환 실행
python scripts/md_to_docx.py projects/my-project/output/final_screenplay.md출력 파일명을 직접 지정하려면 두 번째 인자를 추가합니다.
Troubleshooting
자주 막히는 지점
이 프로젝트는 자동 CLI 앱이 아니라 파일과 프롬프트를 읽는 작업 방식이므로, 경로와 상태 파일을 명확히 유지해야 합니다.
프로젝트가 이미 존재
초기화 스크립트가 중단됩니다
같은 이름의 `projects/{name}` 폴더가 있으면 덮어쓰지 않습니다. 새 이름을 쓰거나 기존 폴더를 확인하세요.
시놉시스를 못 찾음
파일명과 위치를 맞춥니다
`config.yaml`의 `synopsis_file` 값과 `projects/{name}/input/` 안의 실제 파일명이 일치해야 합니다.
단계 순서 혼동
프롬프트 파일명을 기준으로 봅니다
`step_05_treatment.md`, `step_06_scene_list.md` 순서로 진행합니다.
초고 품질 저하
STEP 7을 한 번에 쓰지 않습니다
막별 분할 집필과 사용자 점검을 유지해야 장면 밀도와 맥락 손실을 줄일 수 있습니다.
`.docx` 변환 실패
`python-docx`를 설치합니다
스크립트가 ImportError를 내면 `pip install python-docx` 후 다시 실행합니다.
상업적 이용
라이선스를 먼저 확인합니다
저장소는 CC BY-NC-SA 4.0로 배포됩니다. 생성된 시나리오 권리는 사용자에게 귀속된다고 README에 명시되어 있습니다.
출처와 확인한 파일
- GitHub: sero12journey/synopsis-to-scenario
- `README.md` — 전체 목적, 아키텍처, Quick Start, 라이선스
- `CLAUDE.md` — Claude Code 실행 규칙과 재개 방식
- `prompts/orchestrator.md` — 단계 실행, 체크포인트, 캐스케이딩 규칙
- `prompts/config_schema.yaml` — 실제 프로젝트 설정 필드
- `scripts/init_project.py`, `scripts/md_to_docx.py` — 초기화와 Word 변환 동작
- `docs/02-design`, `docs/03-analysis`, `docs/04-report` — 설계 결정, 갭 분석, 완료 리포트