구술 조립 파이프라인 (v3 hub, 0715-01 조립 + v3/v4 반복 기반)

본 파일은 조립 프로세스 hub입니다: 프로세스 골격과 라우팅만 포함하며, 세부 규칙은 references/ 각 파일에 있습니다 (77개 비교 차이의 정착 지점, 2026-07-16 심층 비교 검토 후 확정).

§0 환경 준비 확인 (매번 호출될 때 먼저 이 섹션을 실행하고, 통과한 후에 아래로 진행)

본 skill의 규칙을 적용하려면 베이스가 있는 Remotion 프로젝트가 필요합니다. 사용자에게 설명을 인쇄하여 직접 처리하도록 지시하지 말고, 아래 검사를 직접 실행하고 부족한 것을 보충하십시오.

검사 순서 (항목별로 실행, 모두 녹색이어야 작업 시작)

# 1) 기본 런타임
node -v && ffmpeg -version | head -1
# 2) 현재 디렉토리가 Remotion 프로젝트인지 확인
[ -f package.json ] && grep -q '"remotion"' package.json && echo "OK: remotion 프로젝트"
# 3) 베이스가 모두 있는지 확인 (하나라도 없으면 불완전)
ls src/design/tokens.ts src/design/motion.ts src/koubo/scenes/shared.tsx \
 scripts/render-service.cjs scripts/qc-master.mjs 2>/dev/null

세 가지 결과 처리

