---
name: short-video-workflow
description: 주제와 언어로 14단계 짧은 영상 제작을 시작하거나 기존 제작을 재개·수정한다. 담당 역할·단계 결과·네 사용자 검토·실제 미디어의 준비 상태를 연결한다.
---

# 짧은 영상 제작 진행

## 시작 또는 재개

[공통 계약](../../../docs/workflow-contracts.md)에서 입력·저장·상태·네 검토·수정 규칙을 읽고 [제작 지침](../../../docs/short-video-guide.md)의 단계별 사용 표와 검토 메모를 확인한다. 새 제작에는 [진행 양식](../../../templates/project.json)과 [검토 양식](../../../templates/review.md)을 사용한다. [연결 예제](../../../examples/water-cycle/README.md)는 양식 설명이며 실제 파일·승인이 있는 제작 기록이 아니다.

새 제작은 `topic`, `language`를 받는다. 공백·누락은 보완하고 언어 이름·코드를 확인해 보존한다. 주제 안에서 각도를 고르며 언어를 한국어로 고정하지 않는다. 저장소에서 유일한 소문자 영숫자·하이픈 project_id를 정해 `projects/<project_id>/project.json`을 만든다. 같은 주제의 새 제작은 새 ID다. 내부 지침·검토 설명은 한국어이고 대본·제목·내레이션·자막은 입력 언어다.

재개 요청이면 기존 project_id 또는 사용자가 가리킨 기록을 찾고 brief·현재 버전·승인·참조·실제 파일을 확인한다. 찾을 수 없거나 여러 후보가 있으면 대상 기록을 확인한다. 새 요청으로 해석해 기존 기록을 덮어쓰지 않는다. 가장 앞선 미해결 작업부터 이어가며 동일한 유효 승인 버전에는 다시 승인을 요구하지 않는다.

## 담당 배정과 전달

총괄인 video-coordinator만 공유 진행·현재 포인터·승인을 기록한다. 아래 역할의 `.codex/agents/<name>.toml`을 읽고 단계·새 revision·사용할 선행 버전을 배정한다. 담당 역할을 사용할 수 없으면 그 지침에 따라 순서대로 작업하고 역할별 책임을 유지한다. 병렬 실행 프로그램이나 잠금 장치를 만들지 않는다.

| 담당 | 단계와 스킬 |
|---|---|
| topic-researcher | 01 short-video-topic, 02 short-video-research |
| story-writer | 03 short-video-script, 04 short-video-title |
| narration-designer | 05 short-video-tts-split, 06 short-video-tts |
| scene-director | 07 short-video-cuts, 08 short-video-scenes, 09 short-video-entities |
| visual-designer | 10 short-video-references, 11 short-video-images |
| video-editor | 12 short-video-motion, 13 short-video-compose |
| video-reviewer | 14 short-video-review |

담당 스킬은 같은 skills 폴더의 `<스킬 이름>/SKILL.md`를 읽는다. 필요한 선행 자료·승인은 공통 계약의 단계 표에 따른다. 스킬 직접 호출도 이 경계를 유지한다. 같은 단계·버전의 작성자는 하나다. 담당은 자기 artifact.json·review.md를 제출하고 총괄이 형식·참조·완료 근거와 문제를 확인한 뒤 project.json에 반영한다.

각 결과는 `projects/<project_id>/stages/<stage_id>/r<revision>/artifact.json`과 같은 위치의 review.md다. 이전 버전은 보존한다. inputs에는 실제 사용한 같은 제작물의 선행 버전을 기록하고 JSON 데이터 경로는 저장소 루트 기준으로 쓴다. review.md의 문서 링크는 실제 위치에 맞춘다. 담당 단계의 제작 지침 적용·결과와 적용하지 않은 구성의 이유만 요약하며 모든 단계에서 같은 전체 메모를 반복하지 않는다.

## 네 곳에서 사용자 결정을 기다린다

