Communitygithub.com

소스 재구성 및 화면 매핑 스킬

제품의 소스 코드(read-only export)를 특정 커밋으로 고정하고, 해당 커밋이 실제 프로덕션에 배포된 코드임을 확인한 후, 비디오 브리프의 모든 화면을 라우트, 컴포넌트, i18n 문자열 및 상태와 매핑하여 SOURCES.md에 기록합니다.

소스 재구성 및 화면 매핑 스킬란 무엇인가요?

이 스킬은 AI 에이전트가 비디오 제작을 위해 제품 코드의 정확한 버전을 참조할 수 있도록 설계되었습니다. "소스 재구성(Source Recon)"은 크게 네 단계로 작동합니다. 첫째, 제품 저장소의 소스 코드를 읽기 전용으로 내보내고(export) 특정 커밋을 고정(pin)하여 `sources.lock`에 기록합니다. 둘째, 배포 파이프라인 구성, 릴리스 태그, 팀 확인 등을 통해 고정된 커밋이 실제 프로덕션 환경에 배포된 코드와 일치함을 증명합니다. 셋째, 비디오 브리프의 각 화면과 상태를 독립적인 읽기 전용 Explore 서브에이전트를 병렬로 실행하여 해당 화면의 라우트, 페이지 및 자식 컴포넌트, i18n 문자열, 상태(플래그, 게이트, 권한 등)를 찾고 인용(citation)과 함께 반환합니다. 넷째, 모든 결과를 하나의 비디오 당 하나의 `SOURCES.md` 파일로 정리합니다. 이 스킬은 코드가 변경된 후 영향을 받는 비디오를 식별하고 소스를 새로고침(refresh)하는 기능도 제공합니다. 사용자는 절대 기존 저장소의 작업 트리를 변경하지 않으며 오직 읽기 전용 작업만 수행하므로 안전합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/source-recon

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

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

문서

소스 재구성

비디오의 모든 픽셀과 모든 문장은 나중에 코드와 대조 검증되므로, 코드는 반드시 올바른 코드여야 합니다. 이 스킬이 만들어진 프로덕션 환경에서는 메인 프론트엔드 체크아웃(checkout)이 프로덕션보다 약 두 달 뒤쳐져 있었고, 현재 코드는 아무도 3일 동안 보지 않은 다른 작업 트리(worktree)에 있었습니다. 아무도 알아차리기 전에 한 비디오의 세 가지 버전이 예전 코드로 재구성되었습니다. 이 스킬은 그런 일이 다시는 발생하지 않도록 존재합니다: 먼저 소스를 고정(pin)하고, 그것이 프로덕션임을 증명한 다음, 화면을 파일에 매핑하세요.

읽기 전용으로 작업하세요. 코드를 읽기만 하고, 사용자 저장소에서 편집, 체크아웃, 페치(fetch) 또는 작업 트리 생성 등을 절대 수행하지 마세요. 사용자의 작업 트리에는 커밋되지 않은 작업이 있을 수 있으며, 체크아웃이나 페치는 사용자가 요청하지 않은 상태를 변경합니다.

1. 소스 고정하기

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/fetch_sources.py" <product_dir>

product.yaml의 sources: 항목을 읽고 역할(role)별로 다음을 수행합니다:

  • url:: 브랜치를 sources/.git-cache/<role>.git에 얕은 클론(shallow-clone)하고 내보냅니다(export).
  • path: (git 저장소): <branch>와 origin/<branch> 중 더 최신 커밋을 git archive로 내보냅니다. 로컬 브랜치가 origin보다 뒤쳐져 있거나 분기(diverge)된 경우, origin refs를 일주일 이상 전에 가져온(fetch) 경우, 동일 저장소의 다른 작업 트리가 내보내기보다 더 최신인 경우 경고합니다.
  • path: (git 저장소 아님): 파일의 해시로 복사 및 고정됩니다("pinned": false이므로 인용이 경고 없이 오래될 수 있습니다. git 소스를 선호하세요).

내보내기는 sources/<role>/에 읽기 전용으로 저장되며 sources.lock에 커밋이 기록됩니다. 디스크에 없는 잠긴 역할(제품 저장소를 새로 클론한 경우)은 잠긴 커밋으로 복원되므로 인용이 계속 같은 줄을 가리킵니다. 출력된 모든 note: 줄을 읽고 진행하기 전에 조치하세요. 각 노트는 내보내기가 프로덕션이 아닐 수 있는 이유입니다.

모든 하위 스트림(downstream) 인용은 <role>/<path>:<line>@<short sha> 형식을 사용하며, 경로는 저장소 루트 기준(sources/<role>/<path>가 존재함)이고 sha는 잠긴 값입니다.

2. 프로덕션임을 증명하기

브랜치 이름은 증거가 아닙니다. 프로덕션이란 배포 파이프라인이 마지막으로 빌드한 것입니다. 화면을 매핑하기 전에, 다음 우선순위에 따라 어떤 커밋이 라이브인지 확인하세요:

  1. 릴리스 기록: 릴리스 태그, 배포 로그, 배포 저장소의 "마지막으로 배포된 sha" 파일.
  2. 배포 파이프라인 구성: 어떤 브랜치에서 빌드하는지, 빌드 인자(환경 변수는 브랜딩을 바꾸거나 기능을 숨길 수 있음).
  3. 팀이 배포되었다고 확인한 가장 최신 브랜치. git worktree list, 브랜치 날짜 및 merge-base와 대조.

