williamsnieves/landing-factory

analyze-reference

패턴을 추출하고, 클론하지 마십시오. 이 스킬은 하나의 공개 페이지(사용자가 지정하는 최대 2개의 내부 링크 포함)를 읽고, 페이지가 어떻게 구축되고 어떻게 움직이는지 추상적인 용어로 설명한 후 patterns/<slug>.md 파일을 작성합니다. 사이트의 어떤 것도 저장되지 않습니다: 이미지, 동영상, 3D, 로고, 텍스트, 코드, 브랜드 폰트 이름 또는 색상 코드는 저장되지 않습니다. 스크린샷은 .cache/analyze/ 아래의 임시 작업 자료(git-ignored)이며 분석 종료 시 항상 삭제됩니다.

이 문서는 리포지토리 자체 워크플로우를 위한 지침이며 법률 자문이 아닙니다. 상품화하기 전에 지식 재산권 변호사와 상담하십시오 (docs/roadmap.md 참조).

입력

• url (필수): 공개 http(s) 페이지. 로그인, 페이월 또는 봇 챌린지 뒤의 페이지는 대상이 아닙니다.
• --focus "..." (선택 사항): 사용자가 사이트에서 마음에 들어하는 점을 사용자의 말로 입력합니다. 시트의 어떤 섹션에 깊이를 둘지 결정합니다. 프론트매터에 기록합니다(생략 시 none).
• 최대 2개의 내부 링크 (선택 사항, 동일 사이트): 각각을 동일한 단계로 분석하고 하나의 시트로 병합합니다. 더 이상 크롤링하지 않습니다.

슬러그(Slug): 호스트에서 파생됩니다 (www. 제거, 점을 대시로 변환, 예: example-com). 사용자가 슬러그를 지정하면 --slug를 recon.mjs에 전달합니다. patterns/<slug>.md가 이미 존재하는 경우 교체하기 전에 확인을 요청합니다.

모든 명령은 리포지토리 루트에서 실행됩니다. 스크립트는 .claude/skills/analyze-reference/scripts/에 있으며, 각 스크립트는 --help에 응답합니다.

단계

순서대로 실행합니다. 6단계(정리)는 1~5단계의 결과(성공, 중단 또는 오류)에 관계없이 항상 실행됩니다. finally 블록처럼 처리합니다.

1. 권한 확인 (브라우저로 사이트에 접근하기 전)

node .claude/skills/analyze-reference/scripts/check-robots.mjs <url>

robots.txt에서 *, ClaudeBot, anthropic-ai 및 GPTBot에 대한 지시사항, X-Robots-Tag 헤더, <meta name="robots">, 텍스트-데이터 마이닝 예약(TDMRep: /.well-known/tdmrep.json, tdm-reservation 헤더 및 메타)을 평가합니다. 종료 코드: 0 허용, 1 차단됨, 2 확인 불가.

• 종료 1 또는 2: 중지합니다. 시트를 생성하지 않고, 리콘을 실행하지 않습니다. 스크립트가 출력한 정확한 이유를 사용자에게 알립니다. 종료 2 (5xx, 타임아웃, 읽을 수 없는 파일)는 보수적인 중단입니다: 권한을 확인할 수 없다고 말하고, 루프로 재시도하거나 다른 방법을 찾지 마십시오.
• 추가 내부 링크 각각에 대해서도 실행합니다.
• robots.txt의 404는 허용으로 간주합니다. 401/403은 허용되지 않는 것으로 간주합니다.

2. 정찰 (Reconnaissance)

node .claude/skills/analyze-reference/scripts/recon.mjs <url> [--slug <slug>]

Playwright (헤드리스 Chromium; Playwright 자체 브라우저가 설치되지 않은 경우 QA_CHROME_PATH 또는 CHROME_PATH 설정)가 페이지를 로드하고, 스크롤하며, .cache/analyze/<slug>/recon.json 및 screens/{375,768,1440}-<n>.png 파일을 작성합니다. JSON에는 구조와 통계만 포함됩니다: 순서대로 섹션(높이, 제목/단어 수 포함, 텍스트는 절대 포함하지 않음), 집계된 타입 크기, 줄 높이, 간격, 그리드/flex 사용, serif/sans/mono/display로 분류된 폰트(이름은 절대 포함하지 않음), 역할 설명으로 표현된 색상(코드는 절대 포함하지 않음), 증거 및 신뢰도와 함께 탐지된 라이브러리, 네트워크 도메인, canvas/WebGL 존재 여부, 모션 관찰 결과(reveal, pin, parallax, scrub, sticky header, eased scroll).

