비디오 제작 워크플로우

이것은 이 저장소에서 새 비디오를 위한 단일 제작 워크플로우입니다. video-director가 최종 결과와 상태를 소유합니다. 리서치 및 작성 기술은 .claude/skills/viral-tech-video-creator/SKILL.md를, 샷, 모션, 사운드 참조는 .claude/skills/video-shotcraft/SKILL.md를 사용하세요. 해당 리소스가 이 파일과 충돌할 경우 이 파일을 따릅니다. 작업 전에 CLAUDE.md와 선택된 참조를 읽으세요. 응답은 베트남어로, 코드는 영어로 작성하세요.

워크플로우는 완전 자동입니다: 에이전트가 스스로 생산, 검토, 승인을 수행하며, 어떤 단계도 사용자의 수동 승인을 기다리지 않습니다. 절대 "들이보세요 / 확인해주세요 / 괜찮나요"와 같은 표현으로 턴을 끝내지 마세요; 최선의 옵션을 선택하고, 결정을 docs/<vid>/에 기록한 후 계속 진행하세요. 중요한 입력이 누락되어 안전하게 유추할 수 없거나, 사용자가 명시적으로 결정 게이트를 요청한 경우에만 사용자에게 질문하세요. 인간 청취(오디오, 최종 MP4)는 선택적 기록이며, 질문이나 차단 요소가 아닙니다. 독립적인 검토자는 깨끗한 컨텍스트를 사용합니다. 사용자가 필수라고 표시한 부분만 그대로 두고, 나머지는 스토리를 위해 각색하거나 다시 작성할 수 있습니다(일반적인 실패 지점의 게이트-A 교훈 참조). 게시에는 별도의 사용자 요청이 필요합니다.

라이트 모드. 짧은 story 비디오 또는 사용자가 스크립트/음성을 제공한 경우, 디렉터는 게이트를 제거하지 않고 단계를 병합할 수 있습니다: research-agent 1개 (사용자 계정이 출처인 경우 리서치 파일 없음), 3개의 Phase 3 분기를 하나의 병렬 메시지로, task-planner와 3-4개 샷당 1개의 scene-agent로 구성합니다. 게이트 A, D, E, B, C, 콘텐츠 및 오디오 브랜치 검토, 수정 루프 규율 및 파일 소유권은 항상 유지됩니다.

파이프라인 맵

게이트 A 이후 작업은 세 개의 병렬 브랜치(콘텐츠, 오디오, 디자인)로 분기되며, 각 브랜치는 자체 생산자 → 깨끗한 컨텍스트 검토자 루프를 가집니다. 세 브랜치가 모두 통과하면 video-director가 이를 결합하고 게이트 E가 결합된 계획을 검토한 후 빌드합니다.

flowchart TD
  P0["0 인테이크<br/>intake-agent ×2-3"] --> P1["1 리서치<br/>research-agent ×N"]
  P1 --> P2["2 스크립트<br/>script-agent"]
  P2 --> A{"게이트 A ≥ 9<br/>script-reviewer"}
  A -- "수정 (≤3회)" --> P2
  A -- 통과 --> FORK(("분기"))

  subgraph BR["3 · 세 개의 병렬 브랜치"]
    direction LR
    subgraph B1["3a 콘텐츠"]
      CA["content-agent<br/>content-pack.md"] --> CR{"content-reviewer ≥ 9"}
      CR -- 수정 --> CA
    end
    subgraph B2["3b 오디오"]
      VA["voice-agent + audio-agent<br/>sN.mp3, BGM/SFX, 믹스 계획"] --> AR{"audio-reviewer ≥ 9"}
      AR -- 수정 --> VA
    end
    subgraph B3["3c 디자인"]
      DA["design-agent<br/>프로토, 스타일 프레임, 커버, 보드"] --> DR{"게이트 D ≥ 9<br/>design-reviewer"}
      DR -- 수정 --> DA
    end
  end

  FORK --> CA
  FORK --> VA
  FORK --> DA
  CR -- 통과 --> J
  AR -- 통과 --> J
  DR -- 통과 --> J
  J["4 결합<br/>video-director: voice.json, timeline.ts,<br/>타이밍 / 텍스트 / 무드 조정"] --> E{"게이트 E ≥ 9<br/>integration-reviewer"}
  E -- "티켓 → 소유 브랜치" --> BR
  E -- 통과 --> P6["6 태스크<br/>task-planner"]
  J -.->|"조기 스캐폴드"| P7
  P6 --> B{"게이트 B ≥ 8<br/>task-reviewer"}
  B -- 통과 --> P7["7 빌드<br/>scene-agent ×N"]
  P7 --> P8["8 QA<br/>qa-agent ×N"]
  P8 --> P9["9 렌더<br/>render-agent"]
  P9 --> C{"게이트 C ≥ 8 · 최종 장벽<br/>MP4 전체 재테스트<br/>final-check.md 모두 ✓ + video-reviewer ×3"}
  C -- "수정 → 소유자, 재렌더, 모든 것 재테스트" --> P7
  C -- 통과 --> P10["10 전달<br/>video-director"]

