reference-template

Imported from lightsoft-dev/claude-plugin-for-dev (reference-template/SKILL.md). Install upstream with npx skills add lightsoft-dev/claude-plugin-for-dev --skill reference-template. Copyright stays with the author.

Reference Template

이 저장소(claude-plugin-for-dev)는 배포용 사본이다. 원본은 lightsoft-dev/easysite 의 .claude/skills/reference-template/ 이고, 거기서 실제로 돌리며 고친다. 고칠 일이 생기면 원본을 고치고 여기로 다시 복사한다.

다른 저장소에서 쓰려면 그 저장소 루트에 reference-template.config.json 을 둔다 (예시: 이 폴더의 reference-template.config.example.json). 팩 폴더·데모 스냅샷 경로·미리보기 경로· 렌더/빌드/배포 명령·공개 데모 규칙이 거기서 온다. 설정이 없으면 easysite 배치를 기본값으로 쓴다.

운영 중인 사이트의 디자인을 재서 옮기고, 콘텐츠는 처음부터 새로 쓴다. 기존 20종은 글 브리프로 AI 가 디자인을 상상해서 세 번을 다시 칠했다. 실측에서 출발하면 그 왕복이 없다. 첫 적용(about.daangn.com → company)은 1차 리뷰에서 그대로 승인됐다.

스크립트는 이 스킬 안에 있다(scripts/). 저장소 루트에서 실행하고, 저장소마다 다른 값은 그 저장소의 reference-template.config.json 에서 읽는다(팩 폴더·데모 슬러그 경로·미리보기·렌더/빌드/배포 명령· 데모 규칙). 설정 파일이 없으면 easysite 배치를 기본값으로 쓴다.

S=~/.claude/skills/reference-template/scripts   # 또는 <저장소>/.claude/skills/reference-template/scripts

그 저장소의 사실(레퍼런스 고르는 기준·함정·적용 기록)은 그 저장소 문서가 원본이다 — easysite 는 docs/template-pipeline.md, 템플릿 공통 규칙은 docs/templates.md, 카피는 docs/copy-guide.md. 이 파일은 순서와 판단만 갖는다.

흐름과 멈추는 곳

⏸ 두 곳에서만 멈춘다. 나머지는 고르고 진행하고, 무엇을 골랐는지 보고한다.

저작권 경계 — 이 스킬이 서 있는 선

디자인을 통째로 베끼는 도구가 아니다. 아이디어·배치 같은 것은 보호 범위가 애매하고, 문장·사진·로고· 서체는 명백히 남의 것이다. 그래서 선을 이렇게 긋고, 애매하면 빼는 쪽으로 간다.

leak-check 가 아래를 숫자로 지킨다 — 문장(8자 이상)·12자 조각·브랜드 이름·브랜드 색·전용 서체·자산 URL. 0건이 아니면 리뷰 보드를 만들지 않는다.

구조도 그대로 두지 않는다. 수치를 맞추는 건 출발점이지 결과가 아니다. 넘기기 전에 이만큼은 바꾼다.

• 섹션 수·순서를 우리 콘텐츠에 맞춘다 — 레퍼런스에 있는데 우리 업종에 필요 없는 칸은 빼고, 필요한 칸 (상담·시간표·오시는 길)은 더한다. 두 팩 다 이야기 4→3개, 문의·상담 칸 추가로 바꿨다.
• 시그니처 장치는 새로 만든다 — 레퍼런스의 3D 고리·일러스트 자리에 우리가 그린 등고선·오각형·SVG 를 넣는다. 그 자리를 비슷한 그림으로 채우면 선을 넘는다.
• 레퍼런스 하나를 그대로 따라가지 않는다 — 업종에 맞는 칸을 다른 데서 가져오거나 우리 카피 규칙으로 재배치한다.
• 출처를 남긴다 — DESIGN.md 에 URL·가져온 것·바꾼 것·실측이 아닌 결정을 적는다. 팩 파일 맨 위 주석에도.

