코드 변경점 분석 및 이해도 검증 가이드 (Explain Diff)

사용자가 지정한 코드 변경 사항을 분석하여, 인지부채를 방지하고 완벽한 학습을 돕는 인터랙티브 HTML 설명서를 한국어로 작성하십시오.

이 파일은 사용자의 맥 컴퓨터 내에 단일 독립형 HTML 파일(CSS 및 JavaScript 포함)로 저장되어야 하며, 파일 이름은 항상 오늘 날짜로 시작해야 합니다. (예: /tmp/2026-07-15-explanation.html)

📋 필수 포함 섹션 (모든 내용은 한국어로 작성)

1. 배경 지식 (Background): 이 변경 사항과 관련된 기존 시스템 구조를 설명합니다. 초보자도 이해할 수 있는 거시적인 배경지식부터 시작하여, 이번에 변경된 코드와 직접 연관된 미시적인 맥락으로 매끄럽게 연결되도록 하십시오.
2. 핵심 직관 (Intuition): 세부 코드 구현 내용보다는 '왜 이렇게 바꿨는지' 본질적인 이유를 설명합니다. 간단한 샘플 데이터(Toy Data)나 HTML 컴포넌트로 구현한 시각적 다이어그램을 적극 활용하십시오. (ASCII 다이어그램은 금지합니다.) 구조가 복잡해 손으로 그린 그림이 감당되지 않으면 아래 구조 다이어그램 절을 따르십시오.
3. 코드 워크스루 (Code): 바뀐 코드를 인간이 직관적으로 이해할 수 있는 논리적 단위로 그룹화하여 설명합니다. 코드 블록은 반드시 <pre> 태그를 사용하거나 CSS에 white-space: pre-wrap을 적용하여 줄바꿈이 깨지지 않게 하십시오.
4. 인터랙티브 Playground: 사용자가 값을 직접 바꾸고 결과를 관측하며 이해하는 조작 가능한 모델. 아래 상세 규격을 따르십시오.
5. 이해도 검증 퀴즈 (Quiz): 이 변경 사항의 실질적인 동작 원리를 알아야만 풀 수 있는 중간 난이도의 객관식 문제를 반드시 5개 출제하십시오. 사용자가 선지를 클릭하면 정답 여부와 상세한 한국어 해설이 화면에 표시되는 인터랙티브 JS 로직을 포함하십시오.

퀴즈는 반드시 Playground 뒤에 옵니다. Playground가 모델을 만들고, 퀴즈가 그 모델을 인출합니다.

🎮 인터랙티브 Playground 규격

왜 퀴즈만으로는 부족한가 (이 섹션의 존재 이유)

퀴즈는 인출 연습(retrieval practice) 입니다. 선언적 사실에는 강하지만 코드 검토가 실제로 요구하는 절차적·반사실적 이해로는 잘 전이되지 않습니다(MOOC 함수형 프로그래밍 n=2,166에서 인출 단서는 시험 성적·최종 학점 어느 쪽도 개선하지 못함). 더 위험한 것은 유창성 착각(fluency illusion) 입니다 — 객관식을 맞히면 확신만 오르고, 잘 붙은 설명은 정확성과 무관하게 수용률을 올립니다(Bansal et al. CHI 2021). 이해 없이 확신만 오른 상태는 산출물이 아예 없는 상태보다 나쁩니다.

cognitive debt를 명명한 Margaret-Anne Storey의 진단 질문은 셋입니다: ① 이게 뭘 하는가 ② 왜 이렇게 만들었는가 ③ 이 줄을 바꾸면 무엇이 깨지는가. ③은 객관식으로 물을 수는 있어도 풀게 할 수는 없습니다. 반사실은 조작해 봐야 답이 나옵니다. Playground는 퀴즈를 대체하지 않고, 퀴즈가 인출할 모델을 먼저 만듭니다.

최소 조건 (셋 다 만족하지 못하면 Playground가 아니므로 넣지 마십시오)

1. 조작 가능 — 사용자가 값·스위치·단계를 직접 바꾼다.
2. 관측 가능 — 조작 결과가 즉시 눈에 보이게 달라진다.
3. 결론 변경 가능 — 어떤 조작에서는 사용자가 내릴 판단이 실제로 뒤집혀야 한다. 조작해도 결론이 늘 같다면 그것은 장식이므로 삭제하십시오.

충실도 배지 (Fidelity — 상단에 필수)

AI가 만든 인터랙티브 설명물의 대표 실패 모드는 "코드도 멀쩡하고 보기에도 멀쩡한데 상호작용 논리가 틀린 것"입니다(EE-Eval, arXiv:2606.31012). 근사 모델을 실제처럼 보이게 하는 것은 이 스킬이 만들 수 있는 최악의 산출물입니다 — 틀린 확신을 제조하기 때문입니다. 배지 없는 Playground는 만들지 마십시오.

F1/F2를 우선하고, F3으로 내려갈 때는 근사한 부분과 왜 실제로 못 돌리는지를 한 줄로 밝히십시오.

Playground 유형 (대상에 맞는 것을 1~2개만 고르십시오. 전부 넣지 마십시오)