텍스트 폴백: 0 인테이크 → 1 리서치 → 2 스크립트 ⇒ A → 분기[ 3a content-agent ⇒ content-reviewer | 3b 음성+오디오 ⇒ audio-reviewer | 3c design-agent ⇒ D ] → 4 결합 → E → 6 태스크 ⇒ B → 7 빌드 → 8 QA → 9 렌더 ⇒ C → 10 전달.

계약 및 명명 규칙

비디오는 고유한 소문자 케밥 케이스 주제 ID <vid>, 음성 슬러그 <voice>, docs/<vid>/, src/<vid>/, public/audio/<vid>/, out/qa/<vid>-*.png를 가집니다.
유일한 최종 비디오는 out/<vid>-<voice>-reel.mp4입니다. 예: out/cam-on-phien-ban-minh-anh-khoi-reel.mp4. 음성 슬러그는 실제로 들리는 음성을 설명합니다. 음성이 변경되면 렌더링 전에 python3 -I scripts/pipeline.py voice <vid> <new-voice>를 실행하세요; 이전 파일은 계속 사용 가능합니다.
python3 -m unittest scripts.test_voice_catalog로 시작하여 카탈로그 미리보기가 해결되는지 확인하세요. vietnamese-voice-samples/previews/ (폴더가 카탈로그이며, 파일명은 축약된 음성 이름)에서 카탈로그 설명과 사용자 요청에 따라 후보를 선택하고, 제공자와 그 음성 ID를 brief.md에 기록하세요. 미리보기 자체로는 상업적 또는 복제 권한이 부여되지 않습니다.
Phase 0 중복 주제 확인 후, 한 번 초기화합니다: python3 -I scripts/pipeline.py init <vid> --comp <CompId> --voice <voice> --profile story|product|knowledge|news. 새로운 제작에는 --voice가 필수입니다: 최선의 추측을 전달한 후, 경로가 결정되는 즉시 pipeline.py voice <vid> <slug>를 실행하세요(슬러그는 실제로 들리는 음성을 지정해야 함); --out은 레거시 출력 이름 전용입니다. 생산 에이전트를 디스패치하기 전에 포트 4180에서 파이프라인 모니터를 시작하거나 재사용하세요. status.json을 수동으로 편집하지 마세요.
각 작업 단계마다 pipeline.py set <vid> <stage> in_progress를 호출한 다음 done, blocked 또는 failed를 호출하세요. 스테이지는 research, brief, script, content, voice, design, build, audio, qa, render입니다(content는 init이 생성하는 워크플로우 v3부터 존재합니다; 게이트 A만 검토된 진행 중인 v2 비디오는 pipeline.py upgrade <vid>로 v3로 이동). render 명령은 자체 스테이지를 업데이트합니다. 검토 게이트는 A → [content · audio · D] → E → B → C 순서로 실행됩니다; 두 브랜치 검토는 게이트처럼 기록되며(review <vid> content|audio …, gate <vid> content|audio, 한도 3에서 override), 게이트 E는 콘텐츠, 오디오, D가 모두 승인될 때까지 거부합니다. 게이트 A, 콘텐츠, 오디오, D, E는 9/10에서 통과하고, B와 C는 8에서 통과합니다(pipeline.py가 점수를 적용함).
에이전트 활동 (모니터 구동). video-director가 에이전트를 디스패치할 때마다, pipeline.py agent <vid> <agent-name> running --stage <stage> --note "<task>"를 실행하고; 완료 알림이 도착하면 pipeline.py agent <vid> <agent-name> done(또는 failed)을 실행하세요. 병렬 복사본은 번호가 매겨진 이름(scene-agent-1, research-agent-2)을 사용합니다. 이 기록이 없으면 모니터는 스테이지 상태로만 추측할 수 있으며, 검토자는 절대 활성화되지 않습니다. 게이트는 점수가 임계값을 충족하고 열린 Cao/Trung 티켓이 없는 경우에만 통과합니다(수정 루프 규율 참조); pipeline.py는 티켓을 볼 수 없으므로 검토자는 하나라도 열려 있으면 --verdict revise를 설정합니다.

