explain-it은(는) 무엇을 하나요?
조사한 코드를 작은 정적 HTML 사이트로 변환하세요. 이 코드베이스에 대한 맥락이 전혀 없는 똑똑한 독자가 따라올 수 있어야 합니다. 루트 페이지는 정신적 모델을 구축하고, 각 주제별 페이지가 있으며, 사이드바가 연결해줍니다.
목표 수준: "너무 쉽지도 않고 너무 어렵지도 않은 간단한 언어." 독자를 얕보지 말고, 저장소 지식을 전제하지 마세요.
워크플로
1. 설명하기 전에 조사하세요
읽지 않은 코드는 설명하지 마세요. 모든 주제에 대해 실제 소스를 읽으세요: 변경된 줄, 포함하는 함수, 그리고 최소 하나의 호출자를 읽어서 "이 코드는 도대체 언제 실행되지?"라는 질문에 실제 이야기로 답할 수 있어야 합니다. 어떤 주장이 다른 사람(리뷰 코멘트, 이슈)에게서 나온 것이라면, 먼저 코드와 대조하여 확인하고 사실이 아닐 경우 그렇게 말하세요.
2. 사이트 계획 세우기
- 루트 페이지 하나 (
index.html): 입문서입니다. 약 2분 안에 독자의 시스템에 대한 정신적 모델을 구축하고 모든 주제 페이지로 연결됩니다. - 주제당 페이지 하나 (
01-<slug>.html,02-<slug>.html, …): 각 페이지는 하나의 변경 사항, 버그, 결정, 또는 서브시스템을 설명합니다. 3~7페이지가 적당하며, 9페이지를 넘지 않도록 주제를 병합하세요. - 모든 페이지에 공유 사이드바: 모든 페이지를 읽기 순서대로 나열하고 현재 페이지를 강조 표시합니다. 페이지는 상대
<a href>로 연결된 일반 파일입니다. 사이트는 디스크에서 직접 (file://) 열었을 때도 작동해야 하므로 라우터, 빌드 단계, 외부 JS가 필요 없습니다.
폴더 위치가 명확하지 않은 경우에만 사용자에게 위치를 물어보세요. 그렇지 않으면 작업 디렉터리 옆에 적절한 이름의 폴더(예: docs/explainers/<topic>/)를 만들고 위치를 알려주세요.
3. 각 페이지 작성하기
방법은 references/writing-guide.md를 따르세요. 첫 페이지를 작성하기 전에 반드시 읽어야 합니다. 절대 타협할 수 없는 사항:
- 입문서 우선. 루트 페이지는 주제 페이지가 필요한 모든 도메인 개념을 소개하며, 각 개념에 하나의 구체적인 메타포를 사용하세요 (예: "릴리스는 복사본입니다. 실행 중인 작업은 하나의 복사본을 고정합니다."). 메타포는 한 번 소개한 후 그대로 재사용하세요. 한 개념에 두 개의 메타포를 쌓지 마세요.
- 모든 주제를 런타임에 근거하세요. 각 주제 페이지는 "이 코드는 도대체 언제 실행되지?" 이야기로 시작합니다: 2~4개의 액터 비트 (사용자가 X를 한다 → 시스템이 함수 Y를 실행한다 → 그 안의 작은 작업). 간단한 언어 이야기와 함께 — 대신하지 않고 — 실제 함수 이름을 코드 폰트로 표시하세요.
- 변경 사항을 diff로 보여주세요. 이전 코드와 새로운 코드를 빨강/초록 diff 블록으로 표시하고 헤더에 파일 경로를 표시하며, 핵심만 남기고 1~3개의 인라인 주석으로 이유를 지적하세요. 무엇을 설명하지는 마세요.
- "왜"를 정량화하세요. "느리다"는 금지입니다. "요청당 수백 KB, 아무 이유도 없이 시간의 ~99%"가 기준입니다. 위험도 마찬가지입니다: 구체적인 입력/상태와 잘못된 결과를 명명하세요.
- 버그와 결정을 분리하세요. 어떤 것이 결함이 아니라 방어 가능한 제품 선택이라면, 실수가 아니라 결정으로 제시하고 트레이드오프를 함께 설명하세요.
- 루트 페이지를 스코어보드로 끝내세요: 모든 항목의 상태 표 (완료 / 제안 / 보류)를 코드베이스 내 위치와 함께 제공하세요.
4. HTML 구축하기
references/site-template.html을 모든 페이지의 시작점으로 복사하세요. 이 템플릿에는 디자인 토큰, 사이드바, 그리고 모든 컴포넌트의 작동 예제(스토리 블록, 콜아웃, diff 블록, 상태 표, 태그)가 포함되어 있습니다. 그 다음:
- 각 페이지를 완전히 독립적으로 유지하세요 (모든 CSS는 페이지 내에 인라인). 사이드바는 각 페이지에 복사되며 현재 항목에는
class="on"이 표시됩니다. references/design-system.md의 토큰과 컴포넌트 규칙을 따르세요. 팔레트, 간격, 글자 크기 체계를 그대로 유지하여 여러 페이지 사이트가 하나의 시스템처럼 보이게 하세요. 템플릿에는 라이트/다크 토글과 접을 수 있는 사이드바가 포함되어 있습니다. 이를 제거하지 말고 모든 페이지에 유지하세요.- 템플릿에 이미 있는 Google Fonts 링크를 제외한 외부 종속성은 없어야 합니다 (폰트 스택은 오프라인에서도 깔끔하게 폴백됨). 템플릿의 테마 토글 스니펫 외에 JS는 없어야 합니다.
5. 전달하기 전에 확인하세요
루트 페이지와 최소 하나의 주제 페이지를 열거나 렌더링하여 (또는 다시 읽어서) 확인하세요: 모든 사이드바 링크가 제대로 작동하는지, 본문에서 언급된 모든 코드 식별자가 코드베이스에 정확히 동일한 철자로 존재하는지, 모든 diff가 실제 파일과 개념적으로 일치하는지, 스코어보드 상태가 최신인지 확인하세요. 그런 다음 사용자에게 폴더 경로를 알려주고, 환경이 허용하면 루트 페이지를 열어주세요.
흔한 함정
- 코드 대신 대화 내용의 기억으로 설명하기 — 설명자는 모든 낡은 주장을 그대로 물려받습니다. 소스를 다시 읽으세요.
- 메타포 표류: 한 페이지에서 "복사본"이라고 부르고 다음 페이지에서 "동결 복사본"이라고 부르는 것. 모든 곳에서 하나의 용어만 사용하세요.
- 60줄을 그대로 붙여넣는 diff 블록. 핵심만 남기고 주변 2~4줄의 맥락 줄만 유지하세요.
- diff를 한 줄씩 설명하는 산문. diff는 무엇을 보여줍니다. 산문은 왜 중요한지와 언제 실행되는지만 담아야 합니다.
- 색인 페이지에만 있는 사이드바. 모든 페이지는 전체 사이드바를 포함해야 합니다.
- 유치한 말투 ("컴퓨터는 특별한 상자에 있는 것들을 기억합니다"). 독자는 똑똑합니다 — 단지 이 코드베이스를 모를 뿐입니다.