HyperFrames 탐구 2 — 에이전트가 주 저자, 사람은 디렉터가 되는 설계
1편에서 파이프라인을 훑으며 "Claude가 문서를 쓰고 HTML을 작성한다"고 여러 번 말했습니다. 이번 편의 질문은 이겁니다. 도구가 어떻게 생겨야 AI 에이전트가 그 일을 잘할 수 있는가?
HyperFrames의 답은 역할 뒤집기입니다. 사람이 짠 코드를 에이전트가 보조하는 게 아니라, 에이전트가 주 저자(author)이고 사람은 디렉터입니다. 디렉터는 의도를 문서로 못 박고, 에이전트는 그 문서에 그라운딩된 결과물을 쓰고, 기계가 검증합니다. 이 구조를 받치는 장치들을 하나씩 봅니다.
먼저: 이 도구를 손에 넣는 두 가지 방법
본론에 앞서, 스터디 과정에서 정리한 실행 방식 비교입니다. 같은 hyperframes preview 명령이 어디서 실행되느냐가 완전히 다릅니다.
| 항목 | npx hyperframes ... |
git clone → bun install → bun run build |
|---|---|---|
| 코드 위치 | ~/.npm/_npx/<hash>/ (시스템 캐시) |
본인 지정 디렉토리 |
| 포함 내용 | 빌드된 dist/만 (~395MB, 소스 없음) |
소스 + 테스트 + docs + CI 전체 (수 GB) |
| 업데이트 | npm 레지스트리 자동 반영 | git pull 수동 |
| 디버깅 | 어려움 — minified 번들, 스택 트레이스가 cli.js:1772 |
쉬움 — TS 소스맵, studioServer.ts:187처럼 정확한 라인 |
| 수정/PR | 불가 | 자유 (dev 모드는 수정 → 저장 → 즉시 반영) |
정체성이 명확합니다. "비디오를 만들고 싶다"면 npx, "도구를 이해하고 고치고 싶다"면 clone. 이 시리즈처럼 내부를 뜯어보는 스터디라면 당연히 후자입니다 — bun run --cwd packages/cli dev preview ...로 TS 원본을 직접 실행하면서요.
전체 그림: 네 개의 레이어
에이전트가 읽고 쓰는 프로젝트 디렉토리는 담당자별로 깔끔하게 나뉩니다.
┌────────────────────────────────────────────────┐
│ AI 에이전트 (Claude Code) │
│ [Skills 시스템 — /hyperframes 등 자동 발동] │
└────────────────────────────────────────────────┘
│ 읽기 ▲ 쓰기
┌────────────────────────────────────────────────┐
│ videos/<project>/ │
│ │
│ [사람이 정의 — 의도/제약] │
│ DESIGN.md, SCRIPT.md, STORYBOARD.md │
│ │
│ [캡처 — 외부 입력] │
│ capture/CLAUDE.md, AGENTS.md, tokens.json, │
│ screenshots/*.png │
│ │
│ [에이전트가 작성 — 실행 가능한 출력] │
│ index.html, compositions/beat-*.html │
│ │
│ [CLI 자동 생성 — 검증/렌더 결과] │
│ transcript.json, renders/, snapshots/ │
└────────────────────────────────────────────────┘
의도는 마크다운, 출력은 HTML, 검증 결과는 JSON — 의도(.md) ↔ 출력(.html) ↔ 검증(.json)의 사이클이 이 시스템의 뼈대입니다.
장치 1: 스킬 — 워크플로우를 압축해 자동 발동
npx skills add heygen-com/hyperframes를 실행하면 .claude/skills/hyperframes/에 SKILL.md, house-style.md, 참조 문서들이 배치되고, 세션 시작 시 자동 로드됩니다.
| 스킬 | 자동 발동 트리거 |
|---|---|
/hyperframes |
"비디오 만들어줘", "scene 3 타이밍 고쳐" |
/hyperframes-cli |
"init", "lint", "render", "preview" |
/hyperframes-media |
"TTS 생성", "받아쓰기", "배경 제거" |
/website-to-hyperframes |
URL 붙여넣기 + "이걸로 영상 만들어줘" |
/gsap, /three, /lottie 등 |
해당 라이브러리 코드 발견 시 |
사용자가 "perso.ai 사이트로 영상 만들어줘"라고 치면 트리거가 인식되고, 스킬이 7단계 파이프라인을 안내하고, 각 단계에서 적절한 도구(Bash, Edit, Write)가 호출됩니다. 워크플로우 지식이 사람의 머리가 아니라 스킬 파일에 압축되어 있는 것입니다.
장치 2: 앵커 문서 — 에이전트는 결정하지 않는다, 추출한다
LLM에게 영상을 맡길 때 가장 무서운 건 즉흥성입니다. 브랜드 보라색이 매번 조금씩 다른 보라색이 되는 것이요. HyperFrames는 이를 **앵커 문서(anchor documents)**로 차단합니다.
DESIGN.md — 브랜드 룩의 SoT. 스킬이 "design.md가 있으면 가장 먼저 읽어라"라고 명시합니다.
## Colors
- **Brand Violet (CTA / Accent)**: `#624AFF`
- **Primary Surface**: `#0E0F11` — near-black void background
## Do's and Don'ts
- Sit every scene on `#0E0F11`
- Use violet exclusively for CTA, not decoration
#624AFF는 그대로 쓰고(임의 보라색 금지), "Don'ts" 섹션은 자동 체크리스트가 됩니다.
SCRIPT.md — 내레이션의 SoT. 본문이 그대로 TTS 입력이 되고, Voice mood: confident, calm, premium 같은 지시가 음성 선택(af_nova)을 결정합니다.
STORYBOARD.md — 연출의 SoT. 리듬 패턴(silence → REVEAL → BUILD → flow → resolve)이 GSAP 이징 곡선 선택으로, "Violet appears at most once per beat" 같은 가드레일이 코드 리뷰 기준으로 이어집니다.
핵심 원칙은 이겁니다. 에이전트는 색·폰트·타이밍을 "결정"하지 않고, 앵커 문서에서 "추출"합니다. 창의성이 필요한 결정은 문서를 쓸 때 한 번만 일어나고, 이후 모든 산출물은 그 결정을 참조합니다. 스킬의 "Prompt Expansion" 단계가 이를 한 번 더 굳힙니다 — 사용자 의도를 DESIGN.md + house-style.md에 그라운딩한 "확장된 스펙"을 만들어, 스토리보드 작성자·컴포지션 작성자·자막 작성자가 전부 같은 중간 산물을 읽게 합니다.
장치 3: capture/ — 에이전트가 외부 세계를 인식하는 방식
캡처 폴더의 안내 인덱스는 두 벌입니다. CLAUDE.md(Anthropic Claude용)와 AGENTS.md(Cursor, Codex 등 다른 에이전트용) — 내용은 같고, 어떤 에이전트가 와도 인식할 수 있게 양쪽 컨벤션을 다 따른 것입니다.
인덱스에는 읽기 순서까지 적혀 있습니다.
1. capture/CLAUDE.md → "asset-descriptions.md를 먼저 읽어라"
2. asset-descriptions.md → 각 이미지의 한 줄 설명
3. tokens.json → 색/폰트 확정 (DESIGN.md 작성용)
4. visible-text.txt → 헤드라인/CTA 발췌
5. screenshots/scroll-*.png → 멀티모달 — 색감·구도·톤
마지막 단계가 중요합니다. 텍스트로 표현 안 되는 정보(색감의 미묘함, 배치 균형, 사진 vs 일러스트 톤)는 에이전트가 스크린샷 PNG를 직접 읽습니다. 출력 방향도 마찬가지 — 렌더 결과 스냅샷을 다시 읽고 "beat 3의 70% 지점에서 폰트가 잘린다"를 스스로 발견해 수정합니다. 입력도 출력도 멀티모달 양방향입니다.
장치 4: HTML이 곧 데이터 모델 — data-* 스키마
에이전트가 읽고 쓰는 최종 산출물에는 별도 메타데이터 파일이 없습니다. HTML의 data-* 속성이 스키마입니다.
<div
data-composition-id="beat-2-title"
data-composition-src="compositions/beat-2-title.html"
data-start="5.0"
data-duration="6.0"
data-track-index="0"
></div>
에이전트는 이 HTML을 JSON 읽듯 읽습니다 — data-start로 타임라인을 정렬하고, data-duration으로 전체 길이를 계산하고, data-track-index로 겹침 가능 여부를 판단합니다. 파라미터화도 같은 방식입니다.
<html data-composition-variables='[
{"id":"title","type":"string","default":"STUDIO PERSO"},
{"id":"theme","type":"enum","default":"dark",
"options":[{"value":"dark"},{"value":"light"}]}
]'>
변수 스키마가 HTML 안에 자체 문서화되어 있으니, "같은 영상을 영어 버전으로"라는 요청이 오면 에이전트가 바꿀 수 있는 값을 스스로 인식합니다.
장치 5: 검증 루프 — 자기 출력을 자기가 디버깅한다
HTML 작성 직후 에이전트는 검증 도구를 돌립니다. lint(정적 분석) → validate(WCAG 대비 등 런타임 검증) → inspect(5개 시점 레이아웃 캡처, 텍스트 오버플로우 검출) → animation-map(GSAP tween Gantt 차트, "1초 이상 dead zone" 플래그).
포인트는 모든 검증 결과가 JSON·텍스트 리포트로 나온다는 것입니다. 사람이 읽으라고 만든 화면이 아니라 에이전트가 다시 읽으라고 만든 출력이라서, "작성 → 검증 → 리포트 읽기 → 수정"의 루프가 사람 개입 없이 돕니다.
원칙 정리
| 원칙 | 구현 |
|---|---|
| HTML이 SoT | 별도 IR 없음. data-* 속성이 모델 |
| 사람의 의도는 마크다운 | DESIGN / SCRIPT / STORYBOARD가 에이전트 입력 |
| 에이전트는 결정 안 함, 추출함 | 색·폰트·타이밍은 앵커 문서 참조 |
| 검증 자동화 | lint / validate / inspect 강제 |
| 멀티모달 양방향 | 입력 스크린샷 + 출력 스냅샷 모두 PNG |
| 스킬 = 워크플로우 압축 | 명시적 단계를 스킬 파일이 가르침 |
| 여러 에이전트 호환 | CLAUDE.md + AGENTS.md 양쪽 배치 |
더 깊이: "에이전트 친화적 설계"의 일반 원칙
HyperFrames의 장치들을 한 발 떨어져 보면, LLM 에이전트를 위한 도구 설계의 일반 원칙이 추려집니다. 다른 도메인에 그대로 이식할 수 있는 것들입니다.
- 점진적 공개(progressive disclosure) — 전체 가이드를 한 번에 컨텍스트에 넣지 않고, 인덱스(SKILL.md)만 상주시키고 상세는 필요할 때 lazy-load. 컨텍스트는 유한 자원입니다.
- 결정과 실행의 분리 — 취향이 개입하는 결정은 앵커 문서에 한 번만 기록하고, 실행 단계는 그 문서를 기계적으로 참조. LLM의 비일관성을 구조로 흡수하는 방법입니다.
- 산출물 자체를 스키마로 — 별도 메타데이터 파일 대신 산출물(HTML)에
data-*로 구조를 심으면, "산출물과 메타데이터가 어긋나는" 클래스의 버그가 사라집니다. - 기계가 읽을 수 있는 피드백 — 검증 결과를 사람용 UI가 아니라 JSON으로. 자기 수정 루프의 전제 조건입니다.
- 에이전트 중립 컨벤션 — CLAUDE.md와 AGENTS.md를 함께 두는 것처럼, 특정 에이전트에 락인되지 않는 인터페이스.
"AI가 쓰기 좋은 도구"란 결국 암묵지를 최소화하고, 모든 계약을 파일로 명시한 도구라는 결론이 나옵니다. 흥미롭게도 이건 신입 개발자가 온보딩하기 좋은 코드베이스의 조건과 정확히 같습니다.
한 줄 요약 — HyperFrames는 "의도는 마크다운, 출력은 HTML, 검증은 JSON"이라는 계약으로 에이전트를 주 저자로 세우고, 사람은 앵커 문서로 의도를 못 박는 디렉터 역할만 하도록 설계된 도구다.
스스로 점검할 질문
- 앵커 문서 없이 에이전트에게 "브랜드에 맞게 만들어줘"라고만 하면 어떤 문제가 생길까요?
data-composition-variables처럼 산출물에 스키마를 심는 방식의 장단점은 무엇인가요?- 여러분이 만드는 도구를 에이전트 친화적으로 바꾼다면, 위 5가지 원칙 중 무엇부터 적용하겠습니까?
참고 링크