단계	설정할 스테이지	게이트 / 체크포인트
0 인테이크	— (init)	—
1 리서치	`research`	—
2 스크립트	`brief`, `script`	A
3a 콘텐츠 브랜치	`content`	review `content` (`content-reviewer`)
3b 오디오 브랜치	`voice`, `audio`	review `audio` (`audio-reviewer`, 머신 판정)
3c 디자인 브랜치	`design`	D
4 결합	— (디렉터 통합)	—
5 통합	(소유 스테이지가 수정 시 재개)	E
6 태스크	`build` → in_progress	B
7 빌드	`build`, `audio` (믹스 통합)	—
8 QA	`qa`	—
9 렌더	`render` (자동)	C (인간 청취 = 선택적 기록)

스테이지 재개(in_progress/blocked/failed)는 다음에서 검토를 무효화합니다: research/brief/script → A (및 두 브랜치 검토), content → review content + E 이후, voice → review audio + E 이후, design → D 이후, build/audio/qa/render → C. 새 검토 항목도 그 이후의 모든 것을 무효화합니다(브랜치 검토가 E, B, C를 다시 엽니다). 무효화된 모든 게이트를 순서대로 다시 실행하세요.

다른 비디오는 고유한 ID, 오디오 폴더, QA 접두사 및 출력을 사용할 때 동시에 실행할 수 있습니다. 한 비디오에서 작업하는 에이전트는 분리된 씬 파일을 소유합니다; video-director만 kit, timeline, Reel, Root 및 음성 JSON을 편집합니다. 파이프라인은 하나의 상태와 하나의 출력 이름에 대한 쓰기를 직렬화합니다.

에이전트 명단 및 핸드오프

video-director는 파이프라인 소유자이자 정보 관리자입니다: 상태를 초기화하고, 현재 브리프/스크립트/소스 결정을 단일 진실 공급원으로 유지하며, 프로필을 선택하고, 파일을 할당하며, 작업을 통합하고, 게이트 명령을 실행하고, 결과를 전달합니다. 각 전문가에게 승인된 브리프, 정확한 입력, 예상 출력 경로 및 승인 확인을 제공하세요. 핸드오프 시 video-director는 반환된 아티팩트를 해당 입력에 대해 확인하고, 결정 또는 해결되지 않은 질문을 docs/<vid>/에 기록하고, 상태를 업데이트하고, 다음 전문가에게 승인된 버전만 제공합니다. 검토자는 깨끗한 컨텍스트를 가져야 하며 자신이 점수를 매길 아티팩트를 생산한 에이전트가 아니어야 합니다. video-director는 자체 작업에 점수를 매기지 않습니다.

video-director는 메인 대화 스레드(당신)이며, 하위 에이전트가 아닙니다. 아래의 모든 에이전트를 관리합니다: 디스패치, 승인된 입력 전달, 수정 라우팅, 공유 파일 통합, 상태/게이트 기록, 사용자와 대화. 각 단계는 자체 이름의 에이전트가 실행합니다; 검토자 에이전트는 별개이며, 깨끗한 컨텍스트를 가지며, 각 라운드마다 새로 생성됩니다.

