ref-researcher

Reference Researcher (ref-researcher)

개요

ref-researcher는 원시 영감(라이브 웹사이트, 디자인 갤러리, 앱 녹화, UI 스크린샷 또는 저장된 HTML)을 디자인 또는 코딩을 시작하기 전에 실행 준비가 된 주관적인 .md 디자인 및 제품 플레이북으로 변환합니다.

모바일 앱 기능, 웹 앱 플로우 또는 마케팅 웹사이트에서 외부 참고 자료의 시각적 장인정신, 모션 큐, 카피 패턴 및 안티패턴을 프로젝트의 실제 브랜드 토큰, 플랫폼 규칙 및 출시 범위를 손상시키지 않으면서 깊이 검사해야 할 때 이 스킬을 사용하세요.

종속성

이러한 설치된 스킬을 복제하지 않고 조정하여 사용하세요.

• uv — Python CLI 스크립트를 uv run을 통해 깔끔하게 확인하고 호출합니다(uv가 설치되지 않은 오프라인/stdlib 환경에서만 엄격하게 python3로 대체).
• chrome-devtools — JS가 많은 SPA를 렌더링하고, 라이브 레이아웃/애니메이션 동작을 검사하며, 정적 HTTP 요청이 클라이언트 측 셸(needs_browser_capture: true) 또는 제한된 사이트에 도달할 때 전체 페이지 스크린샷 또는 대화형 브라우저 세션을 캡처합니다.
• frontend-design — 웹 앱 또는 마케팅 웹사이트를 합성할 때 시각적 관점, 타이포그래피 페어링, 공간적 절제 및 안티템플릿 비평을 안내합니다.
• apple-hig-designer — 모바일 앱 기능 또는 기본 Apple 기기 쇼케이스를 합성할 때 기본 iOS/iPadOS/watchOS 컴포넌트 충실도, 안전 영역, 시트, Dynamic Type 및 접근성을 검증합니다.

빠른 시작

라이브 URL(공개 HTML/에셋을 가져오고 브라우저 스크린샷 캡처)에서 시작하거나 기존 로컬 참조 폴더에서 시작하세요.

# 1. 저장된 HTML 참조를 구조화된 JSON으로 추출
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./Docs/References & Inspo" \
  --limit 25 \
  --output "/tmp/ref_html_summary.json"

# 2. 매우 긴 스크린샷을 분할 + 비디오 키프레임을 스크래치로 추출 (1024px 너비)
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./Docs/References & Inspo" \
  --scratch-dir "/tmp/ref_slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/ref_media_manifest.json"

유틸리티 스크립트

모든 프로그래밍 방식의 추출, 분할, 정중한 HTTP 가져오기 및 링크 감사는 scripts/ref_researcher.py에 있습니다. 모든 명령은 **명시적인 제한과 --output <file.json>**이 필요하며(간결한 상태만 stdout에 기록).

1. fetch-page — 정중한 공개 URL 및 에셋 페처

공개 URL에서 정적 HTML과 최상위 스타일시트/이미지를 다운로드하고 로그인 장벽, 봇 챌린지 및 클라이언트 측 JS 셸(needs_browser_capture: true)을 감지합니다.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py fetch-page \
  --url "https://example.com" \
  --asset-dir "./refs/example" \
  --max-assets 20 \
  --output "/tmp/fetch_example.json"

2. extract-html — 코드, 카피, 타이포그래피 및 토큰 추출기

저장된 .html 및 .css 파일을 --limit까지 구문 분석하여 제목, 탐색 링크, H1-H3 계층 구조, CTA, 본문 카피 샘플, 16진수 색상, font-family 선언 및 애니메이션 라이브러리 큐(@keyframes, framer, gsap, lottie)를 출력합니다.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./refs" \
  --limit 25 \
  --output "/tmp/html_summary.json"

3. slice-media — 긴 스크린샷 및 비디오 키프레임 슬라이서

실제 이미지 픽셀 크기를 읽고(잘못된 확장명 처리, 예: .webp로 저장된 JPEG), 긴 전체 페이지 스크린샷을 선명한 1024px 너비 뷰포트 조각으로 분할하고, ffmpeg를 통해 균등한 간격의 MP4/MOV/WebM 키프레임을 추출합니다.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./refs" \
  --scratch-dir "<scratch_dir>/slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/slice_manifest.json"

작업 공간 위생: 항상 --scratch-dir을 대화 스크래치 디렉토리(또는 /tmp/)로 지정하고, 사용자의 저장소 작업 공간에는 절대 넣지 마세요.

4. verify-links — 플레이북 에셋 링크 감사자

생성된 .md 파일 내의 모든 상대 마크다운 링크를 디스크와 비교하여 검증하고, 경로가 깨진 경우 종료 코드 1로 종료합니다.

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py verify-links \
  --markdown "./Docs/References & Inspo/PLAYBOOK.md" \
  --markdown "./Docs/References & Inspo/README.md" \
  --output "/tmp/verify_links.json"

워크플로우

1. 먼저 대상 제품 및 제약 조건 감사

영감 링크를 열기 전에 대상 프로젝트의 진실 공급원 문서(PRD, 브랜드 색상/토큰, 디자인 시스템, 플랫폼 제약 조건)를 읽으세요. 기록하세요:

