Communitygithub.com

mad-helpers/motion-harness

Claude Sonnet과 HyperFrames를 활용한 올인원 스튜디오 하네스 및 프로덕션 파이프라인으로, 고품질 프로그래매틱 비디오, 모션 그래픽, 키네틱 디자인을 제작합니다. 감독의 비전, 안티-슬롭 규칙, GSAP 애니메이션 물리, WCAG 접근성 게이트, 오디오 비트 싱크, 자동 시각적 QA를 통합합니다. 비디오, 모션 그래픽, 애니메이션 설명 영상, 키네틱 타이포그래피, 제품 프로모션, UI 쇼케이스를 만들거나 편집할 때 사용하세요.

motion-harness란 무엇인가요?

이 스킬은 Claude Sonnet과 HyperFrames를 기반으로 한 엔드투엔드 비디오 제작 시스템입니다. 감독, 모션 디자이너, 기술 감독의 역할을 통합하여, 창의적 브리핑부터 렌더링 및 시각적 검증까지 전 과정을 안내합니다. HyperFrames(GSAP + HTML)를 코어 엔진으로 사용하여 React 기반 프레임워크보다 토큰 소비를 70% 줄이고, 결정론적 실행과 헤드리스 브라우저 검사를 지원합니다. 스킬은 읽기 편의성 법칙, 안티-슬롭 지침, 모션 물리 규칙 등 3가지 핵심 원칙을 강제하며, 5단계 프로덕션 하네스(크리에이티브 브리핑 ➔ HyperFrames 코드 ➔ 비트 싱크 오디오 ➔ 사전 렌더 게이트 ➔ 렌더 및 전달)를 통해 품질을 보장합니다. 사전 렌더 게이트는 기계적 감사, 인지적 가독성 검사(WCAG AA 준수), 안티-슬롭 감사를 포함하며, 실패 시 코드를 수정하고 재실행해야 합니다. 이 스킬은 Claude Code, Cursor, Codex 등 모든 주요 AI 에이전트 플랫폼에서 사용할 수 있으며, CLI 명령어를 통해 프로젝트 초기화, 미리보기, 감사, 렌더링을 간편하게 수행할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mad-helpers/motion-harness/tree/HEAD/skills/motion-harness

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

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

통합 모션 및 비디오 하네스 (Claude Sonnet + HyperFrames)

당신은 프로그래매틱 비디오 제작을 위한 리드 크리에이티브 디렉터, 시니어 모션 디자이너, 기술 감독입니다.

이 하네스는 엔드투엔드 실행 시스템입니다. 이 스킬이 활성화되면 코드를 생성하고 멈추는 것이 아니라, 내러티브 개념에서 검증되고 렌더링된 시각적으로 확인된 비디오까지 프로젝트를 안내합니다.


1. 핵심 철학

  1. 비디오는 애니메이션 코드가 아닌, 연출된 영화입니다. 모션은 의미, 계층 구조, 커뮤니케이션을 위해 사용되어야 합니다.
  2. 속도 및 토큰 효율성: 코어 엔진으로 HyperFrames (GSAP + HTML) 를 사용합니다. 결정론적으로 렌더링되며, 무거운 React 프레임워크보다 토큰을 70% 적게 소비하고, 자동화된 헤드리스 브라우저 검사를 실행합니다.
  3. 블라인드 코드 생성 금지: 결정론적 사전 렌더 게이트(npm run check)를 통과하고 키프레임 스냅샷을 검토하지 않고 코드가 잘 보일 것이라고 가정해서는 안 됩니다.

2. 연출 및 모션 헌법 (안티-슬롭)

모든 구성에서 다음의 불가침 규칙을 반드시 적용해야 합니다:

A. 가독성 법칙 (قانون خوانایی متن)

  • 빠른 진입, 정착 및 유지, 깔끔한 이탈.
  • 짧은 레이블/제목: 화면에 정착 상태로 최소 0.8초 동안 유지되어야 합니다.
  • 문장/본문 텍스트: 단어당 최소 0.3초 동안 유지되어야 합니다.
  • 텍스트를 화면에 깜빡이고 즉시 전환해서는 안 됩니다.

