| name | explain-diff-html |
| description | 코드 변경(diff, 브랜치, 커밋 범위, PR)을 배경–직관–코드–퀴즈 4섹션의 자기완결 인터랙티브 HTML 페이지로 풀어 설명한다. "diff 설명해줘", "이 PR 설명 페이지 만들어줘", "변경 내용 인터랙티브로 정리", "이 브랜치에서 뭘 바꿨는지 학습용으로 설명" 등 변경 사항의 리치 설명을 요청하면 HTML을 직접 언급하지 않아도 반드시 이 스킬을 사용한다. workflow ship 단계의 리뷰 통과 직후(A5)에도 자동 호출된다. 문제점을 찾는 검토 요청은 review 스킬, 대화 내 짧은 텍스트 요약은 일반 응답으로 처리한다. |
Diff 설명 HTML 스킬
지정된 코드 변경을 독자가 바닥부터 이해하고 스스로 점검할 수 있는 단일 HTML 페이지로 풀어낸다.
독자는 이 변경을 처음 보는 개발자다 — 사전 지식 수준을 모르므로 깊은 배경부터 시작하되 건너뛸 수 있게 구성한다.
대상 diff 결정
| 입력 | 대상 |
|---|
| PR 번호 / URL | gh pr diff <번호> |
| 브랜치명 / 커밋 범위 | git diff main...<브랜치> 또는 지정 범위 |
| 명시 없음 + 워킹트리 변경 있음 | 워킹트리 diff |
| 명시 없음 + 워킹트리 깨끗 | 현재 브랜치 vs main (main이면 최근 머지 PR) |
| workflow ship A5 자동 호출 | git diff main...HEAD |
docs/·.claude/ 하위 변경은 설명 대상에서 기본 제외한다 — 워크플로우 산출물(topic/PLAN/STATE) 커밋이 코드 서사를 흐린다. 내용은 배경 소재로만 쓴다.
제외 적용 후 설명할 diff가 비어 있으면(문서·스킬 전용 변경) 페이지를 만들지 않는다 — ship 자동 호출이면 생략을 보고하고, 단독 호출이면 문서 diff를 포함해 만들지 사용자에게 확인한다.
진행 중 토픽의 부분 diff를 설명하게 되면, 완료 태스크까지의 스냅샷임을 페이지 상단에 명시한다.
사전 조사
배경 섹션을 쓰기 전에 변경 주변을 넓게 탐색한다.
CLAUDE.md Reference Files 표에서 변경 영역에 해당하는 docs/context/ 문서를 먼저 읽는다 (결제 플로우면 PAYMENT-FLOW, 비동기 confirm이면 CONFIRM-FLOW 등)- 변경 파일이 속한 패키지의 주변 코드(호출자, 상태 enum, 테스트)를 직접 읽어 문서와 코드의 현재 상태를 대조
- 워크플로우 토픽 산출물이면
docs/archive/<topic>/COMPLETION-BRIEFING.md 또는 활성 docs/topics/<TOPIC>.md에서 설계 의도를 가져온다
페이지 구성
한 페이지 세로 스크롤 + 섹션 헤더 + 목차로 구성한다. 최상위 탭 구조는 쓰지 않는다. 아래 4섹션 고정.
1. 배경
변경과 관련된 기존 시스템을 설명한다. 두 층으로 나눈다.
- 깊은 배경: 입문자용 — 이미 아는 독자는 건너뛰어도 된다고 명시
- 좁은 배경: 이 변경에 직접 닿는 부분
2. 직관
변경의 핵심 아이디어만 전달한다 — 전체 세부가 아니라 본질.
- 장난감 데이터로 구체 예시 구성 (예: paymentId=1, 재고 3개 상품으로 시나리오 재현)
- 그림과 다이어그램을 아끼지 않는다
3. 코드
변경을 이해 가능한 단위로 묶고 순서를 잡아 상위 수준으로 훑는다. 파일 순서가 아니라 서사 순서를 따른다.
4. 퀴즈
이해도를 점검하는 객관식 5문항. 클릭하면 정답 여부와 해설을 즉시 보여준다.
- 난이도는 중간 — 변경의 실질을 이해해야 풀 수 있되, 함정 문제 금지
- 목적은 독자가 정말 이해했는지 스스로 확인하는 것
산출물 형식
- CSS/JS 포함 자기완결 단일 HTML 파일 — 외부 리소스는 Mermaid 렌더링용 mermaid.js CDN
<script> 한 줄만 예외 (오프라인이면 다이어그램만 안 뜨고 본문은 유지되는 트레이드오프 수용)
- 저장 위치는
.archive/explanations/(gitignore 영역), 파일명은 오늘 날짜 선두의 YYYY-MM-DD-<slug>.html
- 예:
.archive/explanations/2026-07-17-dlq-quarantine-recovery.html
- 날짜 선두로 시간순 정렬을 유지하고, gitignore 영역이라 버전 관리 밖이면서
/tmp와 달리 학습 자산으로 축적된다
- slug: ship 호출이면 topic kebab, 단독 호출이면 내용 요약
- 휴대폰에서도 읽히는 기본 반응형 스타일
문체
- 본문은 한국어,
.claude/skills/_shared/conventions/writing.md의 문체·목소리 섹션을 따른다 (~다. 종결, AI체·번역체·메타 도입어 금지 — HTML 산출물이므로 구조 규칙은 제외)
- 섹션 간 전환은 매끄럽게 — 앞 섹션이 다음 섹션의 질문을 자연스럽게 남기도록 서사를 잇는다
- 명료하되 건조하지 않게, 독자를 끌고 가는 산문으로 쓴다
- 코드 식별자·기술 용어는 원형 유지, 태스크 ID·즉석 라벨 대신 내용으로 명명
- 예시 Java 코드에
var 금지 — 명시적 타입 선언
다이어그램
Mermaid와 HTML/CSS를 용도로 나눠 쓴다.
| 용도 | 도구 |
|---|
| 상태 전이도, 시퀀스, 플로우차트 | Mermaid |
| 예시 데이터를 넣는 시스템 다이어그램 | HTML/CSS |
| 사용자가 보는 UI의 극단순화 버전 | HTML/CSS |
- Mermaid가 강한 흐름·전이 표현은 Mermaid로, 예시 데이터를 박아 넣거나 자유 스타일링이 필요한 그림은 HTML/CSS로 — Mermaid에 데이터를 욱여넣어 지저분해지면 잘못 고른 것
- Mermaid 노드·엣지 라벨은
.claude/skills/_shared/conventions/writing.md의 금지 문자 표를 따른다 — HTML과 달리 Mermaid는 파일을 열기 전까지 렌더 실패를 알 수 없으므로 작성 시점에 차단
- HTML 다이어그램은 소수의 패밀리를 정해 문서 전체에서 재사용하고, 시스템 다이어그램에는 반드시 예시 데이터를 함께 넣는다
- ASCII 다이어그램 금지, 나열은 HTML 리스트로 구성
- 핵심 개념·정의·엣지 케이스는 콜아웃 박스로 강조
코드 블록
코드 블록은 <pre> 태그로 감싼다. 커스텀 div를 쓴다면 CSS에 white-space: pre-wrap이 반드시 있어야 한다 — 없으면 브라우저가 줄바꿈을 전부 접는다.
저장 전에 HTML 소스의 모든 코드 블록을 훑어 white-space: pre 또는 pre-wrap 적용을 확인한다.