로봇 배제 기준(robots.txt)을 먼저 본다. 금지·확인 실패면 그 사이트는 버린다. 우회하지 않는다. 전용 자산(일러스트·캐릭터)이 그 사이트 디자인의 본체면 애초에 후보에서 뺀다 — 뺄 게 너무 많아진다.

1. 레퍼런스 고르기

사용자가 사이트를 주지 않았으면 후보를 5~10곳 모아 robots 부터 판정한다(금지·확인 실패는 버린다, 우회하지 않는다):

node ~/.claude/skills/reference-harvest/scripts/check-source.mjs <url> > /tmp/cs.log 2>&1; echo "exit=$?"   # 0 허용 · 1 금지 · 2 확인 실패

통과한 곳을 agent-browser screenshot --full 로 찍어 한 장에 붙여 보고 고른다. 기준 넷(전용 자산이 디자인의 본체가 아닐 것, 쇼핑몰 기성 그리드 제외, 소상공인·회사소개로 옮겨질 것)과 지난 판정표는 docs/template-pipeline.md 「레퍼런스 고르는 기준」. 기존 팩과 겹치지 않는지 shared/templates/types.ts 의 STYLE_LABELS 를 본다.

2. 크롤링

node $S/capture.mjs <url> <refId> > /tmp/cap.log 2>&1; echo "exit=$?"     # 약 2분, robots 게이트 포함
node $S/init-lab.mjs <refId> --style <style>                               # lab.json 초안 — 빈 칸만 채운다

init-lab 이 브랜드 이름·로고 색·전용 서체를 채운다(누출 검사가 이걸로 잰다). sections[].why 는 직접 쓴다 — 섹션마다 「유지: … 바꿈: …」. 리뷰 보드 항목 설명이 여기서 나온다. 섹션 이름에 레퍼런스 문장을 넣지 않는다(커밋되는 파일이다).

그다음 필름을 읽는다. 이 단계가 품질을 정한다 — 전체 캡처만 보면 핀·스크롤 연출이 전부 사라져 보인다. film/ 을 몽타주로 붙여 데스크톱·모바일 둘 다 보고, 어떤 연출인지 references/scroll-patterns.md 「필름에서 연출 알아보기」 표로 판정한다. 요소별 크기·간격은 agent-browser eval 로 따로 재서(스크롤을 한 번 끝까지 내린 뒤) templates-lab/<refId>/DESIGN.md 에 표로 남긴다. 실측이 아닌 값은 「결정」 표에 이유와 함께 따로 적는다(서체 대체, 브랜드 색, 사진 수급).

3. 클론

shared/templates/<style>.ts 에 build<Style>Vfs(brand) 를 쓴다. 아직 등록하지 않는다(preview-template.ts 가 파일을 직접 부른다).

• 토큰은 실측값 그대로 CSS 변수로. 반올림하지 않는다.
• 콘텐츠는 처음부터 가상 회사로 새로 쓴다. 레퍼런스 문장을 옮겨 놓고 나중에 바꾸지 않는다 — 누출이 남는다. 숫자·시각·지명이 든 사실 문장으로(docs/copy-guide.md), 전화 02-465-0417 · 사업자번호 000-00-00000 · SNS 링크 금지(docs/templates.md).
• 스크롤 연출은 references/scroll-patterns.md 레시피로. 외부 라이브러리 없이 CSS 변수 + rAF 하나.
• 레퍼런스의 영상·일러스트 자리는 사진이나 인라인 SVG 로. 사진은 codex-image 스킬로 생성해 assets-src/gen-prompts.tsv 형식으로 기록하고 magick <png> -resize 1200x -quality 78 public/samples/<style>/<name>.webp. 한도가 막히면 다른 팩 사진을 임시로 빌린다(templatize-check 가 경고로 남긴다).
• data-bind 는 BIND_SCRIPT_CORE 가 아는 키에 건다. 바인딩이 textContent 로 덮는 요소를 스크립트가 다시 가공해야 하면 바인딩 뒤에 가공한다(문장 켜기가 그 예).