스크롤 컨테이너. 일부 페이지는 문서를 뷰포트 하나 높이로 유지하고 내부 래퍼를 스크롤합니다. recon.mjs는 이를 감지하고(뷰포트의 60% 이상을 덮고 가장 큰 스크롤 범위를 가진 보이는 overflow-y: auto|scroll|overlay 요소) 스크린샷, 모션 샘플링 및 휠 프로브에 사용합니다. recon.json은 scroller: { kind: "document" | "container", scrollHeightPx, clientHeightPx }를 기록하고, viewports[w].docHeightPx는 실제로 사용된 스크롤 가능한 높이입니다. 증거를 읽을 때 scroller.kind를 확인하십시오. 발견법은 기록되며 보장되지 않습니다: 스크린샷이 페이지 대신 사이드 패널이나 모달을 보여주는 경우 시트에 그렇게 명시하십시오. 중첩 또는 수평 스크롤러, 그리고 스크롤 가능한 요소 없이 휠 이벤트로 구동되는 장면은 다루지 않습니다. 페이지가 특정 너비(예: 태블릿 중단점)에서 스크롤을 멈출 수도 있습니다. 이 경우 해당 너비의 한 장의 스크린샷이 정확합니다.

프록시 뒤. HTTPS_PROXY 또는 HTTP_PROXY가 설정된 경우(클라우드 세션), check-robots.mjs와 recon.mjs는 NODE_USE_ENV_PROXY=1로 한 번 자체 재실행되어 Node의 fetch가 이를 사용하고, recon.mjs는 프록시를 Chromium에 전달합니다(루프백은 직접 연결 유지). 플래그가 필요하지 않습니다. Node의 실험적 경고 줄은 숨겨집니다. 인증서는 평소와 같이 NODE_EXTRA_CA_CERTS에서 가져옵니다. 스크립트는 이를 읽거나 포함하지 않습니다. 프록시가 없으면 아무것도 변경되지 않습니다.

종료 3은 페이지를 분석할 수 없음을 의미합니다(로그인 양식, 봇 챌린지, HTTP 401/403/429, 연결 불가). 중지: 시트 없음, 사용자에게 이유를 알립니다(로그인 페이지의 경우: "페이지가 공개되지 않음"). 차단을 회피하거나, 챌린지를 해결하거나, 로그인하거나, 사용자 에이전트를 변경하려고 시도하지 마십시오.

3. 증거 읽기

• .cache/analyze/<slug>/recon.json을 완전히 읽습니다.
• Read 도구로 스크린샷을 봅니다. 너비별로 최소 몇 장씩 봅니다. 숫자로는 판단할 수 없는 것들을 평가하기 위함입니다: 히어로 구성, 리듬, 밀도, 레이아웃이 그리드를 벗어나는 지점, 움직이는 요소. 스크린샷은 오직 당신의 눈을 위한 것입니다. 절대 복사, 포함 또는 참조하지 마십시오.
• 신뢰도: 전역 또는 DOM 클래스와 일치하는 스크립트 이름이 함께 있으면 high; 둘 중 하나만 있으면 medium; 네트워크 도메인만 있으면 low입니다. 앱 코드에 번들된 라이브러리는 스크립트 이름 일치로만 표시되므로 "추정됨"이라고 말하고 recon이 보고한 신뢰도를 유지하십시오.

4. 시트 작성

patterns/_template.md의 구조를 patterns/<slug>.md에 복사합니다. 프론트매터(url, slug, 오늘 날짜 YYYY-MM-DD, focus, 라이브러리 이름 목록 libraries)와 모든 섹션을 자신의 말로 채웁니다:

섹션	내용
요약 (Summary)	어떤 종류의 페이지이며 왜 배울 가치가 있는지
섹션 맵 (Section map)	순서가 있는 섹션: 역할, 대략적인 뷰포트 높이, 레이아웃 아이디어
히어로 (Hero)	히어로 유형, 첫 화면의 구성, 로드 시 움직이는 요소
그리드 및 간격 (Grid and spacing)	컬럼 시스템, 콘텐츠 너비 클래스, 간격 척도(기본 단위), 수직 리듬
타이포그래피 (Typography)	일반 클래스("큰 그로테스크 디스플레이 + 세리프 본문"), 스케일 비율, 두께, 줄 높이 및 자간 습관, 대소문자
팔레트 (Palette)	역할 및 톤("거의 검은색 배경, 따뜻한 채도 악센트"), 대비 특성, 테마
밀도 (Density)	화면당 콘텐츠, 여백, 섹션당 아이디어, 텍스트-미디어 균형
모션 (Motion)	표: 순간, 트리거(load, scroll, hover), 유형(reveal, pin, parallax, scrub, page transition, shader/3D), 기술 및 라이브러리, 신뢰도
라이브러리 (Libraries)	탐지된 라이브러리, 증거 클래스 및 신뢰도
취할 점 / 피할 점 (What to take / what to avoid)	독창적인 랜딩 페이지에서 패턴으로 재사용할 점, 너무 구체적이거나 모방하기 위험한 점

모션 항목: 관련 효과당 한 행. 스크롤에 따라 콘텐츠가 애니메이션되는 동안 섹션이 고정(pin)되는 경우 트리거는 scroll, 유형은 pin+scrub, 라이브러리와 그 신뢰도를 기재합니다. 호버 동작은 recon으로 측정되지 않습니다. 스크린샷이나 hoverTransitionElements 개수를 보고 추론할 때는 신뢰도를 낮음(low)으로 표시하십시오.