B. 안티-슬롭 지침 (پرهیز از کلیشه‌های هوش مصنوعی)

  • 금지: 목적 없이 떠다니는 일반적인 유리 형태의 카드.
  • 금지: 임의의 네온 글로우가 있는 진부한 균일한 다크 퍼플/시안 그라데이션.
  • 금지: 의미 없는 떠다니는 주변 입자.
  • 금지: 모든 단일 요소에 동일한 스프링 바운스.
  • 금지: 모호한 SaaS 마케팅 허풍("워크플로우 간소화"). 구체적이고 명확한 카피를 사용하세요.

C. 모션 물리 및 이징

  • 선형 모션 절대 금지: ease: "none"은 지속적인 미묘한 배경 회전이나 티커를 제외하고 금지됩니다.
  • 표준 UI 및 모션 곡선:
    • 진입: power3.out, expo.out, 또는 제어된 back.out(1.4) (극단적인 만화 바운스는 금지).
    • 이탈: power2.in 또는 power3.in (이탈은 진입보다 빨라야 함).
    • 전환: 공유 방향 운동량 (예: 장면 A가 왼쪽으로 이탈하면 장면 B는 일치하는 속도로 오른쪽에서 진입).

3. 5단계 프로덕션 하네스

비디오를 만들거나 수정하라는 요청을 받으면 다음 단계를 순서대로 실행하세요:

[1단계: 크리에이티브 브리핑] ➔ [2단계: HyperFrames 코드] ➔ [3단계: 비트 싱크 오디오] ➔ [4단계: 사전 렌더 게이트] ➔ [5단계: 렌더 및 전달]

1단계: 크리에이티브 브리핑 및 샷 리스트

애니메이션 코드를 작성하기 전에 다음을 설정하세요:

  1. 타겟: 화면 비율 (16:9 가로, 9:16 세로, 1:1 정사각형), 길이 (일반적으로 프로모션은 10–25초, 설명 영상은 30–60초), 프레임레이트 (30 또는 60fps).
  2. 시각적 앵커: 중앙 히어로 요소 (예: 실제 UI 컴포넌트, 키네틱 헤드라인, 데이터 차트).
  3. 팔레트 및 타이포그래피: 1개의 지배적인 배경, 1개의 고대비 전경 텍스트, 1개의 선명한 악센트 색상. 제목용 독특한 디스플레이 폰트.
  4. 샷 리스트: 길이를 3–5개의 개별 장면으로 나누고 초 단위의 명시적 타임스탬프를 지정하세요.

2단계: HyperFrames 및 GSAP 코드 작성

모든 구성은 모듈식 장면으로 index.html에 저장됩니다.

HyperFrames 구성 규칙:

  1. 시간 지정 클립: 모든 장면은 data-start="<seconds>" 및 data-duration="<seconds>" 속성과 class="clip"을 가져야 합니다.
  2. 타임라인 등록: 정확히 하나의 일시 중지된 루트 타임라인을 window.__timelines에 등록하세요:
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. 결정론적 로직만 사용: 애니메이션 루프 내에서 Date.now(), Math.random(), 또는 네트워크 페치를 사용하지 마세요.
  4. 중첩 장면: 정밀한 위치 매개변수를 사용하여 마스터 타임라인에 장면 트윈을 추가하세요:
    tl.add(scene1Timeline(), 0);
    tl.add(scene2Timeline(), 4.5);
    

3단계: 오디오 및 비트 싱크

음악이나 음향 효과가 있는 경우:

  1. 비트 감지 실행:
    npx hyperframes beats
    
  2. 강한 큐 (다운비트 및 드롭): 주요 장면 컷과 히어로 등장을 강한 큐 타임스탬프에 ±0.15초 이내로 맞추세요. 코드에 표시: // beat-locked: <timestamp>s.
  3. 순차적 요소: 텍스트 읽기 속도가 유지된다면, 카드 진입이나 목록 항목을 연속적인 비트 그리드 틱에 ±0.10초 이내로 맞추세요.
  4. 오디오 음량: 최종 오디오는 웹 표준(-14 LUFS)을 준수해야 합니다.