회차 돌리기:

node $S/round.mjs <refId> --round 1차 > /tmp/round.log 2>&1; echo "exit=$?"

렌더 → 클론 캡처 → 누출 검사 → 실측 비교 → 리뷰 보드까지 약 1분. 누출이 있으면 보드를 만들지 않는다. 사람에게 보이기 전에 섹션 화면을 직접 원본과 나란히 놓고 본다(magick montage templates-lab/<refId>/{ref,clone}/desktop/sections/*.png …). 토큰 일치율(fidelity.md)은 값이 「있는지」만 잰다 — 98% 여도 배치가 틀릴 수 있다. 콘솔 에러 0 도 확인한다.

4. 피드백 ⏸

node $S/round.mjs <refId> --round 1차 --open

artifact-open 이 백그라운드 탭으로 연다. 이렇게 안내하고 기다린다:

왼쪽이 레퍼런스, 오른쪽이 클론입니다. 항목마다 코멘트를 적고 「코멘트 복사」를 눌러 여기 붙여 주세요.

코멘트를 반영하면 --round 2차 로 다시 돈다. "좋다"·"올려줘"가 오면 5단계로 간다.

5. 템플릿화

등록 지점(한 곳이라도 빠지면 templatize-check 가 이름을 대며 실패한다):

1. shared/templates/types.ts — StyleId · STYLE_IDS · STYLE_LABELS · STYLE_DESCRIPTIONS · STYLE_CATEGORIES
2. shared/templates/index.ts — builders, STYLE_NOUNS 전환 말(기존 말과 겹치면 앞에 둔다 — 「회사소개」는 agency 것)
3. shared/demos.ts — demo-<영소문자> 슬러그
4. 스냅샷·미리보기 — 팩을 마지막으로 고친 뒤에 뜬다:

pnpm exec tsx scripts/export-demo-vfs.ts > /tmp/export.log 2>&1; echo "exit=$?"
pnpm exec tsx scripts/capture-previews.mjs <style> > /tmp/prev.log 2>&1; echo "exit=$?"
pnpm exec tsx $S/templatize-check.ts <style>; echo "exit=$?"      # ✗ 0 이어야 통과, ! 는 보고에 적는다
pnpm build > /tmp/build.log 2>&1; echo "exit=$?"

git status 로 다른 데모 스냅샷이 같이 바뀌지 않았는지 본다(바뀌었으면 남의 팩 변경이 섞인 것). docs/templates.md 의 팩 수·기준선 표, docs/template-pipeline.md 적용 기록을 고치고 커밋한다.

6. 업로드 ⏸ 승인

git push 는 사용자가 올리라고 했을 때만. "업로드까지 해줘"는 승인이다. 이 저장소는 GitHub Actions 가 없어 push 가 배포를 일으키지 않는다 — 배포는 publish.ts 가 한다.

git push origin HEAD:master                                            # 원격·브랜치를 항상 명시
pnpm exec tsx $S/publish.ts <style> --dry-run; echo "exit=$?"  # 사전 점검만
pnpm exec tsx $S/publish.ts <style>; echo "exit=$?"

publish.ts 가 하는 일 — 멈추는 조건이 전부 스크립트 안에 있다:

그 뒤 실제 브라우저로 /s/<slug> 를 연다. 사이트는 iframe 안이라 agent-browser scroll 로는 안 내려간다 — mouse move 700 450 후 mouse wheel 400 을 반복한다.

끝 보고

빌린 사진이 남아 있으면 「남은 일」로 적는다. 함정을 새로 밟았으면 docs/template-pipeline.md 「함정」에 한 줄 더한다.