시리즈: 모듈형 평가 엔진 구축하기 (5/10)

connect 모듈은 사용자가 실제로 보게 되는 것들, 즉 커버 페이지(cover page), 양식 작성 경험(form-filling experience), 그리고 마지막 페이지를 구성합니다. 또한 색상, 배경, 레이아웃과 같은 비주얼 스타일(visual style)을 주도합니다. 이곳은 "기능적인 것"이 "2003년의 정부 양식처럼 보이지 않는 것"과 만나는 지점입니다.

세 개의 페이지, 세 개의 역할

모든 평가 앱에는 세 가지 페이지 유형이 있습니다:

[커버 페이지 (Cover Page)] → [메인 페이지 (Main Page (form))] → [최종 페이지 (Final Page)]

• 커버 페이지 (Cover page): 갈고리(hook) 역할. 사용자가 왜 여기에 5분을 투자해야 할까요?
• 메인 페이지 (Main page): 실제 양식(form). 하나의 긴 페이지(form mode), 화면당 질문 하나(field mode), 또는 카드 스와이프 스타일(card mode)이 될 수 있습니다.
• 최종 페이지 (Final page): 보상(payoff). PDF 보고서 다운로드, AI 전문가와의 채팅, 또는 간단한 감사 인사.

커버 페이지 전환 공식

대부분의 커버 페이지는 "저희 평가에 오신 것을 환영합니다"라고 말하기 때문에 실패합니다. 아무도 신경 쓰지 않습니다. 커버 페이지는 단 하나의 질문에 답해야 합니다: 왜 내가 여기에 시간을 써야 하는가?

SKILL.md는 네 가지 요소로 구성된 공식을 강제합니다:

assess connect cover-page add --id cover_main \
  --name "Workplace Stress Assessment" \
  --description "<p>73% of high-pressure workers don't realize their stress exceeds healthy levels.</p>
...

네 가지 요소:

1. 훅 문장 (Hook sentence) — 지식 베이스(knowledge base)에서 가져온 직관에 반하는 사실이나 놀라운 숫자 ( "환영합니다"가 아님)
2. 혜택 진술 (Benefit statement) — 사용자가 얻게 되는 것 (한 문장)
3. 예상 소요 시간 (Time estimate) — "5분" (정직하게, "빠르게"가 아님)
4. 차원 미리보기 (Dimension preview) — 다루는 내용을 보여주는 2~4개의 키워드

조작된 통계 문제

강제하기 가장 어려운 규칙: 훅(hook)에 사용되는 통계는 AI의 상상이 아니라 반드시 지식 베이스(knowledge base)에서 가져와야 합니다.

AI는 "연구에 따르면 노동자의 87%가 번아웃을 경험하는 것으로 나타났습니다."와 같은 문장을 작성할 수 있습니다. 그 숫자는 신뢰가 가는 것처럼 들립니다. 하지만 그것은 지어낸 것입니다. 공개적인 플랫폼에서 조작된 통계는 신뢰성에 있어 재앙과 같습니다.

해결책: SKILL.md는 "통계는 반드시 지식 베이스 (knowledge base)의 원문에서 가져와야 하며, AI의 조작은 금지된다"라고 명시적으로 규정합니다. 폼 (form) 모듈의 --kbText 계약 (contract)은 소스 자료를 사용할 수 있도록 보장합니다.

메인 페이지 형식 결정 (The Main Page Format Decision)

각기 다른 시나리오에 적합한 세 가지 형식이 있습니다:

형식	UX	사용 시점
form	모든 질문이 한 페이지에 있음	설문 조사 (surveys), 데이터 수집, 짧은 양식
...

결정은 플랜 유형 (plan type)에 따라 이루어집니다:

survey → form (필수)
assessment/consultation/exam → field 또는 card
learn → field

왜 설문 조사 (survey)는 form을 필수로 할까요? 설문 조사는 종종 데스크톱에서 작성되기 때문이며, 20개의 질문이 있는 설문 조사에서 질문당 한 페이지씩 보여주는 것은 다크 패턴 (dark pattern)처럼 느껴질 수 있습니다. 사용자는 참여를 결정하기 전에 전체 범위를 보고 싶어 합니다.

