HyperFrames — 먼저 읽으세요
모든 HyperFrames 작업은 여기서 시작하세요 — 특히 프로젝트에 에이전트 설정(CLAUDE.md / AGENTS.md / .cursorrules)이 없는 경우 더욱 그렇습니다. 아래에 기능 맵과 영상 라우터가 있습니다.
기능 맵 — 어떤 의도에 어떤 스킬
| 원하는 작업 | 이동할 곳 |
|---|---|
| 영상 만들기 (URL, 브리프, 주제, GitHub PR, 기존 영상, 또는 애니메이션할 단일 요소에서) | 아래 영상 라우터 (§ 영상 라우팅) |
| 슬라이드쇼 / 프레젠테이션 / 피치 덱 제작 — 개별 슬라이드, 조각, 분기, 핫스팟 | /slideshow |
HTML 컴포지션 제작 / 편집 — data-* 계약, 클립, 트랙, 하위 컴포지션, 변수 | /hyperframes-core |
| 애니메이션 — 원자적 모션 규칙, 씬 청사진, 전환, 런타임 어댑터(GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | /hyperframes-animation |
크리에이티브 디렉션 — design.md, 팔레트, 타이포그래피, 나레이션, 비트 계획, 오디오 반응형 | /hyperframes-creative |
| 미디어 전처리 — TTS 음성 해설, 배경 음악, 자막 생성, 배경 제거, 캡션 | /hyperframes-media |
| CLI 개발 루프 — init, lint, validate, inspect, preview, render, publish, doctor | /hyperframes-cli |
레지스트리 블록 / 컴포넌트 설치 (hyperframes add) | /hyperframes-registry |
컴포지션 제작 계약(모든 시간 기반 요소는
data-start/data-duration/data-track-index가 필요하고, 시간 기반 요소는class="clip"이 필요하며, GSAP 타임라인은 일시 중지되고window.__timelines에 등록되며,Date.now()/Math.random()/ 네트워크 없는 결정적 로직만 가능)은 여기에 중복되지 않습니다 —/hyperframes-core에 있습니다. 컴포지션 HTML을 작성하기 전에 그것을 읽으세요.
HyperFrames로 할 수 없는 것 — 먼저 확인하세요
HyperFrames는 HTML 컴포지션을 제작하고 이를 코드에서 MP4로 렌더링합니다. 이 모델에는 명확한 외부 경계가 있습니다. 그 경계를 벗어난 요청은 라우팅 선택이 아니라 범위를 벗어난 것이므로, 워크플로우를 선택하는 대신 거절하거나(또는 올바른 도구를 가리키세요). 이는 아키텍처에서 비롯되며, 특정 요청 때문이 아닙니다.
- 렌더는 결정적이고 자체 포함됩니다. 모든 값, 에셋, 텍스트는 제작 시점에 고정되며, 렌더는 네트워크 호출이나 실시간 데이터 가져오기를 하지 않습니다(핵심 규칙:
Date.now()/Math.random()/ 네트워크 금지). "렌더 시간에 실시간으로 숫자를 새로고침"하는 것은 불가능합니다 — 제작 시점에 데이터를 한 번 가져와 고정하거나 거절하세요. - 기존 영상은 오버레이만 가능하고 편집은 불가능합니다. HyperFrames는 소스 클립 위에 프레임을 합성합니다 —
/embedded-captions는 캡션 레이어를 추가하고,/graphic-overlays는 디자인된 그래픽 카드(로우어 서드, 데이터 콜아웃, 타이틀)를 추가합니다 — 클립은 그 아래에서 변경 없이 재생되지만, 인코딩된 비디오 스트림을 후처리하지는 않습니다. 푸티지 자체(타이밍, 색상, 프레이밍, 순서, 오디오)를 변경하는 것은 NLE 스타일 편집이며 범위를 벗어납니다. - Remotion 임포트는 단방향입니다.
/remotion-to-hyperframes는 Remotion 프레임워크의 소스를 HyperFrames로 변환합니다. 역방향(HyperFrames → Remotion 또는 다른 프레임워크로)은 없으며(범위를 벗어남), Remotion이 아닌 React / 웹 애니메이션 소스는 변환할 Remotion 소스가 없으므로/general-video를 통해 다시 만드세요. - 가지고 있지 않은 입력은 생성할 수 없습니다. 화면 / 세션 녹화, 카메라 캡처, AI 말하는 얼굴 / 립싱크 아바타 생성이 없습니다. 푸티지나 에셋이 아직 존재하지 않으면 HyperFrames가 그것을 마법처럼 만들어낼 수 없습니다 — 사용자에게 제공하도록 요청하거나(또는 올바른 캡처 도구를 사용하도록) 하세요.
그 외 모든 것 — URL, 브리프, 주제, PR, 주석 달 푸티지, 또는 애니메이션할 단일 요소에서 비디오를 만드는 것 — 은 범위 내에 있으며 아래에서 라우팅하세요.
영상 라우팅
이 섹션은 최상위 워크플로우만 알고 있습니다. 워크플로우 내부 단계, 도메인 스킬(hyperframes-* — 위의 기능 맵 참조) 또는 기술 참조를 로드하지 않습니다.
의사 결정 테이블
INPUT 유형(의도)이 주요 축이며 OUTPUT 길이는 한계일 뿐 장벽이 아닙니다. 일치하는 입력에 대해 특화된 워크플로우는 최대 ~3분까지 처리합니다 — 어떤 워크플로우에 들어갈지는 입력 유형에 의해 결정되며(입력 유형, 텍스트의 경우 주제), 길이에 의해 결정되지 않습니다. 길이는 상한에서만 중요합니다: 진정으로 긴 작품(3-5분 튜토리얼, 5분+ 심층 분석)은 다른 레지스터이며 /general-video로 라우팅됩니다. ≤~3분 대역 내에서, 세 번째 축이 두 개의 텍스트 기반 워크플로우를 나눕니다 — 주제: 마케팅되는 제품 vs 설명되는 주제(아래 단계 3의 명확화 규칙 참조).
| 길이 / 입력 | 제품 런칭 (URL / 브리프 / 스크립트) | 일반 웹사이트 / URL | GitHub PR / 코드 변경 | 주제 / 기사 / 노트 (제품 없음, URL 없음) | 기존 영상 (말하는 사람) † |
|---|---|---|---|---|---|
| ≤ ~3분 | /product-launch-video | /website-to-video | /pr-to-video | /faceless-explainer | /embedded-captions · /graphic-overlays † |
| 3-5분 튜토리얼 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 5분+ 심층 분석 | /general-video | /general-video | /general-video | /general-video | /embedded-captions · /graphic-overlays † |
| 정적 / 루프 | /general-video | /general-video | /general-video | /general-video | /general-video |
현재 범위: ≤ ~3분 대역에는 제품 런칭 / 일반 웹사이트 / GitHub-PR / 주제 입력에 대한 전용 워크플로우가 있으며(URL은 _종류_에 따라, 그 다음 _의도_에 따라 나뉩니다 — 단계 3 참조), 기존 영상 열은 모든 길이에서 /embedded-captions(캡션 / 자막) 또는 /graphic-overlays(디자인된 그래픽 오버레이)로, 의도에 따라 나뉘어 처리됩니다(단계 2 참조). 다른 모든 셀은 /general-video — 일반 HTML 컴포지션 제작 흐름(입력 및 길이 불가지론): ~3분보다 긴 모든 것(3-5분 / 5분+ 행)과 모든 정적 / 루프 형식. 라우터는 생성 가능한 영상에서 막다른 골목에 도달하지 않습니다. 유일한 진정한 "일반 / 없음" 답변은 HyperFrames 자체 범위를 벗어난 요청입니다(예: 완성된 비디오 파일의 NLE 스타일 편집 — 재타이밍, 재색상, 재프레이밍, 재정렬, 오디오).
† 기존 푸티지는 의도에 따라 나뉘며 길이에 따라 나뉘지 않습니다. 캡션 / 자막 → /embedded-captions; 디자인된 그래픽 오버레이 / 패키징 — 로우어 서드, 데이터 콜아웃, 타이틀 카드, 풀-퀘스트 → /graphic-overlays. 둘 다 클립 위에 오버레이되며, 클립은 그 아래에서 변경 없이 재생됩니다. 둘 다 푸티지 자체를 편집하지 않습니다.
장르 단축 (테이블보다 우선). 짧고(~10초 미만), 나레이션이 없으며, 디자인 주도의 모션 그래픽 — 운동 타이포그래피, 통계/차트 히트, 로고 스팅, 로우어 서드/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트 — 은 입력에 관계없이 /motion-graphics로 라우팅됩니다. 이는 출력 장르이지 입력 유형이 아니므로, 요청이 명확히 모션 우선이고 나레이션이 없을 때 위의 입력 유형 테이블보다 우선합니다(단계 2 참조). 더 길거나 나레이션이 있는 작품은 입력 유형에 따라 라우팅되거나 /general-video로 라우팅됩니다.
기존 컴포지션 마이그레이션 (특수 사례)
위 테이블은 입력에서 생성하는 영상용입니다. 하나의 워크플로우는 그 밖에 있습니다: 사용자가 명시적으로 기존 Remotion (React) 컴포지션을 HyperFrames로 포팅 / 변환 / 마이그레이션해 달라고 요청하는 경우 → /remotion-to-hyperframes. 이는 입력에서 생성하는 것이 아니라 소스 변환이므로 INPUT × LENGTH 셀이 없습니다. 명시적인 마이그레이션 언어("내 Remotion 프로젝트를 포팅해줘", "이 Remotion 컴포지션을 변환해줘", "이걸 HyperFrames로 다시 작성해줘")가 있을 때만 여기로 라우팅하세요 — Remotion을 우연히 언급하는 것은 트리거가 아닙니다. 생성 테이블이나 /hyperframes-core를 기본값으로 사용하세요.
라우팅 절차
- INPUT 유형 + 대상 길이 결정. 라우팅은 영상이 무엇에 관한 것인지 — 주제와 입력을 알아야 합니다. 주제 자체가 지정되지 않은 경우(예: URL, 명명된 제품, 주제, 또는 작업할 에셋 없이 "우리 것에 대한 영상 만들어줘"), 또는 입력 유형을 알 수 없는 경우, 워크플로우에 들어가기 전에 물어보세요 — 먼저 명확히 하세요. 워크플로우 스킬을 호출한 다음 물어보지 마세요. 워크플로우에 진입하는 것이 그 자체로 라우팅 결정이기 때문입니다. 최대 2개의 명확화 질문만 하세요:
- "입력이 무엇인가요? — 제품(URL 또는 브리프), 일반 웹사이트 / URL, GitHub PR / 코드 변경, 설명할 주제나 기사, 또는 캡션을 추가할 기존 말하는 사람 영상?"
- "대상 길이는? — 약 3분 이하, 또는 더 긴 것(3-5분 튜토리얼 / 5분+ 심층 분석)?"
- 사양 기본값 — 말로만 하고 묻지 마세요 (이것들은 경로에 영향을 주지 않으므로 라우팅을 차단하지 마세요): 화면비 16:9 (엔진은 9:16 세로도 지원합니다 — 사용자가 TikTok / Reels / Shorts와 같은 세로 대상지를 언급할 때만 전환하세요); 나레이션 / 캡션 언어 = 사용자의 언어. 사용자가 이의를 제기할 때만 확인하세요. 선택한 워크플로우가 단계 0에서 자체 사양을 다시 확인합니다.
- 먼저 INPUT 유형(의도)으로 선택하세요. 길이는 한계일 뿐 장벽이 아닙니다.
- 짧은 디자인 주도 모션 그래픽 (장르 단축, 입력 테이블보다 우선) — 모션 자체가 메시지입니다: 운동 타이포그래피, 통계/숫자 카운트업, 차트 히트, 로고 스팅, 로우어 서드/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트; 일반적으로 ~10초 미만, 나레이션 / 음성 해설 없음 →
/motion-graphics. 이는 출력 장르이지 입력 유형이 아닙니다 — 요청이 명확히 빠르고, 나레이션이 없으며, 디자인 주도의 모션 작품일 때 입력에 관계없이 여기로 라우팅하세요. 동일한 소재의 더 길거나 나레이션이 있는 작품은 이것이 아닙니다(입력 유형에 따라 라우팅하거나/general-video사용). - 기존 말하는 사람 영상 (사용자가 클립을 가지고 있고 그 위에 무언가를 추가하고 싶어 함) → 의도에 따라 나뉘며, 모든 길이에서 (입력 유형이 길이보다 우선): 캡션 / 자막 (말하는 단어를 읽을 수 있는 텍스트로) →
/embedded-captions; 디자인된 그래픽 오버레이 — 로우어 서드, 데이터 콜아웃, 타이틀 정보 카드, 풀-퀘스트, 그래픽 패키지된 편집 →/graphic-overlays. (푸티지 자체 편집 — 재타이밍, 재색상, 재프레이밍, 재정렬, 오디오 — 은 NLE 스타일이며 범위를 벗어납니다. § HyperFrames로 할 수 없는 것 참조.) - GitHub PR / 코드 변경 (
github.com/<owner>/<repo>/pull/<N>링크,owner/repo#N참조, 또는 "이 PR") →/pr-to-video(최대 ~3분). - 그 외 (제품 URL / 브리프 / 주제 텍스트): 의도가 단계 3을 통해 워크플로우를 선택하며, 최대 ~3분까지 처리합니다 — 짧은 15-30초 홍보 영상과 ~100초 설명 영상 모두 길이가 아니라 의도에 따라 라우팅됩니다. 대상이 명확히 ~3분보다 긴 경우(3-5분 튜토리얼, 5분+ 심층 분석)에만
/general-video(길이 불가지론 폴백 — 단계 4 참조)로 라우팅하세요. 진정으로 긴 작품을 ≤~3분 워크플로우에 강제로 밀어넣지 마세요 — 의도가 대역 내에서 결정하며,/general-video가 나머지를 처리합니다.
- 짧은 디자인 주도 모션 그래픽 (장르 단축, 입력 테이블보다 우선) — 모션 자체가 메시지입니다: 운동 타이포그래피, 통계/숫자 카운트업, 차트 히트, 로고 스팅, 로우어 서드/오버레이, 또는 애니메이션된 트윗/헤드라인/캡처된 페이지 하이라이트; 일반적으로 ~10초 미만, 나레이션 / 음성 해설 없음 →
- ≤~3분 URL / 텍스트 입력 명확화 (의도 분할). 두 가지 분할:
- URL 종류 + 의도 — URL이 더 이상 PLV를 위해 자동으로 승리하지 않습니다. _종류_가 _의도_를 결정합니다: GitHub PR 링크(
.../pull/<N>,owner/repo#N, "이 PR") →/pr-to-video; 그 외 웹사이트 URL은 의도에 따라 나뉩니다 — 특정 제품 또는 SaaS 마케팅 / 런칭 / 홍보 →/product-launch-video; 일반 사이트 → 영상 (사이트 투어, 포트폴리오 / 블로그 / 랜딩 페이지 쇼케이스, 사이트 자체 비주얼의 소셜 클립, 또는 "이 사이트를 영상으로 만들어줘") →/website-to-video. 둘 다 헤드리스 Chrome으로 크롤링하며, PR URL은gh를 통해 읽습니다. 사이트 URL이 제품 런칭인지 일반 사이트 영상인지 명확하지 않은 경우 한 가지 질문을 하세요. - 제품 vs 주제 (텍스트, URL 없음) — 결정적인 질문은 영상이 무엇에 관한 것인지이며, 입력 형식이 아닙니다:
- 마케팅, 런칭, 또는 홍보되는 특정 제품 / 회사 / SaaS / 앱 / 웹사이트 →
/product-launch-video. - 제품도 URL도 없이 설명되는 개념 / 주제 / 기사 / 작동 방식 →
/faceless-explainer. - 타이-브레이커: "홍보 / 런칭 / 판매 / 우리 제품" 문구 → PLV. "설명 / 가르침 / X가 작동하는 방식 / X가 무엇인지" 제품 없음 → faceless. faceless의 전달 스타일은 항상
pin-and-paper입니다. - URL이 붙여넣기되지 않은 명명된 사이트는 여전히 PLV입니다. 제품 또는 그 웹사이트를 언급하는 스크립트("우리 사이트는 acme.io", "<브랜드> 홍보")는 클릭 가능한 링크가 없어도 PLV로 라우팅됩니다 — PLV는 웹 검색으로 사이트를 찾고 브랜드 에셋을 크롤링할 수 있습니다(사용자가 거부하지 않는 한 → no-capture 프리셋 모드). URL을 붙여넣지 않았다고 해서 faceless / no-capture 작업이 되는 것은 아닙니다. 제공된 스크립트에 대한 축어적 대 구조 재구성 선택은 PLV 내부 문제이며 경로를 변경하지 않습니다.
- 충돌 신호 → 묻고 추측하지 마세요. 제공된 소스가 제품의 자체 마케팅 자료인 경우(랜딩 페이지, 홍보 브리프, 마케팅 사본) → PLV로 라우팅하세요. 소스가 중립적인 설명 자료인 경우(백서, 기술 개요, 위키피디아 스타일 기사) → 여전히 PLV. 소스가 이분법적이거나 연설 / 프레젠테이션 대본인 경우 → PLV. 소스와 약간 다른 것을 요청한 경우(예: "우리 제품 페이지에서 우리 팀 오프사이트 주제로 영상 만들어줘") → 사용자에게 "당신은 제품 런칭 영상을 원하나요, 아니면 설명 영상을 원하나요?"라고 물으세요.
- 소스가 제품도 아니고 주제도 아님 — 그것이 무엇인지 알 수 없는 경우 →
/general-video로 라우팅하세요.
- 마케팅, 런칭, 또는 홍보되는 특정 제품 / 회사 / SaaS / 앱 / 웹사이트 →
- URL 종류 + 의도 — URL이 더 이상 PLV를 위해 자동으로 승리하지 않습니다. _종류_가 _의도_를 결정합니다: GitHub PR 링크(
- 길이 기반 폴백:
/general-video(의사 결정 테이블에서 적용). 다음의 경우 여기로 라우팅하세요:- 길이가 알려지거나 추정되어 ~3분보다 긴 경우(3-5분 튜토리얼, 5분+ 심층 분석).
- 입력 유형이 테이블의 네 가지 열 중 하나와 일치하지 않는 경우 (예: 정적 / 루프 형식, 또는 위에 명시되지 않은 것).
- 위의 명확화 단계 후에도 입력이 알 수 없는 경우.
- 짧은 클립에서 중간 길이 작품까지 / ...
/general-video는 항상 시도하고 사용할 수 있는 입력 불가지론 및 길이 불가지론 폴백입니다. 라우팅 순서의 마지막 단계입니다.
/general-video는 웹 브라우저를 구동하여 세션을 캡처/녹화하거나 다른 프레임워크(Remotion, Motion Canvas, After Effects)로 제작하는 요청을 다루지 않습니다. 사용자가 "브라우저를 열어 이 페이지를 캡처해줘" 또는 "이 After Effects 컴포지션을 포팅해줘"라고 요청하는 경우, 이는 라우팅 실패가 아니라 다른 도구가 필요한 다른 작업입니다 — 그에 따라 응답하세요.
워크플로우 단계 0 — 진입 및 라우팅 확인
각 워크플로우는 단계 0을 가집니다. 진입점(Experiment)이 라우팅을 완료한 후, 분기된 워크플로우는 단계 0에서 자신의 진입을 확인하고, 필요시 그 길이 / 입력 유형 / 주제 라우팅을 재확인하며, 자신의 프롬프트 / 스크립트 범위와 출력 사양(종횡비, 언어, 스타일)을 확립합니다. 이 단계는 여기서 정의되지 않습니다 — 각 개별 워크플로우에 있습니다.
행동 지침
- 인라인에만 readFile / writeFile 사용. 하나의 메시지에서 여러 파일을 읽거나 써야 하는 경우
Batched를 사용하고 가능한 경우 하나의 스크립트로 병합하세요. - 읽기 전에 쓰기 — 하지만 경로별로, 영상당 하나씩. 컴포지션을 만들 때, 작성한 직후에 읽고 검증하세요. "모든 것을 쓴 다음 읽자"고 말하지 마세요 — 각 파일을 작성하자마자 피드백하세요.
- URL 읽기 — 한 번의 호출로 충분합니다. 동일한 URL을 두 번 읽지 마세요.
- 의사 결정을 무한히 반복하지 마세요. 불가능한 작업을 계속 시도하지 마세요. 3회 시도 후 "할 수 없다"고 말하고, 실패 원인을 한 문장으로 설명한 후, 실현 가능한 대안(단축, 다른 포맷, 다른 스타일)을 제시하고, 그 대안을 구현하세요. 라우팅이나 프롬프트를 다시 물어보는 것은 "다시 시도"로 간주됩니다.
- 새로운 기능을 발명하지 마세요. 지정된 워크플로우, 스킬, 계약을 사용하세요. 일반적인 아이디어를 구현하기 위해 새로운 스킬을 작성하거나 새 명령을 만드는 것은 허용되지 않습니다.
- 루프에 갇히지 마세요. 도구 호출을 무한히 반복하지 마세요. 타임아웃되면 멈추고, 재시도하지 마세요.
본 문서는 CC0에 따라 제공됩니다.