HyperFrames 설치
HyperFrames를 비디오 제공자로 추가하는 통합을 한 번에 재현합니다. CLAUDE.md의 3단계 새 제공자 추가 계약을 따릅니다. 존재해야 하는 모든 아티팩트의 자체 완결형 체크리스트이며, 누락된 것만 확인하고 생성합니다.
이 스킬을 처음부터 통합을 다시 유도하는 대신 사용하십시오. 이는 이 저장소에서 "HyperFrames가 연결되었다"는 의미의 표준 기록입니다.
호출 시기
- HyperFrames 지원이 아직 없는 새 marketing-engine 클론
- 리베이스 또는 병합으로 아래 아티팩트 중 일부가 누락된 경우(
router:check에서 오류 발생, 비디오 라우팅이 타이포그래피 작업에higgsfield로 대체, 또는.skills/hyperframes*/디렉터리 누락) - 새 클라이언트가 프로그래밍 방식의 짧은 동영상/모션 타이포그래피/데이터 시각화 릴을 원하고 매트릭스에 세 가지 작업 종류를 연결해야 하는 경우
- 세 개의 커밋을 읽는 대신 단일 명령 가능한 플레이북이 필요한 새 운영자를 온보딩하는 경우
입력
repo_root: 문자열. marketing-engine 클론의 절대 경로. 기본값은process.cwd().branch: 문자열, 선택 사항. 커밋할 브랜치. 기본값은claude/install-hyperframes. 브랜치가 없으면 생성합니다. 절대main에 커밋하지 않습니다.dry_run: 부울, 선택 사항. true이면 계획된 변경 사항을 출력하고 종료합니다.
프로세스
각 단계를 순서대로 실행합니다. 각 단계는 멱등적입니다. 이미 통합된 저장소에서 다시 실행해도 아무런 변경이 없습니다.
1단계 — 사전 점검
repo_root에## How to Add a New Provider줄이 포함된CLAUDE.md가 있는지 확인합니다. 없으면 실행을 거부합니다—이는 marketing-engine 저장소가 아닙니다.lib/providers/video.ts,lib/providers/matrix.ts,lib/providers/types.ts,lib/providers/__mocks__/video.ts파일이 모두 존재하는지 확인합니다. 하나라도 없으면 실행을 거부합니다.- 활성 브랜치가
main이 아닌지 확인합니다.main인 경우 먼저branch를 생성하고 체크아웃합니다.
2단계 — 세 가지 런타임 스킬 추가
다음 세 개의 디렉터리를 SKILL.md 파일과 함께 생성합니다. 각 파일은 이미 트리 내 표준 버전으로 존재합니다. 아래 참조 아티팩트 세트 섹션에서 그대로 복사하십시오. 파일이 이미 존재하고 프론트매터 name이 일치하면 건너뜁니다.
.skills/hyperframes/SKILL.md— 컴포지션 작성 규칙(애니메이션 전 레이아웃, 타임라인 일시 중지 및window.__timelines에 등록,Math.random()/시간 기반 로직 금지,data-composition-variables를 통해 변수 선언)..skills/hyperframes-cli/SKILL.md—npx hyperframeslint → inspect → render 개발 루프. 항상--strict --strict-variables로 렌더링합니다..skills/hyperframes-prompt-builder/SKILL.md— 매트릭스가hyperframes로 해석될 때video-prompt-builder가 호출하는 전문가;clients/<slug>/design.md에서 브랜드 토큰을 로드하고,task_kind별 템플릿을 선택한 후 컴포지션 스펙과 렌더 인자를 반환합니다.
3단계 — 디스패처 스킬 업데이트
.skills/video-prompt-builder/SKILL.md에서:
hyperframes-prompt-builder를 시작 단락과 관련 스킬 섹션의 전문가 목록에 추가합니다.task_kind입력 열거형에motion_typography,data_viz_reel,programmatic_short를 추가합니다.- 환경 변수를 확인하는 프로세스 단계에서
HYPERFRAMES_ACTIVE를 목록에 추가합니다. - 제공자→전문가 매핑에
Hyperframes -> hyperframes-prompt-builder행을 추가합니다. - 예제 추가: Hyperframes로 라우팅되고
task_kind: programmatic_short인 주간 KPI 릴.
대상 문자열이 이미 존재하는 하위 단계는 건너뜁니다.
4단계 — 제공자 레이어 확장
lib/providers/types.ts에서 VideoTask 유니온에 세 멤버를 추가합니다:
| "motion-typography"
| "data-viz-reel"
| "programmatic-short"
lib/providers/matrix.ts에서:
EMBEDDED_DEFAULTS.video에 세 개의 행을 추가합니다:motion-typography,data-viz-reel,programmatic-short— 각각 기본값은hyperframes입니다.TASK_LABEL_MAP에 레이블 별칭을 추가합니다:"motion typography","kinetic typography","data viz reel","data-viz reel","programmatic short","parametrized short".
lib/providers/video.ts에서:
RealVideoBase를 확장하고process.env.HYPERFRAMES_ACTIVE === "true"에서 게이트되는HyperframesVideoProvider클래스를 추가합니다.realGenerate에서 기존 higgsfield/topview 스텁 패턴과 일치하게 "로컬 CLI 렌더가 호출자 컨텍스트에서 필요합니다. 스텁" 오류를 던집니다.REAL_VIDEO_REGISTRY에hyperframes: () => new HyperframesVideoProvider()를 등록합니다.
lib/providers/__mocks__/video.ts에서:
BaseMockVideo를 확장하고name = "hyperframes"인MockHyperframesVideoProvider를 추가합니다.MOCK_VIDEO_REGISTRY에hyperframes: () => new MockHyperframesVideoProvider()를 등록합니다.
5단계 — 라우팅 매트릭스 파일 업데이트
.specs/architecture/PROVIDERS.md에서 비디오 라우팅 테이블에 세 행을 추가합니다:
| Motion typography | hyperframes | HTML/GSAP 동적 타이포그래피, 브랜드 충실, 결정론적 |
| Data viz reel | hyperframes | 선언된 변수 → 재렌더링 가능한 차트 (NYT 스타일) |
| Programmatic short | hyperframes | 매개변수화된 HTML 컴포지션; 바이트 동일 재렌더링 |
6단계 — .env.example 업데이트
WAVESPEED_API_KEY= 뒤에 다음을 추가합니다:
# HyperFrames는 로컬 HTML→MP4 렌더러입니다. API 키가 필요하지 않습니다.
# 로컬에서 `npx hyperframes doctor`가 통과하면 HYPERFRAMES_ACTIVE=true로 설정하십시오.
# (Node >= 22, PATH에 FFmpeg 필요). https://github.com/wesleysimplicio/hyperframes 참조
HYPERFRAMES_ACTIVE=false
7단계 — CLAUDE.md 업데이트
- 스택 테이블에서
Video행의 제공자 셀에hyperframes (로컬 HTML→MP4)를 포함하도록 변경합니다. - 사용 가능한 스킬에서
wavespeed-batch뒤에 세 줄을 삽입합니다:hyperframes— HTML을 진실 공급원으로 사용하는 모션 컴포지션 제작.hyperframes-cli—npx hyperframeslint/inspect/preview/render를 실행합니다.hyperframes-prompt-builder— 매트릭스가hyperframes로 해석될 때video-prompt-builder가 선택합니다.
8단계 — 검증
- 아래 테스트를 통해
.specs/architecture/PROVIDERS.md를 파싱하고motion-typography,data-viz-reel,programmatic-short가 모두hyperframes로 해석되는지 확인합니다. npm run typecheck실행 — 변경 사항과 관련 없는 기존 실패(예:@types/node누락)는 수용합니다. 제공자 레이어를 참조하는 새로운 TS 오류가 있으면 실패합니다.- 저장소에
.env가 있으면npm run router:check실행; 그렇지 않으면 건너뜁니다(스크립트는.env를 요구하며 통합 형태와 무관합니다). git status가 예상 파일만 표시하는지 확인합니다.
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
console.error('MISSING:', key); process.exit(1);
}
}
console.log('PROVIDERS.md OK');
"
9단계 — 커밋 및 푸시
- 이 스킬이 건드린 파일만 정확히 스테이징합니다. 절대
git add -A하지 마십시오. - 표준 메시지로 커밋합니다:
그리고 3단계 계약 실행을 설명하는 본문을 추가합니다(병합된 참조 커밋의 문구 참조).feat(skills): wire HyperFrames as a video provider origin <branch>에 푸시합니다. 브랜치에 PR이 없으면 초안 PR을 엽니다.
출력
branch: 문자열. 커밋을 보유한 브랜치.pr_url: 문자열. 생성되었거나 이미 존재하는 초안 PR URL.files_written: 실제 생성되거나 수정된 상대 경로 배열.files_skipped_idempotent: 이미 올바른 상대 경로 배열.verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }.
불가침 규칙
- 멱등적. 이미 통합된 저장소에서 다시 실행하면 파일을 전혀 건드리지 않습니다.
- 절대
main에 커밋하지 않습니다. 먼저 기능 브랜치를 생성하십시오. 엔진의 브랜치 정책은 상위에서 적용됩니다. - 스킬 본문은 계약 외부에서
hyperframes를 언급하지 않습니다. 제공자 선택은 여전히PROVIDERS.md+lib/router.ts를 통해 이루어집니다. 이 스킬은 부트스트랩입니다. 런타임 선택은 제공자에 무관합니다. - 렌더링된 MP4 또는
outputs/아래의 파일을 편집하지 마십시오. 이 스킬은 엔진 배관만 변경합니다. - 기존
compliance-<활성 클라이언트>스킬 또는 클라이언트별 아티팩트를 절대 삭제하지 마십시오. 통합은 추가적입니다.
실패 모드
- 1단계 사전 점검 실패(marketing-engine 저장소 아님): 누락된 파일을 표시하고 중지합니다. "수정"하려고 시도하지 마십시오.
- 파일이 이미 충돌하는 내용으로 존재하는 경우(예:
.skills/hyperframes/SKILL.md가 수동 편집됨): 표준 내용과 비교하여 차이점을 표시하고, 덮어쓰기 전에 운영자에게 문의합니다. npm run typecheck가lib/providers/에 새로운 TS 오류를 보고하는 경우: 중지하고 오류를 표시하며 커밋하지 않습니다.git push가 네트워크 이외의 이유로 실패하는 경우: 중지합니다. 네트워크 실패는 프로젝트의 git 정책(2초, 4초, 8초, 16초 백오프, 최대 4회 시도)에 따라 재시도됩니다.
관련 스킬
hyperframes: 런타임 제작(이 스킬에 의해 2단계에서 설치됨).hyperframes-cli: 런타임 lint/inspect/render(이 스킬에 의해 2단계에서 설치됨).hyperframes-prompt-builder: 런타임 전문가(이 스킬에 의해 2단계에서 설치됨).video-prompt-builder: 이 스킬에 의해 3단계에서 업데이트되는 디스패처.llm-router: 관련 없음. LLM 제공자 라우팅은 별도의 디스패처입니다.
참조 아티팩트 세트
이 스킬이 쓰는 모든 파일의 표준 내용은 main의 병합된 커밋에 있습니다:
- 스킬:
.skills/hyperframes/SKILL.md,.skills/hyperframes-cli/SKILL.md,.skills/hyperframes-prompt-builder/SKILL.md - 제공자 레이어:
lib/providers/types.ts,lib/providers/matrix.ts,lib/providers/video.ts,lib/providers/__mocks__/video.ts - 라우팅 매트릭스:
.specs/architecture/PROVIDERS.md - 환경:
.env.example - 헌장:
CLAUDE.md
의심스러우면 병합된 참조 커밋의 origin/main과 비교하고 표준 버전을 그대로 복사하십시오. 기억에 의존하여 다시 입력하지 마십시오.
상위 참조
- HyperFrames: https://github.com/wesleysimplicio/hyperframes
- 프로젝트 스킬 카탈로그: https://github.com/wesleysimplicio/hyperframes/tree/main/skills