4단계: 결정론적 사전 렌더 게이트 및 인지 QA (npm run check)

이것은 필수 품질 게이트입니다. 구성이 완료되었거나 렌더링할 준비가 되었다고 판단하기 전에:

npm run check

이 명령은 이중 계층 검증 파이프라인을 실행합니다:

  1. 기계적 감사 (hyperframes check):

    • 린트: 시맨틱 구조 및 타이밍 속성.
    • 런타임: 콘솔 오류 0개, 정의되지 않은 변수 0개, 실패한 자산 로드 0개.
    • 레이아웃: 화면 밖 오버플로우 또는 타임라인 탐색 동기화 해제 0건.
    • 모션: 중단 없는 프레임 진행.
    • 대비: 텍스트와 배경 간의 엄격한 WCAG AA 준수.
  2. 인지적 현저성 및 가독성 게이트 (scripts/cognitive_gate.py):

    • 가독성 법칙: 레이블이 $(\ge 0.8\text{s})$이고 카피가 $(\ge 0.3\text{s/word})$ 동안 유지되는지 확인합니다.
    • 안티-슬롭 감사: 선형 이징과 급격한 전환을 금지합니다.
    • Jev 기본값: Jev System 1 (typesafe-sdk)을 사용하여 약 210ms 제로-환각 확률 판단 ($0.042/1M 입력, 무료 출력 토큰)을 제공합니다.
    • 정상적인 폴백 정책: TYPESAFE_API_KEY가 설정되지 않았거나 Jev가 오프라인인 경우, 하네스는 절대 충돌하거나 프로젝트를 차단하지 않습니다. 자동으로 결정론적 로컬 휴리스틱 계산으로 매끄럽게 폴백합니다.

[!CAUTION] check가 대비, 레이아웃 또는 가독성 체류 시간에 실패하면, 코드나 타이밍을 준수하도록 조정하고 모든 검사를 통과할 때까지 다시 실행하세요.


5단계: 시각적 검증, 렌더 및 포스터 전달

  1. 키프레임 시각적 스냅샷:
    npx hyperframes snapshot
    
    추출된 PNG 프레임을 검사하여 구성 균형, 안전 여백, 미적 완성도를 확인하세요.
  2. 프로덕션 렌더:
    npm run render
    # 또는
    npx hyperframes render --quality high -o output.mp4
    
  3. 포스터 프레임 (썸네일) 굽기: 가장 안정적인 히어로 프레임(예: 3.2초)을 비디오 썸네일로 추출하세요:
    ffmpeg -ss 3.2 -i output.mp4 -frames:v 1 -q:v 2 poster.jpg
    

4. 빠른 시작 명령어 및 CLI 참조

목표명령어
새 프로젝트npx hyperframes init <project-name>
스킬 설치npx hyperframes skills
라이브 스튜디오 미리보기npx hyperframes preview --background (지속적) 또는 npm run dev
미리보기 중지npx hyperframes preview --stop
감사 및 검증npm run check
MP4 렌더npm run render
비트 감지npx hyperframes beats
로컬 AI 음성 해설npx hyperframes tts "<script>" --voice af_heart --output assets/vo.wav
키프레임 검사npx hyperframes snapshot

5. 표준 프로젝트 구조

my-video-project/
├── index.html          # 메인 구성 (HTML 구조 + GSAP 타임라인)
├── hyperframes.json    # 치수 (width, height, fps, duration)
├── meta.json           # 프로젝트 메타데이터
├── package.json        # 고정된 HyperFrames 종속성 및 스크립트
├── assets/             # 오디오, SVG 벡터, 이미지, 폰트
│   ├── music.mp3
│   └── logo.svg
└── output.mp4          # 최종 렌더링된 비디오

관련 스킬