1. 01 후보·선택·범위의 topic 검토를 요청한다. 실제 사용자 승인 전 02를 시작하지 않는다.
2. 02 근거와 03 대본·04 제목의 story 검토를 요청한다. 제목·첫 문장의 약속과 결말, 블록 연결·주장·비유의 한계를 제시한다. 승인 전 05를 시작하지 않는다.
3. 검증된 실제 음성으로 07을 준비하고 08·09를 같은 묶음으로 완성해 scenes 검토를 요청한다. 실측 구간·상태 변화·연결·고정 특징과 주석 근거, 08 preview의 실제 대표 화면·짧은 움직임을 제시한다. 대표 샘플의 교육용 3D 품질을 같은 scenes 검토에서 확인한다. 승인 전에는 이 제한된 샘플만 허용하며 정식 10–12 전체 제작을 시작하지 않는다.
4. 실제 13 완성본과 14 검수 보고의 final 검토를 요청한다. 승인 전 제작 완료를 선언하지 않는다.

검토한 stage_id·revision은 artifact_refs에 고정하고 실제 사용자 응답을 feedback에 기록한다. 응답이 없으면 pending 결정과 awaiting_review 상태로 기다린다. 담당의 선택 제안·검수자의 pass를 사용자 승인으로 만들지 않는다. 변경 요청은 수정할 단계와 새 버전을 배정한다.

## 실제 미디어가 없는 경우

새 양식·결과는 계약 1.1이며 새 프로젝트 settings.visual_engine은 Blender다. 06은 기존 qwen3-tts 환경의 Qwen3-TTS, 10–12는 승인된 저장소 내 Blender 실행 경로, 13은 기존 Remotion + FFmpeg 합성 경로를 사용한다. 기존 1.0 결과·승인·WAV를 보존하고 유효한 선행 버전으로 참조한다. 전역 환경 재설치·무단 도구 대체를 하지 않고 설치 확인과 실제 실행 성공을 구분한다.

result=null 또는 필수 실제 자료 부재는 awaiting_input이다. 다음 담당에게 필수 파일이 준비됐다고 보고하지 않는다. 결과 제출 시 요청 ID·선행 버전·모든 항목·파일 존재·형식·실측 메타데이터를 확인한다. 부분 제출은 보존하지만 전 단계 완료가 아니다. 실패는 원인과 blocking 여부를 issues에 기록하고 failed로 보고한다.

세로 9:16, 최종 180000ms 이내, 각 컷 0ms 초과 5000ms 이하를 확인한다. 원본 references/1.png를 보존하고 단순 형태·정돈된 색을 교육용 3D로 해석한다. 단순 배경·부드러운 조명·선명한 형태를 사용하며 평면 복제와 캠핑 소재·인물·상표를 강제하지 않는다. 07은 실제 통합 음성을 0부터 끝까지 덮고 자막은 별도로 정렬한다. 예상 시간·가상 경로는 실제 확인 근거가 아니다. 음성 길이 초과는 대본 수정과 story 재승인으로 돌린다.

## 변경과 완료

수정은 새 버전을 만들고 inputs로 영향을 받는 후속 결과·검토만 stale 처리한다. 승인 경계가 열리면 새 후속 작업 전 해당 버전의 재승인을 받는다. 제목만 바뀌면 13·14와 story/final을 재확인하고 기존 05–12의 음성·장면·이미지는 보존한다. 언어 변경은 언어 의존 결과와 후속 작업을 재검토한다.

최종 검수자는 실제 완성본의 story/visual/audio/captions/timing/consistency를 확인하고 checks.evidence에 실제 근거를 기록한다. 미검수는 not_checked이며 완성본 부재는 incomplete다. 모든 영역 pass·blocking 없음이어야 pass를 추천할 수 있다. 총괄은 유효한 결과·파일·시간·네 사용자 승인을 확인한 뒤에만 제작 완료를 선언한다.