정확한 명령어와 함정(오래된 원격 refs, 기능 플래그, 렌더링을 변경하는 빌드 인자)은 references/freshness.md를 읽으세요. 프로덕션 커밋을 확인할 수 없으면 SOURCES.md 상단에 "production commit unconfirmed"라고 말하고 사용자에게 권장 답변이 있는 하나의 폐쇄형 질문을 하세요. 예: "origin/develop(가장 최신, main 포함)을 프로덕션으로 내보낼까요? 권장: 예, 배포 워크플로우가 이것을 빌드합니다."

사용자가 다른 브랜치를 확인하면 product.yaml의 branch:를 변경하고 fetch_sources.py <product_dir> --refresh --role <role>을 실행하세요(비디오가 이미 이 소스를 인용하고 있다면 먼저 changed_since.py를 실행하세요, 섹션 6).

3. 각 화면 매핑하기

비디오의 BRIEF.md(챕터)와 COVERAGE.md에서 화면과 상태를 가져오세요. 화면당 하나 또는 컴포넌트를 공유하는 작은 화면 그룹당 하나의 읽기 전용 Explore 서브에이전트를 병렬로 실행하세요. 각 서브에이전트에게 references/recon-prompt.md의 프롬프트를 주고, sources/<role>/(고정된 export, 사용자의 체크아웃이 아님)을 가리키도록 하여 반환되는 모든 줄 번호가 잠금과 일치하도록 하세요.

각 서브에이전트는 인용과 함께 다음을 반환합니다: 라우트, 페이지 및 자식 컴포넌트(템플릿, 로직, 스타일 파일), 비디오 언어의 i18n 키와 정확한 문자열, 무엇이 렌더링되는지를 결정하는 상태(기본값, 플래그, 기능 게이트, 빈 상태, 권한 검사), 사용 중인 아이콘 세트와 에셋, 그리고 미출시, 게이트 또는 제한된 것으로 보이는 모든 것.

그런 다음 직접 프로덕션과 복사본을 대조 확인하세요: 화면당 두세 개의 문자열을 참조 자료(녹화본, 복구된 캡처, 문서)와 대조하세요. 다른 문자열은 export가 프로덕션이 아니거나 화면이 플래그 뒤에 있음을 의미합니다. SOURCES.md를 작성하기 전에 해결하세요.

4. SOURCES.md 작성하기

비디오당 하나의 파일, videos/<video>/SOURCES.md:

# Sources: <video>

Locked: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Production: confirmed by <release tag v4.2.0 | deploy workflow builds main | team confirmation>

| screen | route | components | citation |
|---|---|---|---|
| Board, empty | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |

## Board, empty
- Strings: `board.empty.title` "Nothing planned yet" (frontend/src/i18n/en.json:88@1a2b3c4)
- State: renders when `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Icons: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Flags or gates: none found
- Not found: <the brief needs but the code does not have>

## No-code references
<what exists for each screen without code, see section 5>

인용이 없는 화면은 비디오에 포함되지 않습니다. "Not found" 아래에 나열하고 사용자에게 알리세요; 화면을 지어내는 것은 리뷰어가 용서하지 않는 유일한 실수이며, 존재하지 않는 제품을 보여주기 때문입니다.

5. 코드 없는 참조 나열하기

코드가 표시할 수 없는 화면(서드파티 UI, 런타임 출력, 저장소에 없는 백엔드, 또는 프론트엔드 코드가 전혀 없는 경우)의 경우, 다음 우선순위로 사용 가능한 것을 나열하세요: references/의 분석된 화면 녹화, 과거 세션 기록에서 복구 가능한 캡처, 프로덕션처럼 빌드된 앱의 로컬 인스턴스, 공개 문서 및 스크린샷. 여기서 직접 캡처하지 마세요; 그것은 ui-reference-capture의 역할입니다. 리뷰어의 개인 브라우저에 의존하지 마세요.

6. 코드가 변경될 때

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]

각 잠긴 커밋을 현재 브랜치 헤드와 비교하고, 변경된 파일을 인용하는 모든 비디오(및 킷 파일)의 SOURCES.md, TRUTH.md, 스펙 또는 video/src/를 나열하며, 정확한 줄이 변경된 인용을 표시합니다. 아무것도 이동하지 않습니다. --refresh 전에 실행하세요: 잠금과 헤드를 비교하고, 새로고침(refresh)은 둘을 동일하게 만들므로 이후 변경 목록이 사라집니다(스크립트는 대신 힌트를 출력합니다). 사용자에게 그 목록을 보여준 다음, 새 코드를 원하면 fetch_sources.py --refresh를 실행하고, 영향을 받는 화면에 대해 ui-spec-from-code를, 영향을 받는 줄에 대해 product-truth를 다시 실행하세요. 변경된 것을 인용하지 않는 비디오는 그대로 둡니다.

규칙과 이유

  • Export를 읽고, 잠금을 인용하세요. 다른 체크아웃의 줄 번호는 다음 새로고침 후 조용히 잘못된 코드를 가리킵니다.
  • 코드에서 발견한 비밀을 절대 인쇄하지 마세요. 프론트엔드는 종종 키와 토큰을 보관합니다. 파일과 줄만 보고하고, 사용자에게 보안 발견 사항으로 처리하세요.
  • 미출시, 게이트 또는 제한된 기능도 사실입니다. SOURCES.md에 표시하세요(gate: <flag>, restricted: <who sees it>). product-truth는 비디오가 이를 표시할 수 있는지 결정하며, 일반적으로 리뷰어의 승인이 필요합니다.
  • 실제 데이터는 제외하세요. 저장소의 픽스처(fixtures)와 시드(seed) 파일은 실제 고객 이름을 포함할 수 있습니다. 그 구조는 인용하고 값은 인용하지 마세요.

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

관련 스킬