• 대상 표면: 모바일 앱 기능, 웹 앱 플로우 또는 마케팅 웹사이트.
• 시각적 토큰 및 대비 함정: 정확한 16진수 값 및 WCAG AA 최소값(예: 저대비 다크 모드 강조).
• 제품 진실 매트릭스: 오늘 출시와 로드맵 / 금지된 주장을 분리하세요.

2. 참고 자료 수집 (라이브 가져오기, 브라우저 캡처 또는 기존 폴더)

• 기존 로컬 참고 자료: 제공된 디렉토리에서 즉시 extract-html 및 slice-media를 실행하세요.
• 공개 URL / 처음부터 조사:
  1. 먼저 fetch-page를 실행하여 빠르고 속도 제한이 있는 정적 HTML + 에셋 캡처를 수행합니다.
  2. needs_browser_capture가 true인 경우(React/Next/Vite CSR 셸) 또는 전체 페이지 시각적 스크린샷이 필요한 경우 chrome-devtools 스킬(또는 브라우저 워크플로우)을 사용하여 전체 페이지 이미지/DOM을 렌더링하고 캡처합니다.
  3. 인증 / 차단된 사이트 프로토콜 (엄격): 사이트가 HTTP 401/403을 반환하거나 /login으로 리디렉션되거나 페이월/봇 장벽을 표시하는 경우:
     • 사용자에게 먼저 로그인을 요청한 다음 최대 2번 재시도합니다.
     • 2번 재시도 후에도 액세스가 여전히 실패하면 차단된 소스를 명확히 기록하고 자동으로 접근 가능한 공개 사이트/페이지 또는 동등한 대안으로 전환하여 모멘텀이 중단되지 않도록 합니다.

3. 시각적 및 프로그래밍 방식으로 검사 (긴 캡처를 맹목적으로 훑어보지 마세요)

• 전체 페이지 캡처(3840w × 15000px+)는 전체를 보면 읽을 수 없는 축소판으로 다운스케일됩니다. 항상 slice-media가 생성한 순차적인 뷰포트 조각을 수집된 모든 참고 자료와 extract-html의 추출된 카피/CSS 토큰에 걸쳐 검사하세요.
• 플랫폼 가이드와 함께 시각적 연구를 페어링하세요:
  • iOS/iPadOS 탐색, 시트, SF Symbols 및 터치/Dynamic Type 인체 공학에 대해 apple-hig-designer 큐를 호출합니다.
  • 웹 타이포그래피 대비, 의도적인 여백 및 AI 템플릿 기본값 제거에 대해 frontend-design 큐를 호출합니다.

4. .md 플레이북 합성

references/playbook_template.md를 따라 대상 프로젝트의 참조 폴더 안에 전달 가능한 플레이북을 작성하세요. 청사진을 대상 표면에 맞게 조정하면서 항상 다음을 포함하세요:

1. 제품 진실 및 제약 조건 매트릭스 (다크/라이트 대비 함정 포함)
2. 임원 크리에이티브 및 UX 방향
3. 아키텍처 / 화면-플로우 청사진
4. 상태 및 엣지 케이스 인벤토리 (비어 있음, 로딩/스트리밍, 부분/용량 초과, 오류/권한)
5. 플랫폼 및 반응형 변환 매트릭스
6. 타이포그래피, 표면, 모션 및 카피 규칙
7. 엄격한 DOS 및 DON'TS 배치에서 구체적인 긍정 및 부정 예를 인용
8. 색인된 참조 에셋 조회 테이블 (상대 마크다운 링크)
9. 사전 빌드 실행 및 QA 체크리스트

디렉토리의 README.md(있는 경우)를 업데이트하여 새 플레이북을 상단에 표시하세요.

5. 모든 상대 링크 확인

플레이북(및 업데이트된 README.md)에서 verify-links를 실행하세요. 완료를 사용자에게 보고하기 전에 0이 아닌 종료를 수정하세요.

속도 제한

• fetch-page는 파일 잠금(/tmp/ref_researcher_fetch.lock)과 단조 타임스탬프(time.monotonic())를 통해 동시 에이전트 프로세스 전체에서 1.0 요청/초 (REQUESTS_PER_SECOND = 1.0)를 적용합니다.
• HTTP 429는 RateLimitError를 발생시키기 전에 stderr에 기록된 지수 백오프(Retry-After 또는 2^attempt)를 트리거합니다.
• HTTP 5xx는 지수 백오프로 재시도합니다. 영구 HTTP 오류는 빠른 진단을 위해 URL과 잘린 응답 본문을 포함합니다.

일반적인 실수

• 분할되지 않은 15,000px 높이의 스크린샷을 직접 검사: 흐릿한 추측과 놓친 미세 상호 작용을 유발합니다. 항상 slice-media로 먼저 분할하세요.
• 차단된 로그인을 영원히 우회하거나 하나의 페이월에서 멈춤: 사용자에게 한 번 로그인하도록 요청하고, 최대 2번 재시도한 다음, 접근 가능한 소스로 깔끔하게 전환하고 차이를 기록하세요.
• 자체 코드베이스/PRD보다 경쟁사 마케팅 주장을 신뢰: 경쟁사의 "Cloud Sync" 또는 "Mac App" 히어로를 맹목적으로 복사하면 잘못된 마케팅 주장이 생성됩니다. 항상 제품 진실 매트릭스를 통해 모든 패턴을 확인하세요.
• 깨진 상대 링크를 남기거나 스크래치 이미지를 프로젝트 저장소 내부에 덤프: 항상 조각을 스크래치에 쓰고 마무리하기 전에 verify-links를 실행하세요.