| name | reference-analysis |
| description | 원본 레퍼런스(공개 PDF 덱·공식 디자인 시스템·역사 양식)를 확보·적격 판정·전수 정독하여, 팩 집필이 근거로 삼을 visual spec과 변환 계약(transform contract)을 만드는 방법론 스킬. reference-analyst 에이전트가 사용한다. 레퍼런스 모드 4종 분류, 원본 적격 게이트, 페이지 전수 인벤토리, 시그니처 모티프 추출, 상표·독점자산 치환 계약을 규정한다. 이 스킬의 산출물 없이는 premium 레퍼런스 팩을 집필할 수 없다. |
Reference Analysis — 원본 정독 · 변환 계약
reference-analyst가 "원문과 닮은" 팩의 근거를 만드는 방법. 관찰한 것만 기록하고, 추론한 것은 추론이라고 표시한다.
왜 이 스킬이 존재하는가
이 프로젝트는 프리미엄 한국 레퍼런스 10팩을 v1→v2→v3로 세 번 갈아엎었다. 사유는 매번 같았다 — 원본과 다르다. v3에서 실제로 통했던 절차(원본 확보 → 페이지 전수 정독 → mirror plan → 재집필 → 대조 검증)가 어느 스킬에도 문서화되지 않아, 매 회차 처음부터 다시 발명됐다. 이 스킬이 그 절차의 SSOT다.
레퍼런스 모드 (가장 먼저 확정한다)
팩마다 reference_mode를 하나 고른다. 모드가 판정 기준을 결정하므로 이것을 틀리면 뒤의 모든 검증이 무의미하다.
reference_mode | 대상 | 근거 요구 수준 | 판정 기준 |
|---|
exact_document | 특정 공개 덱 1건 (예: 부처 업무보고 PPT, 기업 IR 덱) | 원본 파일 확보 필수 | 페이지·변환 계약 대비 fidelity |
official_system | 공식 디자인 시스템 (Material·HIG·Carbon 등) | 공식 문서 + 컴포넌트 캡처 | 컴포넌트·토큰 conformance |
historical_canon | 역사 양식 (바우하우스·데스틸·스위스 타이포 등) | 학술·박물관 1차 자료 | 원리·모티프 인벤토리 conformance |
style_synthesis | 복수 2차 자료의 합성 (예: "컨설팅 덱 미감") | 2차 자료 허용 | style_conformance만. 원문 충실도를 주장하지 않는다 |
엄수: style_synthesis 팩은 source_depth: full을 쓸 수 없고, meta·사이트 어디에서도 "원본을 재현했다"고 말하지 않는다. 2차 자료(슬라이드 판매 사이트·유튜브 해설·블로그)만 있는데 full로 표기하는 것은 출처 위조다.
원본 적격 게이트 (exact_document 전용)
후보를 정독하기 전에 기계적으로 판정한다. 여기서 거른 것이 가장 싸다.
| 게이트 | 기준 | 판정 방법 |
|---|
| G-A 확보 | 원본 파일을 실제로 내려받았다 | curl -sL -o 후 파일 유효성 확인. 링크 존재만으로는 불가 |
| G-B 매체 형태 | PPT 트랙은 종횡비 ≥ 1.6 (16:9 = 1.778) | 1페이지 mediabox 실측 |
| G-C 분량 | 페이지 ≥ 8 | 페이지 수 |
| G-D 디자인 밀도 | 앞 5장을 렌더해 직접 보고 시각 언어가 있는지 판정 | 사람/에이전트 육안 |
| G-E 권리 | 공개 배포물이며 출처가 1차 | 게시 주체·URL |
G-B가 이 프로젝트에서 가장 많이 실패한 게이트다. A4 세로 한글 문서(종횡비 ≈0.71)를 덱으로 착각해 국토부·고용부 2팩을 폐기했고, 농식품부·행정안전부·식약처·기후에너지부·한국은행 후보 6건을 다운로드 후에야 탈락시켰다. 비율을 먼저 재라.
게이트 결과는 후보별로 남긴다 — 탈락 사유는 다음 회차의 자산이다.
{ "code": "mois", "gate_16x9": "fail", "aspect_ratio": 0.707,
"drop_reason": "A4 세로 한글 문서. 디자인 덱 아님." }
원본 확보 기록 (source manifest)
통과한 원본은 재현 가능하게 고정한다. 원본은 저장소에 커밋하지 않되, 식별자는 커밋한다.
reference:
mode: exact_document
canonical_url: "https://..."
retrieved_at: "2026-08-15T14:20:00+09:00"
sha256: "..."
media_type: application/pdf
page_count: 22
page_box: { width: 960, height: 540, unit: pt }
aspect_ratio: 1.778
local_path: "_workspace/{batch}/pdf/{code}.pdf"
sha256가 같으면 이전 분석을 재사용한다 — 같은 원본을 두 번 정독하지 않는다.
페이지 전수 인벤토리
원본 전 페이지를 렌더해 전부 본다. 표본만 보고 쓰는 것이 v1 실패의 직접 원인이었다.
pdftoppm -png -r 110 원본.pdf _workspace/{batch}/pages_src/{code}/p
페이지마다 관찰 기록을 남긴다. 형용사가 아니라 관찰값으로.
{ "page": 13, "role": "policy-diagram",
"observed": {
"bg": "#001838→#0848A0 세로 그라데이션 풀스크린",
"structure": "중앙 반원 호 + 3노드, 호 상단에 시안 글로우",
"type": "캘리그래피 28pt 흰색 2행 + 노드 라벨 16pt",
"chart": null,
"notes": "이 덱에서 유일한 다크 배경 다이어그램 — 시그니처 후보" },
"inferred": ["글로우는 외곽 blur 24px로 추정 (원본 벡터 확인 불가)"] }
observed와 inferred를 반드시 분리한다. 뒤의 fidelity 검증자는 observed만 근거로 인정한다.
시그니처 모티프 추출
"이 덱임을 알아보게 하는 것"을 순위와 함께 3~7개 뽑는다. 각 항목은 네 필드를 갖춘다.
signature_motifs:
- rank: 1
name: 캘리그래피 손글씨 슬로건 풀스크린
evidence_pages: [1, 5, 12, 20, 21]
where: 표지·섹션 인트로·종결. 본문 페이지에는 없음
uniqueness: 다른 부처 덱은 고딕 제목만 씀 — 손글씨가 이 덱의 유일 식별자
must_preserve: true
evidence_pages가 비어 있으면 그 모티프는 관찰이 아니라 창작이므로 삭제한다. must_preserve: true인 모티프가 하나라도 재현되지 않으면 fidelity에서 점수와 무관하게 반려다 — 그러니 이 플래그는 정말 그 덱을 그 덱이게 하는 것에만 붙인다.
변환 계약 (transform contract)
원본을 그대로 베끼는 것은 목적이 아니다. 우리가 배포하는 것은 시각 원리의 명세다. 원본의 각 요소를 네 가지 중 하나로 처분하고, 그 결정을 기록한다.
| action | 의미 | 예 |
|---|
preserve | 그대로 재현 | 그리드 비율, 색 관계, 타이포 위계, 다이어그램 문법 |
adapt | 역할은 유지하되 값을 조정 | 유료 폰트 → metric 호환 공개 폰트 |
substitute | 보호 자산을 역할만 남기고 치환 | 부처 엠블럼 → 같은 위치·크기의 중립 워드마크 자리 |
drop | 재현하지 않음 | 특정 인물 사진, 원본 고유 일러스트 |
{ "source_page": 1, "element_id": "ministry-emblem", "class": "trademark",
"action": "substitute",
"preserve": ["우하단 배치", "슬라이드 폭 대비 5%", "다크 위 흰색 대비"],
"prohibit": ["기관명 문자열", "엠블럼 기하", "전용 서체"] }
보호 자산 분류(class) — trademark(로고·엠블럼·워드마크) · proprietary_image(원본 사진·일러스트) · licensed_font(유료 폰트) · slogan(정부·기업 공식 문구). 이 넷은 preserve가 불가능하다. substitute 또는 drop만 허용한다.
페이지 매핑과 정직한 명명
원본 N장을 팩 M장으로 옮길 때, 반드시 어느 원본에서 왔는지 적는다.
page_mirror_plan:
original_pages: 22
pack_pages: 10
compression: merged
map:
- pack_page: 5
source_pages: [9, 10, 11]
kind: chart
rationale: 3장이 같은 정책의 연속 화면 — 하나로 합쳐도 문법 손실 없음
명명 규율. compression: merged인데 "1:1 mirror"라고 부르지 않는다. 22장을 10장으로 합쳤으면 그것은 transformed-principle fidelity이지 픽셀 미러가 아니다. 과대 표기는 뒤의 검증자가 무엇을 기대해야 할지 혼란시킨다.
identity — 원본 1장 = 팩 1장, 전 페이지 커버selected — 원본 일부만 선택 (선택 사유 + 비선택 페이지 목록 필수)merged — 복수 원본 → 팩 1장 (병합 사유 필수)
산출물
_workspace/{batch}/
01_scout_candidates.json # 게이트 판정 포함 (탈락분도 보존)
pdf/{code}.pdf # 원본 (로컬 전용, 커밋 안 함)
pages_src/{code}/p-NN.png # 원본 전 페이지 렌더
visual_spec/{code}.json # 페이지 전수 인벤토리 + 시그니처 + reference manifest
transform_contract/{code}.json # 요소별 처분 계약
정본 키 (필수 — 이름을 바꾸지 않는다)
이 절이 없어서 첫 배치 5팩의 산출물이 즉시 갈라졌다. 인벤토리에 inventory/page_inventory 2종, 비선택 페이지에 not_selected/unselected/unmapped_source_pages 3종, 변환 계약 루트에 5종이 생겼다. 팩 meta.yaml에서 벌어졌던 고아 필드 28종 사태와 같은 병이다. 아래 이름만 쓴다.
visual_spec/{code}.json 최상위 키:
| 정본 | 필수 | 폐기된 별칭 |
|---|
schema_version | ✓ | — |
code | ✓ | — |
reference | ✓ | manifest |
pages_unreadable | ✓ (없으면 []) | — |
page_inventory | ✓ | inventory · pages |
signature_motifs | ✓ | signature_visual_motifs · signature_top5 |
page_mirror_plan | ✓ | mirror_plan · compression_plan |
palette_measured | 권장 | palette |
contrast_measured | 권장 | contrast |
page_mirror_plan 하위: original_pages · pack_pages · compression · map · not_selected(← unselected·unmapped_source_pages·excluded 폐기).
transform_contract/{code}.json 최상위 키: schema_version · code · reference_sha256 · elements(요소 배열. protected_assets·preserved_principles로 쪼개지 말고 각 원소의 class·action으로 구분한다).
page_inventory 각 원소: page(정수) · role · observed(객체) · inferred(배열).
페이지 번호는 항상 정수 배열로 쓴다 — "1,2,13-16 등 전 페이지" 같은 문자열 금지. 뒤의 검증자가 기계로 대조할 수 없다.
새 키가 필요하면 산출물에서 즉석으로 만들지 말고 이 표를 먼저 고친다.
하지 말 것
- 표본 몇 장만 보고 전체를 단정하는 것. 전 페이지를 봐라.
observed에 추론을 섞는 것. 확인 못 한 것은 inferred에 두거나 비워라.- 원본을 못 구했는데
exact_document로 선언하는 것. 그건 style_synthesis다.
- 일반 디자인 상식으로 관찰의 빈칸을 메우는 것 — 원본이 규칙을 어기고 있으면 원본이 옳다. 그 이탈이 곧 그 덱의 정체성이다.
- 보호 자산을
preserve로 처분하는 것.