결과	작업
모두 녹색	조용히 통과, 사용자에게 환경 상황을 보고하지 말고, 바로 조립 프로세스로 진입
프로젝트 있음, 베이스 부족	자동으로 설치, 묻지 말기 (setup이 이미 Remotion 프로젝트임을 감지하면 skill/스크립트/베이스만 보충하고 코드를 덮어쓰지 않음):macOS/Linux: `bash <(curl -fsSL https://raw.githubusercontent.com/jincheng2026/jc-remotion-skills/master/setup.sh) .`Windows (PowerShell): `irm https://raw.githubusercontent.com/jincheng2026/jc-remotion-skills/master/setup.ps1
프로젝트 없음	한 번 물어보고 설치 (`npm install`은 3-5분 소요, 용량이 크므로 무거운 작업에 속하므로 사용자 디렉토리 확인 필요):「먼저 Remotion 프로젝트를 생성해야 합니다 (의존성 설치 약 3-5분). 어디에 생성할까요? 기본값은 `./remotion-koubo-studio` 입니다」답변을 받은 후: macOS/Linux는 위의 setup.sh에 `<디렉토리>` 매개변수 추가; Windows는 `node <저장소>/setup.mjs <디렉토리>`
node / ffmpeg 부족	자동으로 설치할 수 있으면 자동으로 설치하고, 명령을 사용자에게 넘기지 마십시오 (대부분의 환경에서 시스템 패키지 관리자로 이 두 가지를 설치하는 데 관리자 권한이 필요하지 않음):① macOS에 brew 있음 (`command -v brew`) → 한마디 알림 「X가 부족합니다. brew로 설치하겠습니다. 약 몇 분 소요됩니다.」 후 직접 `brew install <부족한 것만>` 설치 후 이 섹션 다시 실행② Windows에 winget 있음 → `winget install OpenJS.NodeJS Gyan.FFmpeg`③ Linux는 먼저 `sudo -n true` 시도: 비밀번호 없이 가능하면 `sudo apt install -y nodejs ffmpeg`; 비밀번호가 필요하면 명령을 사용자에게 전달하여 실행하도록 함④ 모두 불가능 (예: Mac에 Homebrew 없음) → 공식 Homebrew 설치 명령을 하나 제공하여 사용자가 터미널에 붙여넣도록 함 (비밀번호 한 번 입력 필요), 설치 완료 후 사용자에게 알리도록 하고 이 섹션 다시 실행

규율

처음 호출될 때만 실행; 동일 세션 내에서 이미 통과했으면 다시 확인하지 않음.
모두 녹색일 때 침묵 유지 — 사용자가 원하는 것은 영상 편집이지 환경 보고서가 아닙니다. 설치가 필요한 경우에만 말을 꺼냅니다.
보충 설치/새로 생성 후 반드시 다시 한 번 검사를 실행하여 모두 녹색인지 확인하고 프로세스로 진입합니다.
사용자가 명시적으로 「검사 건너뛰기」 또는 「환경에 문제없다는 것을 알고 있습니다」라고 말하면 사용자를 존중하고 직접 작업을 시작합니다.

§0.1 작업 시작 전 필독 관문 (계획을 세우기 전에 실행, §0 환경 검사와 동등한 수준: 통과하지 않으면 아래로 진행 불가)

본 파일은 라우팅 hub일 뿐, 내용이 아닙니다. 아래 표는 진정한 출처 목록입니다 — 조립 계획표를 작성하기 전에 하나씩 모두 읽어야 하며, 「필요할 때 참조」가 아닙니다.

필독	담당
design-system `references/motion.md`	모션 효과 어휘 (숫자 롤링 / 판결문 떨어뜨리기 / 선 성장 / 퇴장 / 깨끗한 화면), 매끄러움 다섯 가지 법칙
design-system `references/typography.md`	T 계층 폰트 계층, 공백 대역, 주역 문자 비율
design-system `references/layout.md`	3구역 좌표, 인수 메커니즘, 안전 프레임
design-system `references/specs.md`	컴포넌트 사양표, 모션 효과 수치표
assembly `references/subtitle.md`	자막 끊어 읽기, 이중 언어 규범, 검증 게이트
assembly `references/rhythm.md`	비트 밀도, 퇴장 규율, 밀도 곡선
assembly `references/narrative.md`	사이드 레이블 시스템, 다섯 가지 에너지 노드, 판결문 승격
assembly `references/selection.md`	문장 유형 → 단락 유형 → 컴포넌트 대조표
design-system `references/infographic.md`	비유 시각화, 차트 선택 (데이터/프로세스/비교 구간이 있을 때 필독)

왜 이 관문을 세웠는가 (2026-07-27, 0727-01 전복 근본 원인 제1계층): 그 버전은 본 hub + tokens.ts + 기존 Scene 파일 하나만 읽고 작업을 시작했으며, 위 9개 진정한 출처는 하나도 읽지 않았습니다. 결과는 전체 모션 효과 어휘가 「페이드 인」 하나만 남았습니다 — 숫자는 롤링되지 않고, 판결문은 떨어지지 않으며, 대부분의 구간에 퇴장이 없고, 장 사이에 깨끗한 화면이 없습니다. 이 모든 것이 motion.md에 명백히 기록되어 있었습니다.

두 가지 부수 규율:

기존 Scene 파일을 사용하여 규범을 역추론하는 것을 금지합니다. 하나의 장면은 그것이 사용한 규칙의 일부만 반영하며, 빠진 것은 정확히 그것이 사용하지 않은 부분입니다 — 0727-01은 0724-01의 Scene02를 템플릿으로 사용했는데, 해당 장면에는 우연히 숫자 롤링과 Stamp가 없었습니다. 그래서 전체 영상에 없었습니다.
계획표의 각 단락은 반드시 규칙 항목 번호를 써야 합니다 (§2 2단계 참조). 「motion §7 / narrative §3」과 같은 항목 번호를 쓸 수 없으면 읽지 않은 것이므로, 돌려보내 다시 읽게 합니다.

§0.2 Studio 실시간 미리보기 기본 활성화 (「루트 A」, 2026-07-28 사용자 결정)

반복 확인의 기본 수단은 Remotion Studio 핫 리로드이며, 정적 프레임을 렌더링하여 다시 보는 것이 아닙니다 — 「한 곳 수정 → 프레임 렌더링 → 이미지 읽기」의 사이클은 게이트 검수용으로만 남깁니다.

작업 시작 즉시 미리보기 실행: 환경 검사 통과 후 기본적으로 Studio를 시작하고 본 영상 합성을 사용자에게 보여줍니다 (Claude Code: 미리보기 패널에서 저장소 루트 .claude/launch.json의 remotion-studio 실행; 일반 호스트: npm run dev 후 사용자에게 http://localhost:3000/Koubo-<영상명>을 열도록 요청). 메인 컴포넌트에는 기본 거친 편집(OffthreadVideo)이 포함되어 있어, Studio에서 바로 완전한 합성(구술+MG+자막+SFX 동시 화면)을 볼 수 있으며, 사용자는 언제든지 재생하고 타임라인을 드래그할 수 있습니다.
반복 작업은 핫 리로드로 진행: 코드 수정 후 초 단위로 자동 새로고침되며, 글꼴 크기/위치/색상/텍스트 등의 조정은 사용자가 미리보기에서 직접 보고 결정합니다. 프레임 렌더링(render-service stills/segment)은 세 가지 게이트 증거, mg-judge 입력 및 전달 검수에만 사용됩니다 — 게이트 및 제출 규칙은 모두 변경되지 않습니다 (제출 시 여전히 음향 효과 구간 포함 완성본; 모션 효과 자체 점검은 여전히 직접 연속 화면을 봐야 하며, §2.5 5단계).
파라미터 조정 패널: 새 영상의 메인 컴포넌트는 scaffold-koubo.mjs에 의해 자동으로 zod 스키마(qc / subZhSize / subBottom / sfxGain; 끝에 출력되는 Root 등록 코드 조각에는 이미 schema+defaultProps 포함)를 생성합니다. InfoScrim을 연결할 때는 src/koubo/Koubo072701.tsx를 참조하여 scrimStrength도 함께 스키마에 연결하고, 나머지 파라미터는 영상에 따라 추가/삭제합니다. 철칙: 스키마 기본값은 항상 tokens/현행 결정값과 동일하며, 출력은 기본값을 사용합니다 — 패널은 탐색 계층일 뿐 진정한 출처가 아니며, 최종 확정 값은 해당 진정한 출처에 다시 기록합니다 (글꼴 크기/하단 간격 → tokens.ts; 볼륨 레벨 → sfx §4.4 프로세스). 기본값이 아닌 값을 defaultProps에 남겨두는 것을 금지합니다. Root의 defaultProps가 token 변수를 참조하여 Studio에서 「Can't save default props」 오류가 발생하는 것은 의도된 설계입니다 (tokens를 우회하여 값을 저장하는 경로를 차단). 수정하지 마십시오. zod 버전은 Remotion 요구 사항에 따라 고정됩니다 (4.0.489 ↔ zod 4.3.6, Studio 시작 시 version mismatch 경고가 바로 검증입니다).
실시간 재생 시 프레임 드롭은 브라우저 실시간 합성의 정상적인 현상입니다: 모션 감을 판단하기 위해 0.5x 속도로 재생하거나 구간 렌더링으로 확인합니다. Studio를 켠 상태에서 렌더링을 시작할 때 직렬 처리 규율은 변경되지 않습니다 (#23 동시 교착 상태 + 예상 위험 구역 「Studio+still 동시 충돌」). 프로세스가 「0% CPU 조용히 멈춤」 상태가 되면 먼저 iCloud 제거를 확인합니다 (오답 #25 및 그 node_modules 변형).

시스템 반복 원칙 (사용자 2026-07-16 결정: skill은 지속적으로 반복하고, 지속적으로 기준과 품질을 높여야 함)

래칫은 앞으로만, 뒤로는 없음: 사용자가 결정한 기준 (사양 값, 거부 항목, 배음 문법)은 바닥이지 천장이 아닙니다 — 이후 단락은 그 위에 더 추가할 수만 있으며, 「이전에도 그랬으니까」라는 이유로 현상 유지를 금지합니다.
각 단락마다 반드시 침전: 단락 통과 = 최소한 하나의 마이그레이션 가능한 why를 해당 블록 파일에 추가; 전복 = 오답 사례로 등록 (증상 → 수정 방법 위치); 사용자의 한마디 「안 돼/간신히」 = 개선 방향 기록 (예: 음향 효과 「간신히 괜찮다」 → 상용 패키지로 업그레이드 대기).
각 영상마다 반드시 회고: 새 비디오 조립 전에 먼저 오답 집합과 각 블록의 「부정적 사례」를 훑어보고, 새 영상의 시작점이 이전 영상의 종료점 기준과 동일한지 확인합니다.
질감 벤치마크는 상한선 없음: 현재 기준 영상은 기준선일 뿐 종착점이 아닙니다; 더 높은 수준의 참고 자료를 발견하면 언제든지 단어급 비교법을 사용하여 사양표에 흡수합니다.

규칙 충돌 판결 순서 (두 규칙이 충돌할 때 이 순서대로 자체 판결, 기록 후 사용자 확인 대기)

사용자 결정 > 하드 제약 (3구역/점유표/게이트 제어/밝은 화면 맨 글자 금지) > 의미론적 정렬 (말하는 대로 나오기) > 밀도 리듬 기준 > 미적 선호도. 알려진 판결 사례: 정렬이 깨끗한 화면보다 우선 (rhythm 1), 차트 설명 앵커는 퇴장 규율 면제 (rhythm 4, 대고사 검증 대기), 플래시 열거는 case 자료 의무를 트리거하지 않음 (broll 6). 새로운 충돌은 순서대로 자체 판결하고 계획에 명시적으로 기록하며, 조용히 하나를 선택하는 것을 금지합니다.

메인 세션 규율 (0722-01 전체 프로세스 회고 가드레일, 2026-07-24 제정; 자세한 내용은 my-video/docs/0722-01-전체프로세스함정회고-20260723.md 참조)

하룻밤에 세 번 재작업, 기계 두 번 멈춤. 근본 문제는 실행이 아니라 판단과 정렬입니다. 네 가지 철칙:

기존 방안 채택 / 값을 하드코딩하기 전에 먼저 「적용 조건」을 명확히 씁니다. skill의 기본 출력 (예: gbro 조립 애니메이션의 느린 공개)은 자신의 맥락에서만 성립하며, 호스트 내용에 자동으로 적응하지 않습니다 — 밀집된 구술에서 느린 공개 = 화면이 항상 박자에 늦습니다 (A1, 8개 비디오 폐기). 하나의 숫자가 전체 배치를 관리한다 = 기본적으로 모든 항목이 동형이라고 가정하지만, 일반적으로 동형이 아닙니다 (A2 「인물 점유 높이 45-60%」 일률적 적용으로 전신 원경 실패). 사양은 「어떤 상황에서 어떤 단계를 사용할지」를 써야 하며 (예: 객체 기반 은유 45-60% / 인물 기반 은유 근경 65-80%), 하나의 단계만 쓰지 않습니다.
사용자의 조건문은 명령문이 아닙니다. 「X만 있으면 Y」는 제약 조건을 제공하는 것이지 X를 요구하는 것이 아닙니다 (A3: 사용자가 「전체 화면 B-roll만 인물을 사라지게 함」 = 인물은 기본적으로 사라지지 않음, 나는 「B-roll을 전체 화면으로 만듦」으로 읽었고, 심야 재작업 1.5시간). 모호한 용어 (「화면을 움직이게 함」 = 카메라 움직임 vs 요소 움직임)는 먼저 다시 물어 정렬한 후 구현하는 것이 추측하는 것보다 훨씬 저렴합니다.
검증은 「테스트했는데 문제없음」과 「전혀 테스트하지 않음」을 구분할 수 있어야 합니다. QC 「위반 제로」는 먼저 프로브 적용 범위를 확인합니다 (오답 #35); 긴 작업 모니터링은 작업 전용 신호 (해당 작업 자체의 세션/산출물/프로세스 PID)를 주시하고, 전체를 주시하지 마십시오 — 0722-01의 세 번 모니터링 오보는 모두 잘못된 신호를 주시했기 때문입니다 (사용자가 병렬로 실행하는 커버 작업을 주시하거나, 「파일이 얼마나 오래 변경되지 않았는지」로 생사를 판단했지만 Codex는 충분히 모아서 배치로 디스크에 씀); 하드 레드라인 (가짜 글자/로고/워터마크 없음)은 메인 세션이 독립적으로 확대 재검증해야 하며, 하위 에이전트의 자체 점검 구술을 신뢰하지 않습니다 (C5: 07번 자체 점검 「사면에 가짜 글자 없음」이지만 실제로 상단 가장자리에 문자가 있음).
개정 / 전달 시 git 커밋. 프로젝트는 git 저장소이지만 오랫동안 커밋하지 않음 → v5 장면 코드가 전체 화면 버전으로 덮어쓰여진 후 렌더링 화면만 보고 재구성해야 하며, 복원도가 떨어짐 (D3). 각 버전을 완료하거나 전달하기 전에 git add -A && git commit을 실행합니다. 코드 손실은 전체 프로세스에서 유일하게 되돌릴 수 없는 손실입니다.

베이스 결함은 베이스를 보충하거나 사례로 등록하고, 단일 구간에만 패치를 적용하는 것을 금지합니다 (오답 #36 InfoScrim: 0715-02 제자리 패치, 결함이 0722-01까지 남아 폭발).

블록 라우팅 테이블 (조립 각 단계에서 어떤 파일을 읽을지)

블록	파일	담당
문장 유형 선택 (첫 번째 조회 지점)	references/selection.md	구술 문장 유형 → 단락 유형 → 문법 포인터 → 컴포넌트 대조표; 메인 촬영 세 순서 판단 기준; 미일치 시 출구
참고 없음 연구	references/rd-noref.md	문법 갭 + 참고 영상 없음 시의 새 편집 설계: 다중 방안 생성 → judge 패널 → 사용자 최종 확정
참고 영상 복제 (연구 모드-A 방법 레이어)	독립 skill `remotion-reference-fidelity`	참고 영상 복제 시의 충실도 방법론: scene grammar 여섯 가지 유형, 단어급 beat 표, 충실도 게이트; 「참고 영상을 충실히 읽는 방법」만 담당하며, 수치는 모두 각 블록의 진정한 출처를 기준으로 함; alpha 투명 전달선 트리거 조건도 여기에 있음 (§6 참조)
장 내러티브	references/narrative.md	사이드 레이블 시스템, 레드/그린 진영, 강타 타이밍, hook/CTA, 판결문 승격
밀도 리듬	references/rhythm.md	beat 표, 매 3-5초 비트, 퇴장 규율, recap 강조, 감사 방법
자막	references/subtitle.md	의미론적 끊어 읽기, 영어 단문, 하단 배경 상자, 검증 스크립트
자료 엔지니어링	references/broll.md (규칙 진정한 출처) + 독립 실행 skill `remotion-broll` (판단 → 수집 → 진위 확인 → 구간 선택 → 임베딩 → 색보정 → 구간 렌더링 원스톱, 진정한 자료 구간이 판단되면 호출하여 작업)	4단계 자료 우선순위 (자체 화면 녹화 > 공식 비디오 > 스크린샷 > 시뮬레이션 카드), 비디오 자체 수집 및 편집 파이프라인, punch-in, 색보정 통일
사운드	references/audio.md (규칙 진정한 출처) + 독립 실행 skill `remotion-sfx` (소스 선택 → 청음 보드 → 가공 및 라이브러리 등록 → cue 마운트 → 정량 검수, 단락 배음 시 호출하여 작업)	SFX 파이프라인, 볼륨 규범, 마스터 loudnorm, 정량 검수
판형/인쇄/질감/모션/차트	design-system의 references/	layout / typography / texture / motion / infographic
오답 집합 (증상 → 수정 방법 색인)	독립 skill `remotion-gotchas-index`	본문의 「오답 #NN」(#18/#19/#23/#24/#25 등)의 수정 방법 위치는 여기서 조회

엔지니어링 베이스 (substrate): 본 프로세스는 src/design/ (tokens/컴포넌트/motion/qc 프로브/FontGuard) + src/koubo/scenes/shared.tsx (게이트 제어 4종 세트 + Place + qcAllow)가 이미 제자리에 있다고 가정합니다 — 이들은 전체 저장소 공유 베이스이며, 새 영상에서 재사용되고 재구성되지 않습니다. Cold start 시 src/가 없으면 먼저 design-system SKILL 「엔지니어링 베이스 목록」에 따라 베이스를 구축한 후 본 프로세스로 진입합니다.

새 영상 종단 간 프로세스 (참고 영상 없음: 거친 편집+SRT에서 완성본까지의 범용 체크리스트)

위치 명확화 (2026-07-20): 참고 영상 없음이 일반적이며, 참고 영상 있음은 특수 사례입니다. 일반적 = 독창적인 구술 편집, 해당 참고 영상 없음, references/selection.md 문장 유형 문법 경로를 따르고, 이미 보정된 스타일 사양을 사용하여 계획을 수립합니다 (본 체크리스트는 이를 위해 작성됨). 참고 영상 있음 (예: 기준 영상의 특정 영상을 1:1 복제하여 스타일 보정)은 특수 사례일 뿐이며, 용도는 스타일이 제대로 학습되었는지 보정하고 검증하는 것입니다. 「참고 영상 있음, 프레임별 정렬」을 기본 프로세스로 간주하지 마십시오. 기존 각 절은 주로 0715-01/기준 영상을 예시로 사용합니다 (프레임별 정렬이 가능한 보정 시나리오). 참고 영상이 없는 자체 제작 영상은 본 체크리스트를 따릅니다 — 범용 프로세스는 여기에 있으며, 본 영상의 세부 사항은 각 해당 블록에 귀속됩니다. 참고 영상이 있을 때는 4단계 전에만 「원본 영상 contact sheet 단어급 정렬」을 삽입합니다 (§2 3단계 / §2.5 연구 모드 참조), 나머지 단계는 동일합니다.

입력 검수 및 자료 접수 (§0 + §0.5): 거친 편집 완성본 + SRT 수신, §0.5 7단계에 따라 「사용자가 던져준 두 파일」을 작업 가능한 상태로 변환합니다 (동일 영상 확인/위치 지정/자막 초안/엔지니어링 골격/하드코딩 적응). ffprobe로 fps/해상도 결정, 합성 매개변수는 자료와 일치해야 하며, 기본 60fps를 사용하지 마십시오 (design-system 오답 #19); calculateMetadata 코드화.
구도 사용자에게 질문 (§1 / layout.md §1): 정보 영역을 왼쪽/오른쪽에 배치하는 것은 자의적으로 결정하지 말고, 3-4프레임을 추출하여 인물 위치를 보고 사용자 결정을 기준으로 합니다; 저자는 기본적으로 정보 MG를 왼쪽에 배치합니다.
SRT 전체 읽고 장 구분 (§2 1단계): 의미론적 전환에 따라 15-20개 단락으로 나누고, 각 단락마다 하나의 메인 포장 지점을 선택합니다; 동시에 타임라인에 다섯 가지 에너지 노드를 표시합니다 (hook/강타 판결문/VS 결산/전체 영상급 판결문/CTA, narrative.md §1 참조).
문법에 따라 계획 수립 (참고 영상 없음의 핵심 차이): 원본 영상에서 beat을 복사할 수 없으므로, 문장별로 먼저 references/selection.md 문장 유형 대조표를 조회하여 단락 유형 및 메인 문법 (메인 촬영 세 순서 판단 기준 포함)을 결정한 후, 포인터가 가리키는 블록 진정한 출처에서 사양을 가져옵니다 — narrative는 내러티브 골격과 다섯 노드 결정, rhythm은 비트 전환과 피크 결정, infographic은 비유 시각화 결정, layout은 3구역과 인수 결정. 대조표에 일치하는 것이 없는 문장 유형은 references/rd-noref.md를 참조하며, 맨 뼈대 디자인을 금지합니다. 산출물: 조립 계획표 (assembly/<영상명>/조립계획서.md: 시간대｜구술 요점｜사이드 레이블｜메인 MG｜자료 갭), 사용자에게 보여주고 확인을 받은 후에야 코드를 작성합니다.
연구/생산 모드 판단 (§2.5): 전체 단락의 주요 편집이 모두 기존 문법에서 대응을 찾을 수 있음 = 전체 생산 모드 (§2.5.1 다섯 단계); 새 편집 모드를 포함하는 단락은 연구 모드로 승격하여 단계별 순환 진행.
구현 + 세 가지 게이트 (§2.5): 자료 구간은 remotion-broll, HUD 구간은 layout 측정값에 따라 코드 작성, 배음은 remotion-sfx; 각 단락은 QC 프로브 → mg-judge → 사용자 최종 심사를 통과.
전체 영상 장법 통과 (§2.6): 색상 체계 예산/사이드 레이블 연속성/리듬 밀도 곡선/SFX 분포/반복 요소 다섯 가지 항목을 단락 간에 한 번씩 검토.
마스터 체인 + 전달 (§5/§6): 마스터 체인 (압축+정량 게인+리미터, audio.md 규칙 2) 통과 후 ffprobe로 재생 시간/오디오 트랙/비트레이트 검증; 전달 시 증거 첨부 (QC 보고서+렌더링 프레임 비교). 전달 또는 재작업 종료 후 프로젝트 루트 STATUS.md의 본 영상 상태 행 업데이트 (없으면 생성; 이는 세션 간/agent 간 상태 파일이며, 새 대화가 이어받을 때 전적으로 의존함).

0. 입력 규범 (사용자 전달 규칙)

사용자 제공: 거친 편집 완성본 (숨소리 이미 편집됨) + 配套 SRT. whisper 실행 안 함.
상호 작용 계약 (2026-07-21 사용자 결정, 철칙급): 사용자는 세 가지만 제공 — ① 거친 편집+SRT; ② 지명된 자료 (B-roll 화면 녹화/스크린샷 — AI가 먼저 broll 규칙 2에 따라 목록을 작성하여 지명 요청하거나, 사용자가 자발적으로 제공); ③ 자연어 판결 및 최종 심사 피드백 (구도 방향, 청감/촉감 시간 보고). 이 외에는 사용자에게 어떤 파일도 던지도록 요구하지 마십시오: 조립 계획, 워크샵 문서, 재작업 지시서, cue 테이블 등 프로세스 파일은 모두 내부 산출물이며, AI가 스스로 생성하고 읽고 이어갑니다 — 재작업/계속 작업은 §0.5 1단계 「동일 영상 재입력」에 따라 미해결 항목을 자동으로 로드하며, 사용자에게 프로세스 파일을 전달, 붙여넣기 또는 재설명하도록 요구하는 것을 금지합니다.
SRT 타임스탬프 = 조립 유일한 기준: enterAt 프레임 = SRT 시작 초 × 합성 fps.
입력에 SRT가 없는 경우 (구술 텍스트만 있음) 계획 수준의 beat 표만 출력할 수 있음: 시간 열에 「추정」 표시, 코드 작성 전에 반드시 실제 SRT로 다시 보정; 거친 편집이 없어 프레임을 추출할 수 없는 경우 구도 판결에 「판결 대기」 표시.
합성 fps/해상도는 자료에 일치 (ffprobe 먼저 조회, 기본 60fps 사용 금지). 1080p@30이 아닌 경우: 사양표/모션 프레임 수/qc-master.mjs 메타데이터 어설션을 함께 변경해야 하며, 전체 변경 목록은 design-system references/motion.md §0 참조 (기존 전체 보정 값은 30fps 고정).
자막 생성 및 끊어 읽기 규범 → references/subtitle.md.

0.5 자료 접수 작업 목록 (새 영상 작업 시작 0단계: 사용자가 제공한 mp4+SRT에서 작업 가능 상태까지)

환경 자체 점검 (통과하지 못하면 중지, 우회 금지, 호스트 범용): Bash로 테스트 파일 작성 (예: echo ok > assembly/env-check.txt) → 읽기 파일 수단으로 다시 읽어 가시성 확인 (Claude=Read 도구) → 삭제. 쓰기가 지속되지 않거나 다시 읽어도 보이지 않음 = 세션이 샌드박스 모드에서 실행 중이며, 이후 모든 산출물이 증발함 (오답 #30: 0719-01 테스트 따라서 전손) — 즉시 중단하고 사용자에게 쓰기 권한을 열어달라고 요청 (Claude=Bash/편집 권한 부여; Codex=workspace-write 등), 그런 다음 작업 시작. 세 가지 자체 구제 우회 금지: /tmp 심볼릭 링크로 중국어 경로 우회 (경로 전체를 큰따옴표로 감싸면 됨), 자체적으로 샌드박스 해제 (dangerouslyDisableSandbox 등 모든 호스트 플래그), 프로젝트를 다른 곳에 복사하여 작업. 파일 산출물은 모두 표준 파일 쓰기 수단으로 디스크에 저장하고 다시 읽어 확인합니다 (Claude=Write 도구 우선).
동일 영상 확인: ffprobe 재생 시간과 public/footage/의 기존 각 영상을 비교, ±1초 이내이면 동일 영상으로 간주 → 사용자에게 「기존 구현을 재사용할까요, 아니면 새 영상으로 다시 편집할까요?」 질문; 다시 편집 선택 시 전체 과정에서 기존 영상의 scenes 코드 및 assembly/<기존 영상명>/ 워크샵 문서를 읽지 않음 (기존 답변을 베끼거나 기존 영상을 실수로 덮어쓰는 것을 방지), 새 영상명으로 완전히 새로운 프로세스를 진행합니다. 동일 영상 재입력 (계속 작업/재작업/자료 교체, 2026-07-21 결정): 사용자가 「계속」이라고 말하거나 새 자료만 던져줄 때, 자동으로 assembly/<영상명>/분단공방/segments.md의 미완료 항목 + docs/<영상명>-재작업지시서*.md의 미해결 항목을 스캔하여 직접 본 라운드의 작업 목록으로 설정하고 작업 시작 — 사용자가 재작업 지시서를 붙여넣거나, 내역을 재설명하거나, 어디를 수정할지 설명하도록 기다리는 것을 금지합니다 (§0 상호 작용 계약).
영상명 결정: MMDD-NN (촬영 날짜-일련번호, 예: 0715-01); 사용자가 지정한 이름을 따릅니다.
자료 위치 지정: 거친 편집본을 public/footage/<영상명>.mp4로 복사; 소스가 4K인 경우 먼저 1080p H264로 변환한 후 footage에 넣습니다 (합성이 1080p이므로, 4K로 깔린 OffthreadVideo 디코딩 지연 시 중복 프레임 발생 = 완성본 인물 프레임 고정, 0721-01 실증은 오답 #33 참조 — 접속 단계에서 변환하고, 프레임 고정이 렌더링된 후 재작업할 때까지 기다리지 마십시오); 원본 SRT를 assembly/<영상명>/input/에 보관 (SRT는 조립 유일한 기준이므로 반드시 라이브러리에 넣어야 함 — 0715-01 교훈: 원본 SRT가 라이브러리에 없어 생성물만 남아 재검증 불가). 사용자 원본 파일은 변경하지 않습니다.
검수: §0의 ffprobe 항목 + SRT 세 가지 항목 (UTF-8 읽기 가능, 타임스탬프 단조, 마지막 항목 종료 시간 ≈ 비디오 재생 시간) + 자막 레코딩 확인 (ffprobe 후 필수): ffmpeg로 임의의 1-3프레임을 추출하여 Read 도구로 하단을 보고, 육안으로 거친 편집본에 자막 레코딩/워터마크가 없는지 확인 (0715-02 교훈: 원본 전달에 전체 영상 자막 레코딩이 포함되어 있고, 픽셀에 레코딩되어 독립 자막 스트림이 없으며, 정밀 수정 새 자막과 중복되어 렌더링 프레임에서 발견됨 = 한 라운드 QC가 헛됨; 발견 즉시 중지하고, 사용자에게 자막 없는 버전을 제공하거나 점유를 결정하도록 요청).
자막 초안: node scripts/srt-to-cues.mjs <보관.srt> <영상명> 기계적 변환으로 src/koubo/subtitles-<영상명>.ts 초안 생성 (zh=SRT 원문, en 비어 있음), 그런 다음 subtitle.md 규칙 2/3에 따라 의미론적 재배열, 오타 교정 (구술 기준), 영어 번역 완료, check-subs.mjs에서 오류 제로여야 조립 가능. 세 단계는 일체형이며, 영어 번역은 선택 사항이 아님 — check-subs는 이제 「en 모두 비어 있음 / 적용 범위 <90%」를 차단합니다 (2026-07-27 입안: 0727-01은 재배열만 수행, 77개 en 모두 비어 있음, 완성본이 한 줄 중국어로 퇴화, 구버전 check-subs는 en이 비어 있지 않을 때만 형식 검증, 모두 비어 있으면 오히려 조용히 통과). 진정한 단일 언어 영상을 만들려면 명시적으로 --mono 플래그를 전달하여 「이것은 결정이다」와 「이것은 누락이다」를 구분합니다.
엔지니어링 골격: node scripts/scaffold-koubo.mjs <영상명> <재생 시간 초> 한 번에 생성 (자막 트랙/음향 효과 트랙+빈 cue 테이블/메인 컴포넌트/scenes-<영상명>/ 디렉토리+자리 표시자/워크샵 단락 표, 볼륨은 현재 기준선 사용; 스크립트 끝에 Root.tsx 등록 코드 조각을 출력하므로 그대로 붙여넣기만 하면 됨). 단락 파일 디렉토리는 기존 영상 scenes/와 분리 — 파일 잠금은 영상별로 독립적으로 적용되어 이름 충돌 방지; 공유 베이스는 여전히 src/koubo/scenes/shared.tsx에서 참조.
영상 교체 시 두 곳 하드코딩 변경: render-service의 COMP_ID/ENTRY 및 qc-master 메타데이터 어설션, 세부 사항은 §6 「영상 교체 시 반드시 변경」 참조.

1. 구도 및 3구역 판형 → design-system references/layout.md

구도는 먼저 사용자에게 질문합니다 (0715-01 교훈: 정보 영역 방향은 자의적으로 결정할 수 없으며, 사용자 결정에 따라 왼쪽에 배치). 3구역 좌표, takeover 자료 인수 메커니즘 (A급: 인물 전체 구간 퇴장, PiP 없음; 승격 순간은 글꼴 크기 등급 상승+공간 정리+레드/그린 미러 프레임 사용, B급 어둡게 하기는 사용자가 거부함), 주역 순간, 그룹화 템플릿은 모두 layout.md에 있습니다 — 이것이 판형의 유일한 진정한 출처입니다.

2. 분할 방법: 먼저 계획, 그 다음 코드 (두 단계)

SRT 전체 읽고 장 구분: 의미론적 전환에 따라 15-20개 단락으로 나눕니다 (오프닝 hook / 논점 / 사례 / 전환 은유 / 분기점 진행 / 요약 / 예측 / 엔딩), 각 단락마다 하나의 「메인 포장 지점」을 선택합니다.
조립 계획표 생성 (assembly/<영상명>/조립계획서.md): 시간대 | 구술 요점 | 사이드 레이블 | 메인 MG | **규칙 근거** | 자료 갭 | 수용 모드, 사용자에게 보여주고 확인을 받은 후에야 코드를 작성합니다. 「규칙 근거」 열은 §0.1 필독 관문의 검수 증명서입니다 (2026-07-27 추가): 각 단락에 해당 단락의 주요 편집이 근거하는 항목 번호를 채웁니다 (예: motion §7 숫자 롤링 / narrative §5 판결문 승격 / selection 횡평문). 항목 번호를 채울 수 없음 = 해당 단락은 어감으로 설계된 것이므로, 진정한 출처를 다시 읽고 재배치하도록 반환 — 이 열은 문서 작업이 아니라, 「읽었는지 읽지 않았는지」에 대한 유일하게 확인 가능한 증거입니다 (0727-01의 계획표는 27개 단락에 규칙 참조가 하나도 없어, 전체 영상 모션 효과가 따라서 하나의 페이드 인만 남았습니다).

B-roll 수용 모드는 먼저 질문해야 합니다 (2026-07-24 사용자 결정, 가로 화면 영상 강제): 단락을 나눌 때 B-roll/화면 속 화면이 필요한 단락을 표시합니다. 각 해당 단락에 대해, 사용자가 자료를 제공하지 않은 경우, 능동적으로 나의 이해 제안을 가지고 사용자에게 질문합니다: 이 단락은 「전체 화면 B-roll」(인물 퇴장, 자료가 전체 화면을 채움)인가요, 아니면 「화면 속 화면 카드」 수용 (인물在场, 자료가 오른쪽 영역의 작은 카드에 표시, 예: 0722-01)인가요? 수용 모드는 한 번에 세 가지를 결정합니다 — ① 판형: 전체 화면 인물 차단 vs 카드+인물 상주 (layout §2 철칙); ② 해상도/도구: 화면 속 화면 720p로 충분 (Grok/gbro 콜라주 사용 가능), 전체 화면은 진정한 1080p 필요 — grok CLI 실제 측정 결과 480p/720p 두 가지 단계만 있어 불가능, 따라서 xAI API (grok-imagine-video-1.5는 1080p 지원), 진정한 자료 또는 Sora/Veo/Kling/Seedance로 가야 함 (자세한 내용은 broll SKILL ④ 참조); ③ 자료 방향: 이에 따라 AI 생성으로 가거나 사용자/편집자에게 찾도록 요청합니다. 자신이 기본적으로 수용 모드를 결정하지 마십시오 — 0722-01은 기본적으로 전체 화면을 만들고, 비율까지 일률적으로 적용하여 두 번 재작업했습니다.

자료 미도착 구간 병렬 렌더링 (속도 향상 철칙, 2026-07-24 사용자 결정): 수용 모드와 자료 방향 확인 후 자료를 기다리며 차단하지 않음 — 모든 외부 자료에 의존하지 않는 순수 MG 구간을 먼저 모두 렌더링 완료하고, B-roll/화면 속 화면을 기다리는那几个 단락만 자리 표시자로 남깁니다; 자료 도착 후 그 구간만 보충 렌더링하고 splice로 전체 영상에 다시 붙입니다 (구간 렌더링 다시 붙이기는 22초 수준, §6 참조). 즉: 자료 의존 구간과 독립 구간을 분리하여, 사용자가 자료를 찾는 동안 메인 세션은 렌더링할 수 있는 것을 모두 렌더링하여 병렬성을 최대화합니다. 3. 구술 원고가 특정 참고 비디오에서 비롯된 경우 (녹화/재작성), 먼저 원본 영상의 contact sheet를 추출하여 단락별로 정렬해야 합니다 (ffmpeg로 10-15초마다 한 프레임을 추출하여 그리드로 만듦), 원본 영상의 실제 처리를 기준으로 하고, 자유롭게 창작하지 마십시오 — 첫 번째 조립 시 8곳의 편차는 모두 원본 영상을 먼저 보지 않은 데서 비롯되었습니다.

2.5 분할 정렬 워크샵 (2026-07-16 사용자 결정; 2026-07-17 이중 모드 판단 기준 보충)

연구 모드 vs 생산 모드 (사용자가 속도 향상을 지명한 후 결정, 제일 원리: 문법이 이미 침전되었으면 더 이상 발굴해서는 안 됨):

연구 모드 (본 절 전체 프로세스: 집중 프레임 읽기 → 계획 → 다중 경로 검증 → 단락별 최종 심사)는 새 편집 모드를 도입하는 단락에만 사용됨 — 판단 기준: 해당 단락의 주요 편집이 narrative/rhythm/infographic/specs 기존 규칙에서 해당 문법을 찾을 수 없음. 연구 모드는 A/B 두 가지 방법 경로로 나뉨: 참고 영상 있음, 프레임 추출 가능 = 연구-A (본 절 2단계 참조 프레임 읽기); 문법 갭 및 참고 영상 없음 = 연구-B, 방법 본체는 references/rd-noref.md (다중 방안 생성 → judge 패널 우선 선택 → 사용자 최종 확정 → 침전 및 다시 쓰기), 본 절 2단계는 연구-B에 적용되지 않음.
생산 모드 (패턴 재사용 단락): 단락별 순환을 거치지 않고, 「전체 단락 팬아웃 병렬 + 집중 통합」 배치 토폴로지 사용 (다섯 단계는 §2.5.1 참조) — 판단 기준 반전: 전체 단락의 주요 편집이 모두 기존 규칙에서 해당 문법을 찾을 수 있음. 어떤 단락 judge 반려율이 상승하면 = 해당 단락에 실제로 새 모델이 포함되어 있으므로, 단독으로 연구 모드로 승격하고, 나머지 단락에 영향을 주지 않음 (승격 임계값 정량화 = 동일 단락 스캔 배치 반려 ≥2회 또는 사용자 최종 심사 재작업, §2.5.1 4단계 참조).

연구 모드 단락별 순환:

단락 분할: 내용에 따라 참고 영상과 정렬하여 수십 개의 조각으로 나눔 (장 수준에서 시작, 문제 구간은 beat 수준까지 세분화). 다중 세션 병렬 규율 (2026-07-17 사용자 명령): 작업 시작 전에 먼저 assembly/<영상명>/분단공방/segments.md 단락 표 읽기 (본 영상 예시: assembly/0715-01/분단공방/segments.md) — 자리 표시자가 있는 단락은 건드리지 않음; 자신이 작업 시작 시 먼저 자리 표시자 행 작성 (세션 식별자+작업 범위 목록: 어떤 파일의 어떤 블록을 수정할지); 렌더링/npm은 전체 프로젝트 직렬 (오답 #23/#24), 렌더링 시작 전 pgrep으로 장면 확인. 새 영상이 처음으로 워크샵에 진입할 때 해당 파일이 존재하지 않음: 메인 세션이 초기화 — mkdir -p assembly/<영상명>/분단공방/ 후 segments.md 새로 생성, 0715-01 단락 표 형식 적용 (한 줄에 한 단락: 단락 번호 | 시간 범위 | 메인 포장 지점 | 적용 범위 파일 | 자리 표시자/인계 상태), 작업 배정 전에 먼저 생성하고, 하위 에이전트는 인계만 하고 새로 생성하지 않음.
참고 보기 (단어급 정렬, 2026-07-16 사용자 결정): 참고 영상의 해당 단락 밀집 프레임 추출 (0.5초/프레임). 대본이 참고 영상과 동일할 때, 참고 영상에 포함된 자막을 정렬 축으로 사용 — 각 프레임은 자체적으로 「그가 지금 무엇을 말하고 있는지」를 가지고 있어, 「무슨 글자를 말함 → 어떤 MG가 나옴」의 단어급 beat 표를 복원하고, 우리의 SRT에서 동일 문장의 시간점을 찾습니다; 비교는 반드시 프레임별로 그림을 읽고 이해해야 합니다 (요소 사양/연결 관계/양보 동작), 파일 이름이나 썸네일만 보는 것을 금지합니다. 먼저 「진정한 자료 구간인지 손으로 그린 HUD 구간인지」 판단 (broll.md 총칙 참조), 그런 다음 먼저 측정하고 코드 작성 — 참조 프레임에서 요소의 화면 점유 비율/글꼴 크기/위치를 측정하고, 육안 측정을 금지합니다 (seg01 교훈: 육안 측정 = 체계적 축소 0.4-0.7배). 산출물: 해당 단락의 《계획》(beat 표+차이 진단+수정 방법+비교 스크린샷), 사용자에게 보여주고 확인을 받은 후에야 코드를 건드립니다.
만들기: 자료 구간은 수집 파이프라인 사용, HUD 구간은 측정값에 따라 코드 작성.
해당 단락 렌더링: --frames=a-b 수십 초만에 출력; 렌더링 전에 기존 산출물 삭제하여 ○ 캐시 방지.
검수 (세 가지 게이트, 2026-07-16부터; 2026-07-27 정적 게이트 하나를 앞에 배치): ⓪베이스 재사용 게이트 (node scripts/check-scenes.mjs src/koubo/scenes-<영상명>) — 정적 스캔 장면 디렉토리: design/motion 제로 참조, 제로 퇴장 요소 (useExit/Exit/ClearOut, motion §1 sev5) 각각 FAIL; 컴포넌트 카테고리가 단락 수 등급 미만 (단편 <10개 단락 3개 카테고리 / 장편 5개 카테고리), 퇴장 적용 범위 <50%, 자체 kit >150줄이지만 모션 제로 각각 WARN 보고; 끝에 자체 점검 목록 하나 출력 (숫자 롤링 / 판결문 떨어뜨리기 / 장 간 깨끗한 화면 / 모션 효과 어휘 단일 여부), 이 네 가지 항목은 정적 스캔으로 찾을 수 없으므로, 반드시 직접 연속 화면을 봐야 함. (임계값은 2026-07-27 대항식 검토 후 수정됨: 초기 버전의 「Breathe 제로 참조 WARN 보고」는 삭제됨 — motion §9 「새 영상은 일률적으로 Breathe를 걸지 않음」과 직접 충돌; 「컴포넌트 카테고리 <4 일률적」

…

[truncated for translation]

remotion-assembly