5. 검증

npm run validate:patterns

반드시 통과해야 합니다. file:line 위반이 보고되면 해당 줄을 더 추상적으로 다시 작성하고 다시 실행하십시오. 검증기를 약화시키지 말고, > note: 줄을 사용하여 카피를 몰래 집어넣지 마십시오. 해당 접두사는 긴 인용구 규칙에서 자신의 짧은 의견만 면제합니다.

선택 사항, 3단계 후에도 흥미로운 효과가 설명되지 않은 상태로 남아 있는 경우에만: npx rea-agents analyze-javascript-application <url> (무겁고, 필수가 아님). 출력, 코드 또는 덤프가 아닌 서면 결론만 기록합니다(예: "타임라인 라이브러리로 구동되는 스크롤 연결 카메라 경로, 중간 신뢰도"). 가지고 있지 않은 네트워크 액세스가 필요한 경우 건너뜁니다.

6. 정리 (항상)

node .claude/skills/analyze-reference/scripts/recon.mjs --cleanup <slug>

성공 후, 모든 단계에서 중단 후, 그리고 오류 후에 실행합니다. 그런 다음 .cache/analyze/<slug>가 사라졌는지, git status에 사이트의 어떤 것도 표시되지 않는지(성공 시 patterns/<slug>.md만 표시) 확인합니다. recon.mjs는 실패 시 자체 폴더도 제거하지만, 여전히 정리를 실행해야 합니다.

7. 사용자에게 보고

분석된 내용, 시트의 경로, 신뢰도와 함께 발견된 라이브러리, 확인할 수 없었던 사항, 그리고 사람이 PR에서 시트를 검토해야 한다는 점을 말합니다. 중단 시: 이유와 시트가 작성되지 않았다는 점을 말합니다.

추상화 규칙 (엄격)

절대 시트, 시트의 채팅 요약, 커밋 또는 버전 관리된 파일에 다음을 넣지 마십시오:

• 사이트의 텍스트: 헤드라인, 본문 카피, 마이크로카피, 대체 텍스트, 메타 설명 (페이지 제목과 URL만 허용됨).
• 이미지, 비디오, 폰트, 3D 모델 또는 아이콘 URL 및 모든 에셋 파일.
• 소스 코드, 마크업, CSS, JS 또는 셰이더 조각 (짧거나, 축소되거나, 편집된 경우에도).
• Hex, rgb(), hsl() 또는 기타 색상 코드. 역할과 톤으로 설명하십시오.
• 브랜드 또는 독점 폰트 이름. 일반 클래스를 사용하십시오.
• 로고, 브랜드 마크, 일러스트레이션.

디자이너가 동료에게 브리핑하는 방식으로 패턴에 대해 작성하십시오: "고정된 명령문 섹션, 콘텐츠가 약 한 뷰포트 정도 스크러빙됨", 마크업을 옮겨 적는 방식이 아닙니다. 세부 사항이 콘텐츠인지 패턴인지 확실하지 않으면 생략하십시오.

중단 사례

상황	조치
robots.txt가 *, ClaudeBot, anthropic-ai 또는 GPTBot에 대해 경로를 허용하지 않음	1단계에서 중단, 일치하는 규칙 보고, 시트 없음
TDM 예약 (TDMRep 파일, 헤더, 메타 또는 robots.txt 지시어)	1단계에서 중단, 보고, 시트 없음
X-Robots-Tag 또는 메타 로봇에 noai, noindex 또는 none	1단계에서 중단, 보고, 시트 없음
권한을 확인할 수 없음 (5xx, 타임아웃, 읽을 수 없는 파일)	1단계에서 중단, "권한을 확인할 수 없음"이라고 말함, 시트 없음
로그인 양식, 페이월, HTTP 401/403/429, 봇 챌린지	2단계에서 중단, 페이지가 공개되지 않거나 자동화된 브라우저를 차단한다고 말함, 시트 없음; 회피하지 않음
연결할 수 없는 URL 또는 2xx가 아닌 응답	2단계에서 중단, 오류 보고, 시트 없음
검증이 계속 실패함	더 추상화하여 수정; 요점을 잃지 않고 통과할 수 없으면 그렇게 말하고 시트를 작성하지 않음

모든 중단 사례에서 6단계를 실행합니다.

기여

정찰 접근 방식(여러 너비의 스크린샷, DOM 구조, 계산된 스타일, 상호작용 및 스크롤 관찰)은 JCodesMore/ai-website-cloner-template의 clone-website 스킬에 있는 리콘 단계를 각색한 것이며, MIT 라이선스입니다. 리콘 단계의 아이디어만 재사용 및 재작성되어 추상적인 설명을 위해 사용되었습니다. 코드나 해당 스킬의 에셋 다운로드 또는 재구축 단계는 포함되지 않았습니다.