단계	생산자 에이전트	검토자 에이전트 (게이트)	소유 및 반환
0 인테이크	`intake-agent` (읽기 전용)	—	중복 주제 보고서, 사전 점검 결과; 디렉터가 `brief.md` 헤더를 작성; 중요한 입력이 누락된 경우에만 사용자에게 질문
1 리서치	`research-agent` (소스 그룹별 × N)	—	`research.md` 또는 `research-<group>.md`: 소스, 대상 언어, 사실/추론/미지, 5개의 후크 후보
2 스크립트	`script-agent`	`script-reviewer` (A)	`brief.md`, `script.md`, `voice.proposed.json` / `script-review.md`
3a 콘텐츠	`content-agent`	`content-reviewer` (브랜치)	`content-pack.md`: 샷별 화면 텍스트, 캡션 청크, 악센트 단어, 커버/재후크/CTA 텍스트, 주장→소스 표, `minh hoạ` 레이블 / `content-pack-review.md`
3b 오디오	`voice-agent` + `audio-agent`	`audio-reviewer` (브랜치, 머신 판정)	`sN.mp3` + 지속 시간 + ASR (`voice-report.md`); BGM/SFX + 비트 그리드 + 믹스 계획 + `assets-manifest.md` / `audio-review.md`
3c 디자인	`design-agent`	`design-reviewer` (D)	`design-spec.md` + 프로토타입 + 3개의 스타일 프레임 + 커버 + 스토리보드 + 후크 모션 스트립 / `design-review.md`
4 결합	`video-director`	—	`voice.json`, `timeline.ts` 초안, `docs/<vid>/join-notes.md` (타이밍/텍스트/무드 조정)
5 통합	(수정은 소유 브랜치 생산자에게 전달)	`integration-reviewer` (E)	`integration-review.md`, 전체 빌드 전에 판단
6 태스크	`task-planner`	`task-reviewer` (B)	`task-review.md`: 도구, 샷→파일 소유권, 종속성, 검사
7 빌드	`scene-agent-1..N` (병렬, 각 파일 하나씩)	—	`src/<vid>/scenes*.tsx` + 스틸; 디렉터가 `timeline`/`kit`/`Reel`/`Root`/오디오 통합
8 QA	`qa-agent`	—	`qa-report.md`: tsc, 결정론, 프레임/전환/캡션 검사, 샷별 디자인 충실도 점수, 수정을 소유자에게 라우팅
9 렌더	`render-agent`	`video-reviewer` (C, 최종 장벽)	검증된 MP4 + `final-check.md` (MP4에 대한 전체 회귀 테스트) + `render-evidence.md` (연락처 시트, 조밀 프레임, 음량, ASR) / `video-review.md`
10 전달	`video-director`	— (인간 청취 = 선택적 기록)	디렉터가 `check`를 실행하고 전달 보고서 작성

video-director만 공유 kit, timeline, Reel, Root 및 voice.json을 작성합니다; 전문가들은 핸드오프 시 해당 파일에 변경 사항을 제안합니다. 씬 에이전트는 비디오의 SHOTS 맵에서 지속 시간을 읽고 모션을 측정된 음성 범위에 고정합니다. 두 에이전트에게 동일한 쓰기 가능 파일을 할당하지 마세요. 사용자가 작업을 중지하면 백그라운드 에이전트도 중지하세요. 게이트 C는 연락처 시트, 조밀 프레임, ffprobe/음량 데이터 및 ASR에 대한 AI 검토입니다; C 이후의 인간 청취(pipeline.py listen)는 선택적 기록이며 전달 차단 요소가 아닙니다.

속도 규칙: 기본적으로 병렬 디스패치

video-director는 작업이 허용하는 한 많은 하위 에이전트를 병렬로 디스패치하여 비디오가 가능한 한 빠르고 잘 완료되도록 해야 합니다. 함께 실행할 수 있는 단계를 순차적으로 실행하는 것은 결함입니다.

모든 독립적인 에이전트 호출을 하나의 메시지(하나의 도구 블록)로 보내고, 절대 턴당 하나씩 보내지 마세요.
입력이 승인되고 쓰기 가능한 파일이 겹치지 않을 때 병렬화: research-agent × N (소스 그룹당 하나); 세 개의 Phase 3 브랜치(content-agent, voice-agent + audio-agent, design-agent) 함께; scene-agent × N (각각 하나의 파일과 하나의 샷 ID 목록); qa-agent는 샷 클러스터로 분할; 워크플로우/스킬/문서 수정은 비디오 작업과 병행; 독립적인 수정은 동일한 라운드에서 다른 소유자에게 라우팅.
독립적인 단계는 병렬로 실행 (단계 맵):
- Phase 0: intake-agent 검사(중복 주제, 도구 사전 점검, 음성 카탈로그 테스트)를 하나의 메시지로; Phase 1: 모든 research-agent 소스 그룹.
- Phase 3: A 통과 직후 세 브랜치 생산자를 하나의 메시지로. 각 브랜치는 자체 생산자 → 자체 검토자 루프를 독립적으로 반복: 통과한 브랜치는 결합 지점에서 대기하는 반면 다른 브랜치는 계속 수정; 브랜치는 절대 다른 브랜치의 검토를 기다리지 않음.
- Phase 5-6: task-planner가 계획을 초안하고 scene-agent가 E 검토 중 조기 스캐폴드를 빌드; B 검토는 E 통과를 기다림(E가 무언가 변경하면 계획이 변경됨).
- Phase 7: scene-agent × N이 분리된 파일에서; Phase 8: 샷 클러스터 및 스틸 프레임 렌더당 qa-agent; Phase 9: 연락처 시트, 조밀 프레임, 음량 및 ASR 증거가 동시에 계산됨.
- 수정 라운드: 다른 소유자에 대한 티켓은 하나의 메시지로 전송. 검토는 동시에 실행될 수 있지만, 디렉터는 점수를 기록하고 엄격히 A → D → E → B → C 순서로 gate를 실행하며(pipeline.py가 적용), 이전 게이트가 재개되면 이후 검토자의 결과는 무효화됨.
실제 종속성이 있는 경우에만 순차적으로 유지: 게이트 A → D → E → B → C (검토자는 완성된 아티팩트가 필요함), 이전 검토에 의존하는 수정 라운드, 단일 소유자가 있는 모든 파일(kit, timeline, Reel …).

