moonklabs Explain Diff — 순수판 (HTML 직접 작성)
먼저 확인: 대부분의 경우
explain-diff-html가 맞는 선택이다. 그쪽은 마크다운 + DSL만 쓰면render.py가 CSS/JS/목차/퀴즈/git 추출을 처리해 작성량이 84% 적고, diff를 손으로 옮겨 적지 않으므로 원본과 어긋날 위험도 없다. 이 순수판은 DSL로 표현할 수 없는 레이아웃이 필요하거나 Python을 쓸 수 없을 때만 쓴다.
지정된 코드 변경 사항에 대해 풍부하고 대화형(interactive)인 설명을 만들어 주세요.
소스부터 확정한다. 특별한 언급이 없으면 베이스 브랜치(기본 main) 대비 현재 브랜치를 설명 대상으로
삼는다. "PR #N 해설"이면 gh pr checkout N 후 그 diff와 gh pr view N의 제목/설명을 함께 쓴다.
"스테이징된/워킹트리 변경"을 요청받으면 각각 git diff --staged/git diff로 범위를 잡는다. 변경이
없으면 문서를 만들지 말고 그대로 "변경 없음"을 보고한다.
언어: 본문·다이어그램·퀴즈는 사용자 대화 언어(기본: 한국어)로 작성한다. 코드 식별자·기술 용어는 원형 유지.
근거 원칙: 모든 사실 문장은 diff의 hunk나 실제로 읽은 파일에 근거해야 한다. diff·PR 설명 어디에도 없는 의도·동기를 추측해서 쓰지 마라. 바뀐 파일이 많으면(50개 이상) 대표적인 변경으로 묶어 설명하되, 바뀐 경로 자체는 빠짐없이 나열한다 — 조용히 자르지 마라.
다음 섹션들을 포함해야 합니다:
- Background (배경): 이 변경사항과 관련된 기존 시스템을 설명합니다. (이를 위해 주변 코드를 넓게 탐색해야 합니다.) 독자가 얼마나 알고 있는지 알 수 없으므로 초보자를 위한 깊이 있는 배경 지식(독자가 이미 익숙하다면 건너뛸 수 있음을 명시)을 포함한 뒤, 변경 사항과 직접 관련된 구체적인 배경을 설명합니다.
- Intuition (직관적 이해): 코드 변경의 핵심 직관을 설명합니다. 전체적인 세부사항보다는 본질을 설명하는 데 집중합니다. 간단한 예시 데이터를 사용해 구체적인 사례를 듭니다. 그림과 다이어그램을 적극 활용합니다.
- Code (코드 설명): 변경된 코드를 고수준에서 설명합니다. 이해하기 쉬운 방식으로 변경 사항을 그룹화/정렬합니다.
- Quiz (퀴즈): 이 PR에 대한 독자의 지식을 점검할 수 있는 5개의 질문을 만듭니다. 난이도는 중간 정도여야 하며, 단순히 꼬아낸 문제가 아니라 PR의 실질적인 내용을 이해해야 맞출 수 있어야 합니다. 목표는 독자가 실제로 잘 이해했는지 확인하도록 돕는 것입니다. 대화형 객관식 질문으로 제공되어야 하며, 사용자가 클릭하면 정답 여부와 피드백을 보여주어야 합니다.
포맷:
- CSS와 JavaScript가 포함된 단일 자기 완결형(self-contained) HTML 파일로 출력합니다. 전체를 섹션 헤더와 목차가 포함된 하나의 긴 페이지로 만듭니다. 최상위 구조에 탭을 사용하지 마세요. 모바일 기기에서도 볼 수 있도록 기본적인 반응형 스타일을 적용하면 좋습니다. 파일은 코드 저장소 외부의 컴퓨터 전역 위치에 두고, 파일 이름은 항상
YYYY-MM-DD-형식의 오늘 날짜로 시작하도록 하세요. 그래야 파일이 시간순으로 정렬되고 버전 관리 대상에서 제외됩니다. 예:/tmp/2026-01-12-explanation-<slug>.html- 저장소 안에 출력하지 마세요 — 하드 룰입니다. 같은 경로에 이미 파일이 있다면 조용히 덮어쓰지 말고 슬러그를 바꾸거나 확인을 구하세요.
- 마틴 클렙만(Martin Kleppmann)의 명확성과 흐름을 살려 읽기 쉽고 클래식한 스타일로 작성해 주세요. 섹션 간의 전환은 매끄러워야 합니다.
- 다이어그램 관련 팁: 이상적으로는 다양한 상황을 설명할 수 있도록 설명 전체에서 재사용 가능한 소수의 다이어그램 유형을 선택하는 것이 좋습니다. 유용한 다이어그램의 종류:
- UI 변경 사항을 설명하기 위한, 앱에서 사용자가 보는 화면의 매우 단순화된 버전.
- 구성 요소 간의 데이터 흐름이나 통신을 보여주는 시스템 다이어그램. 여기에 예시 데이터를 반드시 포함하세요!
- ASCII 다이어그램은 사용하지 마세요. 다이어그램에는 항상 심플한 HTML 디자인을 사용하고, 목록에는 HTML 리스트 태그 등을 사용하세요.
- 코드 블록에는 항상
<pre>태그를 사용하세요. 커스텀 스타일의 div를 사용하는 경우 CSS에 반드시white-space: pre-wrap이 포함되어 있어야 합니다. 그렇지 않으면 브라우저가 모든 줄바꿈을 한 줄로 축소해 버립니다. 파일을 저장하기 전에 HTML 소스의 각 코드 블록을 점검하여 CSS에white-space: pre또는pre-wrap이 포함되어 있는지 확인하세요. - 코드 블록에는 code highlighter 라이브러리를 적용하여 가시성을 높인다.
- 코드 블록의 diff 는
diff라이브러리를 사용해서 색상을 다르게 표시해야 합니다.
- 코드 블록에는 항상
- 핵심 개념이나 정의, 중요한 엣지 케이스 등에는 콜아웃(callout)을 사용하세요.
- 파일을 저장한 뒤 열어서 목차 링크와 퀴즈 정답/오답 클릭이 실제로 동작하는지 최소 1문항 확인하세요. 브라우저 도구가 없으면 HTML/JS 소스를 다시 읽어 점검하고, 어느 쪽으로 확인했는지 결과 보고에 남기세요.