왜 평가 (assessment)는 field를 선호할까요? 화면당 하나의 질문을 배치하면 집중도를 높일 수 있기 때문입니다. 사용자는 15개의 리커트 척도 (Likert scales)를 한꺼번에 보며 압도당하지 않습니다. 또한 이는 진행 표시기 (progress indicators)와 질문별 맥락 (context) 제공을 가능하게 합니다.

스타일 시스템 (The Style System)

시각적 스타일은 별도의 AI 호출인 style apply를 통해 적용됩니다:

assess connect style apply \
  --theme Noir \
  --look "workplace stress assessment, psychological evaluation, dark professional, deep blue with silver accents" \
...

이는 모든 페이지에 적용되는 CSS를 생성합니다. --look 파라미터는 자연어 (natural language)이며, AI는 이를 실제 색상 값, 배경 그라데이션 (background gradients), 타이포그래피 (typography)로 변환합니다.

테마 프리셋 (Theme Presets)

12개의 프리셋 테마가 컬러 팔레트 (color palettes)에 매핑됩니다:

라이트 테마 (Light Themes)	다크 테마 (Dark Themes)
Minimal (연보라빛 회색)	Earthy (짙은 포레스트 그린)
...	...

AI는 평가 주제 (assessment topic)를 기반으로 테마를 선택합니다. 심리 평가 (Psychological assessments)는 다크 테마 (Noir, Mystic)를 선호하는 경향이 있습니다. 건강 설문 조사 (Health surveys)는 라이트 테마 (Fresh, Clean)로 기웁니다. --look 파라미터는 뉘앙스를 더합니다. 예를 들어 "따뜻하고 지지적인 (warm and supportive)"라는 표현은 테마가 적용되는 방식을 수정합니다.

apply-all 최적화

초기에는 페이지 유형(커버, 메인, 최종)당 style apply가 한 번씩 호출되었습니다. 각 호출은 CSS를 생성하기 위해 별도의 AI 호출을 트리거했습니다. 스타일링에만 세 번의 AI 호출이 발생한 것입니다.

해결책: style apply-all:

assess connect style apply-all \
  --theme Noir \
  --look "dark professional, deep blue with silver accents" \
...

단 한 번의 AI 호출로 스타일을 한 번 생성한 다음, 이를 모든 페이지에 적용합니다. 이를 통해 스타일링 시간을 약 15초에서 약 5초로 단축했습니다.

SVG 일러스트레이션 시스템

connect 모듈은 필드 수준의 맥락 (field-level context)을 위해 선택적인 SVG 일러스트레이션을 지원합니다. 사용자가 "장면 일러스트레이션 (scene illustrations)"을 요청하면, 각 평가 질문 위에 작은 SVG가 배치됩니다:

assess connect main-page set --field X4 \
  --description "<div><svg viewBox='0 0 280 64' width='100%' height='64'>
    <defs><linearGradient id='gd' x1='0' y1='0' x2='1' y2='0'>
...

다섯 가지 표준 일러스트레이션 패턴이 대부분의 평가 질문 유형을 커버합니다:

패턴 (Pattern)	비주얼 (Visual)	시점 (When)
A. 레이어 해체 (Layer deconstruction)	중첩된 라운드 박스	개념 이해
...	...	...

버그를 방지하는 SVG 규칙

이 시스템의 SVG에는 엄격한 규칙이 있습니다. 이는 미학적인 이유가 아니라, 나중에 Batik에 의해 PDF로 렌더링될 때 Batik이 매우 까다롭기 때문입니다:

1. 투명 배경 (Transparent background) — <rect> 배경을 사용하지 마세요. Batik은 이를 PDF에서 불투명한 검은색으로 렌더링합니다.
2. fill='none' 또는 낮은 불투명도 (low opacity) — 크고 단색인 블록을 사용하지 마세요. 인쇄 시 결과가 매우 좋지 않습니다.
3. viewBox는 반드시 명시적이어야 함 — viewBox가 없으면 Batik은 기본 치수를 사용하며, 이로 인해 PDF에서 SVG가 잘못된 크기로 렌더링됩니다.
4. <path>의 d 속성은 반드시 M으로 시작해야 함 — Batik은 이동 명령(move-to command)으로 시작하지 않는 경로(path)를 거부합니다.
5. 그라데이션 ID (Gradient IDs)는 페이지마다 고유해야 함 — 중복된 ID는 첫 번째 그라데이션이 모든 곳에 사용되는 문제를 일으킵니다.
6. <script>, <use>, 또는 <image> 사용 금지 — Batik은 스크립트를 실행하거나 외부 리소스를 가져오지 않습니다.

이 규칙들은 각각 하나의 버그 리포트로부터 만들어졌습니다. M 대신 L로 시작하는 <path>요? 그것 때문에 문제를 발견하기 전까지 일주일 내내 PDF 렌더러가 충돌했습니다.

최종 페이지: 변환이 일어나는 곳

최종 페이지는 사용자가 보상을 받는 곳입니다. 네 가지 형식이 있습니다:

형식	내용	시점
report-pdf	표시 + PDF 보고서 다운로드	평가, 시험, 보고서
...

최종 페이지는 반드시 다음 질문에 답해야 합니다: "방금 5분을 썼는데, 내가 얻은 게 뭐지?"

SKILL.md는 세 가지 요소의 구조를 강제합니다:

1. 축하 (Congratulations) — 완료를 인정함
2. 가치 선언 (Value statement) — "귀하의 맞춤형 보고서에 따르면..."
3. 공유 프롬프트 (Share prompt) — "이 내용이 유용했나요? 친구에게 공유하세요"

공유 프롬프트는 생각보다 더 중요합니다. 이것이 바이럴 계수 (viral coefficient)입니다. 공유 프롬프트가 없는 앱의 공유율은 약 2%인 반면, 자연스러운 공유 프롬프트가 있는 앱은 약 8%에 도달합니다.

--type vs --page-id 혼동

CLI에서 주의해야 할 점이 하나 더 있습니다. style set 명령은 유형(type) 또는 ID로 페이지를 지정할 수 있습니다:

# 유형별 — cover/main/final에 적용 가능
assess connect style set --type main --submit-label "Submit"

...

규칙: --type은 타입 수준의 설정(제출 버튼 텍스트, 메인 페이지 설정)을 위한 것입니다. --id는 페이지별 오버라이드(특정 커버 페이지의 타이핑 속도 등)를 위한 것입니다. --id cover_main을 의도했을 때 --type cover를 사용하면 모든 커버 페이지에 조용히 적용되는데, 이는 대개 의도한 바가 아닐 것입니다.

예외 사항: --submit-label은 --type main과 함께 사용할 수 있는 유일한 파라미터입니다. 그 외의 모든 것은 --id가 필요합니다.

교훈 (Lessons Learned)

1. 커버 페이지는 디자인의 문제가 아니라 전환 (conversion)의 문제이다. 후킹 (Hook) > 이점 (benefit) > 시간 (time) > 미리보기 (preview). "환영합니다 (Welcome)"는 후킹이 아닙니다.

2. 조작된 통계는 신뢰성을 폭파시키는 폭탄이다. 원문 자료에 없는 숫자라면 커버 페이지에 넣지 마십시오. 그것으로 끝입니다.

3. SVG 규칙은 PDF 렌더러 (renderer) 규칙이다. 브라우저에서 괜찮아 보이는 것이 Batik을 충돌시킬 수 있습니다. 제약 사항은 렌더링 시점이 아니라 생성 시점에 정의하십시오.

4. 스타일 생성은 N번이 아니라 단 한 번의 AI 호출 (AI call)로 이루어져야 한다. apply-all은 단순한 최적화가 아닙니다. 이는 페이지 전반에 걸친 시각적 일관성 (visual consistency)을 보장합니다.

5. 마지막 페이지가 바이럴 (virality)이 발생하는 지점이다. 좋은 공유 프롬프트 (share prompt) 하나가 아름다운 커버 페이지보다 더 가치 있습니다.

다음: [리포트 모듈 — 페이지 템플릿 기반 PDF 생성]