소스 재구성
비디오의 모든 픽셀과 모든 문장은 나중에 코드와 대조 검증되므로, 코드는 반드시 올바른 코드여야 합니다. 이 스킬이 만들어진 프로덕션 환경에서는 메인 프론트엔드 체크아웃(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. 프로덕션임을 증명하기
브랜치 이름은 증거가 아닙니다. 프로덕션이란 배포 파이프라인이 마지막으로 빌드한 것입니다. 화면을 매핑하기 전에, 다음 우선순위에 따라 어떤 커밋이 라이브인지 확인하세요:
- 릴리스 기록: 릴리스 태그, 배포 로그, 배포 저장소의 "마지막으로 배포된 sha" 파일.
- 배포 파이프라인 구성: 어떤 브랜치에서 빌드하는지, 빌드 인자(환경 변수는 브랜딩을 바꾸거나 기능을 숨길 수 있음).
- 팀이 배포되었다고 확인한 가장 최신 브랜치.
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) 파일은 실제 고객 이름을 포함할 수 있습니다. 그 구조는 인용하고 값은 인용하지 마세요.