video-qa은(는) 무엇을 하나요?
데모 MP4를 의도된 스토리보드와 비교하여 예리한 사람 리뷰어가 작성할 타임스탬프 체크리스트를 반환합니다. 두 계층으로 구성됩니다: 결정론적 프로브(ffmpeg/ffprobe/node — 모델 추론 없이 기계적 감지)와, 프로브의 컴팩트 JSON 보고서 + 스크립트 대비 추출된 일부 프레임을 기반으로 추론하는 분석 하위 에이전트(fresh analysis subagent).
중요 규칙: 분석은 항상 새로운 하위 에이전트에서 실행
호출자(주 스레드의 사용자)는 최소한만 수행합니다:
- 입력을 찾습니다.
- 프로브 스크립트를 실행합니다.
- 분석을 수행할 새로운 독립 하위 에이전트(
Agent도구)를 생성합니다. - 하위 에이전트의 이슈 목록을 사용자에게 전달합니다.
호출자 스레드에서 추출된 프레임을 읽거나 보고서에 대해 추론하지 마십시오. 핵심은 토큰 격리입니다. 5분 동영상은 ~50개의 프레임과 큰 JSON 보고서를 생성하며, 이를 추론하는 데는 수만 개의 이미지 + 분석 토큰이 소모됩니다. 이것이 호출자의 컨텍스트에 들어가면 세션의 나머지 부분을 오염시킵니다. 하위 에이전트가 이를 흡수하고 짧은 이슈 목록만 반환합니다. 이것은 선택 사항이나 "편할 때"가 아닙니다. 모든 video-qa 호출은 작업을 위임합니다. 참고: references/handoff.md.
1단계 — 입력 수집
다음이 필요합니다:
- 동영상 경로 — QA할 MP4 (리뷰어가 볼 최종 편집본).
- 스토리보드 / 스크립트 — 원하는 비트 순서, 타이밍 예상, 각 세그먼트가 보여줘야 하는 내용. 사용자가 제공하지 않았다면 요청하십시오(또는 해당 이슈 또는
demo-video스토리보드). 비트를 임의로 만들지 마십시오. - 예상 카드 — 스크립트에 명시된 카드(표지, 아젠다, 각 인트로, 요약)를 순서대로. 작은 JSON 파일(
--cards-file용)로 작성:{ "label": "표지 (제목 + 부제목)" }항목 배열 (텍스트가 많은 카드의 읽기 시간 기준을 재정의하려면"minRead": <초>추가). 이는 결정론적 카드 교차 검증을 구동하며, 카드는 작성된 내레이션이므로 일급 출력입니다. - 브랜딩 — 카드/배경 색상 및 커서/주석 색상. 프로브가 브랜드 카드를 분류하고 하위 에이전트가 대비를 확인할 수 있도록 합니다. 지정되지 않은 경우 기본값: 사용자에게 질문하십시오. 브랜드를 추측하지 마십시오.
2단계 — 결정론적 프로브 실행
node ${CLAUDE_PLUGIN_ROOT}/skills/video-qa/scripts/probe.mjs \
--video "<절대/경로/동영상.mp4>" \
--out "<작업디렉토리>/video-qa-report.json" \
--frames-dir "<작업디렉토리>/video-qa-frames" \
--card-rgb 15,81,255 \ # 브랜드 카드 색상 (R,G,B) (예: #0F51FF)
--cards-file "<작업디렉토리>/cards.json" # 예상 스토리보드 카드 (순서대로)
사용자 저장소 대신 스크래치/임시 <작업디렉토리>(/tmp 등)를 사용하십시오. 프로브는 JSON 보고서와 제한된 프레임 세트를 작성하고 보고서 경로를 출력합니다. 전체 동영상에 대해 세 가지 필터 패스(프레임 고정, 장면 전환, 움직임)와 장면별 샘플링을 실행하며, 예상 시간은 동영상 길이의 약 1~1.5배입니다. 튜닝 가능(모두 선택 사항, 합리적인 기본값 내장): --card-tol, --demo-freeze, --annot-freeze, --card-min-read (읽기 시간 기준, 2.5초), --annotate-rgb R,G,B — 주석 강조 색상. 이 색상의 "여기 보세요" 주석 링이 있는 무음 영역은 의도적인 페이싱(annotated: true)으로 처리되어 헤드라인 무음 수에서 제외되며 결함으로 플래그되지 않습니다. 각 감지기가 측정하는 항목과 임계값이 설정된 이유는 references/detectors.md를 참조하십시오.
주석 감지는 무음 영역으로 범위가 제한되므로 annotatedRegionCount: 0이 "동영상에 주석 없음"을 의미하지는 않습니다. 링은 고정/정지된 구간과 일치할 때만 등록됩니다. 편집 시 무음이 제거되거나 링이 움직임 위에 재생되면 링이 여전히 화면에 렌더링되지만 무음 영역이 없으므로 개수는 구조적으로 0입니다. 해당 숫자만으로 주석이 누락되었다고 보고하지 마십시오. 비트가 무언가에 링을 걸도록 스크립트되었다면 해당 세그먼트의 프레임(장면별 span-* 프레임 또는 주석 타임스탬프에서 프레임 추출)으로 확인하십시오.
인계 전에 출력된 요약(구간 수, 무음 영역, 글리치 수, 프레임 수, cardCheck.countMatches)을 sanity check 하십시오. cardSpans가 0이면 --card-rgb가 잘못된 것이므로 수정하고 다시 실행하십시오. 그렇지 않으면 모든 카드가 ui로 읽히고 프레임 고정/무음/카드 분류가 무의미해집니다. cardCheck에 수 불일치가 표시되면 이는 프로브 오류가 아니라 실제 발견 사항(카드 누락 또는 초과)이므로 하위 에이전트가 프레임을 통해 확인하도록 하십시오.
3단계 — 분석 하위 에이전트로 인계
Agent 도구(subagent_type: general-purpose)를 사용하여 새 하위 에이전트를 생성하십시오. references/analysis-prompt.md에서 프롬프트를 빌드하고 다음을 대체하십시오:
{{REPORT_PATH}}→ 2단계의--out경로.{{FRAMES_DIR}}→--frames-dir경로.{{OUT_FINDINGS}}→ 읽을 결과 파일 경로 (예:<작업디렉토리>/video-qa-findings.md).{{STORYBOARD}}→ 1단계의 의도된 비트, 그대로.{{BRANDING}}→ 1단계의 브랜딩 규칙.
초기 프롬프트의 명시적 지시사항으로 하위 에이전트에게 자신의 차례 마지막 단계로 {{OUT_FINDINGS}}에 결과를 작성하도록 지시하십시오. 해당 파일을 읽는 것이 신뢰할 수 있는 검색 경로입니다. 생성된 에이전트의 최종 텍스트 메시지가 항상 호출자에게 전달되는 것은 아니며, 후속 "결과를 보내주세요" 핑은 종종 유휴 상태인 에이전트에 도달하여 다시 응답하지 않습니다. 파일에는 이슈 목록만 포함되므로(프레임 없음) 토큰 격리를 깨지 않습니다. 하위 에이전트는 여전히 보고서와 프레임을 읽고 비트별로 추론하며, 결과를 읽을 수 있는 파일에 저장합니다.
4단계 — 전달
결과 파일({{OUT_FINDINGS}})을 읽고 이슈 목록을 사용자에게 그대로 전달하십시오(이미 전달 가능한 형식입니다). 프레임에 대한 자신의 추론은 아무것도 추가하지 마십시오. 설계상 전혀 보지 않았습니다. 사용자가 브랜드 HTML 아티팩트를 원한다면 별도의 후속 작업입니다.
"확인 불가" 항목을 결함으로 처리하기 전에 점검하십시오. 프로브는 제한된 프레임 세트(수십 개, 모든 프레임 아님)를 샘플링하므로 실제로 발생한 비트가 샘플 사이에 떨어져 "확인 불가" 또는 "페이지 이동됨/표시되지 않음" 플래그로 반환될 수 있습니다. 이는 샘플링 간격이며 실제 부재가 아닙니다. 이러한 항목 중 가장 잘못 판단되기 쉽습니다. 각 항목에 대해 해당 비트가 발생해야 하는 정확한 타임스탬프에서 몇 개의 프레임을 추출하고(예: ffmpeg -ss <t> -i video.mp4 -frames:v 1 …) 결함으로 보고하기 전에 직접 확인하십시오. 전체 동영상에 실제로 없는 것만 보고하십시오. 존재가 확인된 비트는 샘플 세트 외부에서 검증되었음을 표시하는 ✅로 다운그레이드하십시오.
감지되는 항목 (및 감지되지 않는 항목)
- 신뢰할 수 있고 기계적인 것: 무음/고정 UI 영역(움직임 밀도 스캔), 장면/세그먼트 구조, 브랜드 카드 대 UI 분류, 글리치 클러스터(이상한 새로고침/페이지 이동 깜빡임), 전체 대비/휘도 통계.
- 제한된 프레임에 대한 하위 에이전트 추론: 스크립트 외부의 배관 UI(관리자 대시보드, 로그, 오류 추적) — 비트 사이와 세그먼트 중간의 짧은 로그인/로딩/빈 화면/관리자 플래시를 포함하며, 이는 허용 가능한 전환이 아닌 정제 결함으로 처리됩니다. 과도한 편집/하드 컷(무음 제거가 실제 움직임을 자름 — 커서가 이동 없이 순간이동, 페이지 전환이 하드 점프로 스냅, 중간 동작에서 컷)은 가짜로 읽힙니다. 비트 누락/잘못됨. 탐색 스타일을 일급 검사 항목으로 (제품을 탐색한 vs 딥 페이지로 바로 이동). 카드는 단순한 존재 여부가 아니라 제대로 보이는지(가독성 있는 지속 시간, 모순되거나 빈 이웃에 의해 방해되지 않는지)에 따라 평가되며, 표지와 아젠다 카드는 내용으로 구분됨. 잘못된 화면 데이터(개수, 깨진 행). 누락된 주석. 브랜딩/대비 문제.
- 사각지대: 활성 영역 중 누락된 화면 캡션(로딩 애니메이션은 움직임으로 읽힘), 작업이 실제로 실패했는지 편집으로 프레임 밖으로 잘렸는지 여부. 하위 에이전트는 이를 "확인 불가"로 표시합니다.
references/validation-notes.md에는 이 스킬이 참조 픽스처의 사람이 검토한 황금 목록에 대해 어떻게 점수를 매겼는지 기록되어 있습니다.