정상 경로는 코드가 무엇을 하는지 보여주고, 실패 경로는 코드가 무엇을 틀리는지 보여줍니다. ④를 넣을 수 있으면 대개 ④의 정보량이 가장 큽니다.

필수 상호작용 프로토콜: 예측 → 관측 → 해설

각 Playground의 첫 상호작용 1회는 반드시 예측 게이트를 통과해야 하며, 자유 조작(샌드박스)은 그 뒤에 열립니다.

1. 조작 UI는 보여주되 결과 영역은 가립니다.
2. 한 문장으로 묻습니다 — "이 값을 X로 바꾸면 결과가 어떻게 될까요?"
3. 제출 전에는 답을 어떤 형태로도 노출하지 않습니다. 힌트·예시 답·기울임 단서·"참고로…" 문장을 붙이지 말고 질문 뒤에서 멈추십시오.
4. 제출 후 예측과 실제를 나란히 표시하고, 어긋났으면 어디서 갈렸는지 해설합니다.
5. 그 다음부터 자유 조작을 개방합니다.

예측이 틀리는 순간이 이 섹션의 전부입니다. 맞히면 확인이고, 틀리면 그 지점이 인지부채가 있던 정확한 위치입니다. 따라서 예측이 갈릴 만한 지점을 고르십시오 — 누가 봐도 뻔한 값을 묻지 마십시오.

금지 사항

자가 검증 (생성 직후 반드시 통과)

• 조작하면 사용자의 판단이 뒤집히는 경로가 최소 하나 있는가?
• 충실도 배지가 상단에 있는가? F3이면 근사한 부분을 명시했는가?
• 예측 게이트가 1회 있고, 제출 전 정답이 화면·소스 어디서도 안 읽히는가?
• 조작 대상이 5개 이하인가?
• "이 변경을 되돌리면 무엇이 깨지는가" 에 Playground만으로 답할 수 있는가?
• 외부 네트워크 요청이 0인가?
• 다이어그램을 넣었다면 이미지는 data: URI로 인라인했는가?

🧭 구조 다이어그램

이 변경을 이해하는 데 구조 자체가 설명의 본체일 때 — 호출 체인이 여러 서비스를 건너뛰거나, 상태 전이가 새로 생겼거나, 파이프라인 경로가 바뀌었을 때 — 다이어그램을 넣으십시오.

추측으로 그리지 마십시오. diff와 실제 호출 체인에서 확인한 것만 그립니다. 확인 못 한 경로는 그리지 말고 글로 "미확인"이라고 쓰십시오.

diff 설명에서 자주 맞는 타입:

diff 전용 규칙

• 변경 전/후 두 장을 만들지 마십시오. 한 장에 그리고, 이번 변경으로 생긴 노드·엣지를 variant: "emphasis"로 구분한 뒤 캡션에서 "강조된 부분이 이번 변경"이라고 밝힙니다. 두 장 비교는 독자가 눈으로 diff를 다시 뜨게 만들어 인지부채를 오히려 늘립니다.
• architecture 타입이면 --repo-root <레포 경로>로 실제 코드 근거를 붙일 수 있습니다. 붙였을 때만 🟢 코드 근거 배지를 쓰고, 커밋 해시를 함께 적습니다.
• 다이어그램은 핵심 직관(2번 섹션) 또는 코드 워크스루(3번 섹션) 안에 놓습니다. Playground를 대체하지 않습니다 — 구조를 보여줄 뿐 조작 가능한 모델이 아닙니다.

⚠️ 퀴즈 출제 시 주의사항 (Critical Constraints)

• 정답 길이 균일화: 정답 선택지만 유독 길어지는 현상을 방지하기 위해, 모든 선택지(A~D)의 텍스트 길이를 엄격하게 균일한 수준으로 맞추십시오.
• 정답 위치 무작위화: 정답이 특정 번호에 편향되지 않도록 A, B, C, D 위치에 고르게 무작위로 분산시키십시오.
• 사용자가 버튼을 누르기 전까지 소스코드 분석을 통해 정답을 미리 유추할 수 없도록 스크립트 구조를 안전하게 설계하십시오.

🔗 대상 해석 (Target Resolution)

인자로 받은 대상에 따라 변경 내용을 아래 방식으로 수집한 뒤 분석하십시오.

diff가 크면 논리적 단위(슬라이스/파일 그룹)로 나눠 섹션을 구성하되, 4개 필수 섹션 구조는 유지하십시오.

🤝 impl-pipeline 연동

/impl-pipeline이 이 스킬을 호출하는 지점은 두 곳입니다. 대상은 언제나 해당 슬라이스의 diff입니다.

슬라이스 ID(S-n)와 base 브랜치가 전달되면 범위를 좁혀 분석합니다 — 체크포인트 커밋이 있으면 git diff <슬라이스 커밋>^ <슬라이스 커밋>, 없으면 git diff <base>...HEAD -- <슬라이스 글롭>. 산출 HTML 파일명은 날짜-S{n}-explanation.html 형태로 저장하고, 경로를 run.json 의 해당 슬라이스 artifacts.explain 에 기록하십시오 (리뷰 데스크가 이 경로로 엽니다).