핸드오프 규칙

완전한 컨텍스트 제공: 승인된 브리프, 정확한 입력 파일, 예상 출력 경로, 승인 확인.
아티팩트 확인: video-director는 반환 시 입력과 출력을 확인하고, 결정을 기록하며, 다음에 승인된 버전만 전달.
깨끗한 검토자: 검토자는 자신이 점수를 매길 아티팩트를 생산한 에이전트와 같은 컨텍스트를 절대 공유하지 않음.
파일 소유권: 각 파일은 정확히 한 명의 소유자를 가짐. 공유 파일은 video-director만 수정하고 전문가들은 제안만 함.
버전 관리: 각 아티팩트의 버전을 추적하고, 수정 시 업데이트.

수정 루프 규율

모든 검토에서 발견된 문제는 Cao (치명적, 차단) 또는 Trung (중요) 티켓으로 생성됩니다. Thấp (사소한) 티켓은 기록되지만 차단하지는 않습니다.
티켓이 있는 게이트는 --verdict revise로만 통과할 수 있으며, 검토자는 pipeline.py에 점수와 함께 티켓 상태를 전달합니다.
티켓은 소유자에게 라우팅되며, 소유자는 수정 후 티켓을 닫습니다.
하나의 브랜치에 대한 수정 라운드는 최대 3회로 제한됩니다. 3회 후에도 해결되지 않으면 video-director가 개입하여 결정합니다.
수정이 완료되면 해당 게이트가 재개되고 모든 후속 게이트가 무효화됩니다 (이전 규칙 참조).

일반적인 실패 지점

게이트 우회: 검토 없이 다음 단계로 넘어가면 품질이 저하됩니다. 모든 게이트를 통과하세요.
불완전한 컨텍스트: 하위 에이전트에 승인된 브리프와 승인 확인을 제공하지 않으면 방향을 잃습니다. 항상 완전한 컨텍스트를 전달하세요.
수동 승인 요청: 사용자가 요청하지 않는 한 차단 결정을 위해 사용자에게 되돌리지 마세요. 최선의 결정을 내리고 기록하세요.
파일 경로 오류: 항상 <vid>, <voice>, <stage>를 올바르게 사용하세요. 경로를 하드코딩하지 마세요.
게이트 A 교훈: 사용자가 필수라고 표시한 대사만 그대로 유지하세요. 나머지는 스토리에 맞게 각색하거나 다시 작성할 수 있습니다. 게이트 A는 창의성을 억압하지 않고 스토리 일관성을 검토합니다.
병렬화 실패: 독립적인 단계를 순차적으로 실행하면 속도가 크게 저하됩니다. 항상 가능한 한 병렬화하세요.

시작

사용자의 아이디어나 소스 자료를 수신합니다.
intake-agent를 실행하여 중복 주제를 확인하고 도구를 사전 점검합니다.
research-agent를 디스패치하여 배경 정보를 수집합니다.
script-agent가 스크립트를 작성하고 script-reviewer가 게이트 A에서 검토합니다.
게이트 A 통과 후 콘텐츠, 오디오, 디자인 브랜치를 병렬로 시작합니다.
모든 브랜치가 통과하면 video-director가 결합하고 게이트 E에서 검토합니다.
task-planner가 태스크를 계획하고 task-reviewer가 게이트 B에서 검토합니다.
scene-agent가 씬을 빌드하고 qa-agent가 QA를 수행합니다.
render-agent가 최종 MP4를 렌더링하고 video-reviewer가 게이트 C에서 검토합니다.
video-director가 최종 MP4를 전달합니다.

nanxnguyen/remotion-ai-agentic-studio

remotion-ai-agentic-studio란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서