wlsdnen/explainer-page

해설 페이지 작성

언제 쓰나

• 새 해설 페이지(단일 HTML 또는 폴더)를 만들 때.
• 기존 해설 페이지의 구성·그림·설명을 크게 바꿀 때.

페이지 폴더나 프로젝트에 CLAUDE.md가 있으면 그 규칙이 이 skill보다 우선한다.

출력 언어

기본 출력 언어는 한국어다(합쇼체, lang="ko"). 사용자가 다른 언어를 요청하거나 프로젝트 CLAUDE.md가 정하면 그 언어로 쓰고, lang 속성·글꼴 스택·문체 규칙(references/writing.md)을 그 언어에 맞게 바꾼다. 나머지 규칙은 언어와 무관하게 그대로 적용한다.

결과물

• 빌드 단계 없는 자기완결 단일 index.html(인라인 CSS/JS). 영상 클립이나 이미지가 있으면 같은 폴더에 둔다.
• 외부 라이브러리는 CDN에서 정확한 버전으로 고정해 불러오거나, 오프라인이 필요하면 파일을 폴더에 넣어(vendoring) 상대 경로로 불러온다. 어느 쪽인지 사용자에게 묻거나 페이지 폴더 CLAUDE.md에 적는다.

작업 순서

1. 자료 수집과 사실 확인

• 논문·영상·코드 저장소·기술 블로그/웹 페이지를 직접 열어 읽는다. 페이지에 쓸 주장과 숫자는 원문(표·그림 번호, 강의 시각, 코드 위치, 블로그 섹션)으로 확인한다. 블로그가 논문을 인용하면 가능하면 논문에서 확인한다.
• 본문을 이해하는 데 필요한 선행 개념 목록을 만든다. 다음 단계 인터뷰의 재료다.

2. 독자 수준 인터뷰 (구성안 전에 필수)

• AskUserQuestion(다중 선택)으로 선행 개념마다 '아는 것 / 애매한 것 / 모르는 것'을 묻는다. AskUserQuestion이 없으면 같은 질문을 글로 묻는다.
• 답에 따라 더 깊이 묻는다. 본문 이해에 필요한 수준이 확정될 때까지 계속한다.
• 결과를 페이지 폴더 CLAUDE.md의 ## 독자 수준 섹션에 개념별로 기록한다. 이후 수정 때도 이 기록을 읽고 같은 수준을 유지한다. 페이지를 배포할 때 CLAUDE.md는 올리지 않는다.
• 본문 반영:
  • 모름: 본문에서 풀어 쓴다.
  • 애매: 짧은 복습 박스(<details>)로 둔다.
  • 아는 것: 설명을 생략한다.

3. 구성

• 페이지 흐름과 섹션 제목(주장 문장)을 먼저 정한다. 섹션마다 주장을 보여 줄 그림(애니메이션·정적 그림·슬라이더)과 클립을 정한다.
• 데이터·모델·평가가 나오는 주제면 데이터에서 평가 지표까지의 흐름을 섹션 구성에 넣는다.
• 세부: references/writing.md, references/visuals.md.

4. 작성

• 단일 index.html에 인라인 CSS/JS. 계산 로직은 DOM 없는 스크립트로 분리한다.
• 영상 소스가 있으면 설명 구간마다 클립을 잘라 넣는다.
• 세부: references/writing.md, references/visuals.md, references/style.md.

5. 검증

• scripts/check_page.py로 375·768·1280px 가로 넘침, 콘솔 에러, 첫 [data-widget] 터치 크기를 확인한다.
• 모든 조작부와 애니메이션 동작, 계산 로직(check.mjs)도 확인한다.
• 명령: references/verify.md.

핵심 규칙

• 사실: 논문 주장·수치는 원문에서 확인한 것만 쓴다. 모든 숫자에 논문/블로그/강의/계산/예시 꼬리표를 단다.
• 구성: 제목 + 한 줄 요약 → 섹션들 → 함정·오해 → 출처. h2는 주장 문장.
• 섹션 안: 무엇을 볼지 1~2문장 → 그림 → 왜 그런지 짧게. 유도·예외는 <details>.
• 수식: 유도 전체가 아니라 각 항의 역할과 핵심 개념.
• 그림: 주장을 독자가 직접 확인하게 하는 것만. 기본은 자동 재생 애니메이션(재생/일시정지·처음으로).
• 문체: 합쇼체(기본 언어 기준), 한 문단 3문장 이내, 비유는 섹션당 최대 하나.
• 디자인: 주제에 맞춰 페이지마다 새로 정한다(기존 페이지 복사 금지). 고정 요건은 라이트 전용(color-scheme: light), 색은 CSS 변수로 모아 관리.

완성 체크리스트

• 페이지 폴더 CLAUDE.md에 ## 독자 수준 섹션이 있다.
• '모름'으로 표시된 개념이 본문에서 모두 설명됨.
• '애매'로 표시된 개념은 <details> 복습 박스가 있다.
• 모든 h2가 주장 문장이다.
• 모든 숫자에 꼬리표가 있고, 논문·블로그 수치는 원문에서 확인했다.
• 수식마다 각 항의 역할을 설명했다.
• 데이터·모델·평가가 나오면 데이터 정제 → 입출력 포맷 → 모델 내부 처리 → 출력 → 손실·학습 → 평가 지표 흐름이 그림과 함께 있다.
• 장식용 그림이 없고, 조작부 기본값에서 현상이 바로 보이며, 그림 아래 한 줄 안내가 있다.
• 영상 소스가 있으면 구간별 클립과 출력 언어 자막(예: .ko.vtt)이 있다.
• 맨 아래 출처 목록(논문·영상·코드 저장소·블로그/웹 페이지 링크)이 있다.
• lang 속성, viewport, <title>, color-scheme: light, 색은 CSS 변수로 관리.
• 레이아웃·색이 주제의 성격에 맞고, 기존 페이지 디자인을 복사하지 않았다.
• check_page.py 통과, 모든 조작부·애니메이션 동작.
• 계산 로직이 있으면 node check.mjs 통과.