explain-difflisted
Install: claude install-skill hun-meta/Q-Net-Study
# explain-diff — 코드 변경을 이해하기 위한 설명 문서
> 원안: Geoffrey Litt, "Understanding is the new bottleneck" (2026) 및 공개 스킬 `explain-diff`.
> 이 저장소용으로 한국어화하고 웹 앱(`web/`) 맥락에 맞췄다.
## 왜 이 스킬이 있는가
에이전트가 코드를 대량으로 작성하는 시대에는 **이해가 병목**이 된다. 이해는 두 가지 이유로 필요하다.
- **검증(verification)**: 이게 올바른가? — 에이전트가 점점 잘하게 되는 영역.
- **참여(participation)**: 다음 아이디어를 내려면 지금 무슨 일이 벌어지는지 알아야 한다 — **인간이 계속 맡아야 하는 영역.**
이 스킬의 목표는 후자다. 원시 diff(raw diff)는 "무슨 일이 있었나"의 재료일 뿐이다. 좋은 설명은 **배경 → 직관 → 코드 → 이해 확인**의 순서로, 팀이 이 변경을 나에게 가르치려고 커리큘럼을 짠 것처럼 만든다.
**속도 조절 장치 규칙**: 문서 맨 아래 퀴즈를 통과하지 못하면, 그 변경을 남에게 리뷰 요청하거나 다음 작업으로 넘어가지 않는다. 퀴즈는 "빨리 가기"가 아니라 "제대로 이해하며 가기"를 위한 브레이크다.
## 대상 diff 수집
인자로 받은 대상에서 변경 내용을 모은다. 명시가 없으면 사용자에게 무엇을 설명할지 확인한다.
- 커밋/범위: `git show <해시>` / `git diff <base>..<head>` / `git diff HEAD~1`
- 스테이지된 변경: `git diff --cached`
- 작업 중 변경: `git diff`
- PR: `gh pr diff <번호>` (gh 사용 가능 시)
변경 파일 목록(`git diff --name-only ...`)을 먼저 보고, **주변 코드를 폭넓게 탐색**해 배경을 파악한다. diff만 보고 쓰지 말 것 — �� 변경이 건드리는 기존 시스템을 읽어야 배경 섹션을 쓸 수 있다.
## 문서 구조 (4개 섹션 고정)
1. **배경 (Background)** — 이 변경과 관련된 기존 시스템을 설명한다. 독자의 사전 지식을 모르므로 두 겹으로 쓴다: ① 입문자를 위한 깊은 배경(이미 아는 사람은 건너뛸 수 있다고 명시), ② 이 변경에 직결되는 좁은 배경.
2. **직관 (Intuition)** — 변경의 **본질**을 먼저 전달한다. 세부보다 직관이 우선이다. 장난감 데이터로 구체적 예시를 들고, 그림·다이어그램을 아낌없이 쓴다. ("이 커밋의 핵심은 X를 Y로 바꿔 Z가 되게 하는 것이다"를 한 문장으로 먼저 말한다.)
3. **코드 (Code)** — 변경을 이해 가능한 순서로 묶어 고수준 워크스루를 한다. 파일을 알파벳순으로 나열하지 말고, **읽기 좋은 순서**로 재배열해 각 덩어리 앞에서 "여기서 무슨 일이 일어나는가"를 말한다(literate diff).
4. **이해 확인 퀴즈 (Quiz)** — 이 변경을 실제로 이해했는지 확인하는 5문항.