설계 분석 및 이해도 검증 가이드 (Explain Design)

사용자가 지정한 설계·결정·아키텍처를 분석하여, 구현 전 리뷰의 인지부채를 방지하고 완벽한 이해를 돕는 인터랙티브 HTML 설명서를 한국어로 작성하십시오.

이 스킬은 explain-diff-html의 설계 단계 짝입니다. diff는 "무엇이 바뀌었나"를 설명하지만, 설계는 **"왜 이 방향인가 · 어떤 대안을 버렸나 · 무엇이 터질 수 있나"**를 설명해야 합니다. 코드 워크스루가 아니라 트레이드오프와 영향 범위가 중심입니다.

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

🔗 대상 해석 (Target Resolution)

인자로 받은 대상에 따라 설계 내용을 아래 방식으로 수집한 뒤 분석하십시오. 전체 문서를 통째로 읽지 마십시오 — 확정된 결정만 뽑는 것이 design-workflow 원칙입니다.

LEDGER="${CLAUDE_PLUGIN_ROOT}/scripts/ledger/ledger"

"$LEDGER" current --file <task> --ids-only     # 어떤 결정(D-n)이 있는지
"$LEDGER" current --file <task>                # 확정 결정 본문
"$LEDGER" ls                                   # task-file 미지정 시 후보 나열

current가 비어 있으면 아직 확정된 설계가 없는 것입니다. 그럴 때는 진행 로그/제안 내용을 대상으로 분석하되, "아직 미확정 설계"임을 HTML 상단에 명시하십시오. 전체 문서를 통째로 읽어 우회하지 마십시오.

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

1. 문제 정의 & 배경 (Problem & Context): 이 설계가 무엇을, 왜 지금 풀려는지. 초보자도 이해할 수 있는 거시적 배경에서 시작해, 기존 시스템의 제약과 이번 설계가 건드리는 지점까지 매끄럽게 좁혀 가십시오.
2. 설계 직관 (Design Intuition): 세부 스펙보다 핵심 아이디어가 왜 이 방향으로 자연스러운지를 설명합니다. 간단한 샘플 데이터(Toy Data)나 HTML 컴포넌트로 구현한 시각적 다이어그램(플로우·시퀀스·상태 전이 등)을 적극 활용하십시오. (ASCII 다이어그램은 금지합니다.) 구조가 복잡해 손으로 그린 그림이 감당되지 않으면 아래 구조 다이어그램 절을 따르십시오.
3. 결정 & 대안 비교 (Decisions & Alternatives): 각 결정(D-n)마다 택한 안 vs 버린 대안, 그리고 트레이드오프를 표 또는 카드로 나란히 제시합니다. "왜 A가 아니라 B인가"의 근거가 핵심입니다. 결정이 서로 의존하면 그 의존 관계도 드러내십시오.
4. 영향 범위 & 리스크 (Blast Radius & Risks): 이 설계가 어떤 레이어·모듈·데이터에 파급되는지, 그리고 리뷰어가 정독해야 할 위험 지점을 명확히 표시합니다. 특히 ① 돈·권한·개인정보 ② 스키마 마이그레이션 ③ 트랜잭션·락·동시성 경계 ④ 호출자가 많은 심볼(high fan-in) 변경은 별도로 강조하십시오. 검증되지 않은 가정(unstated assumption)이 있으면 그것도 명시하십시오.
5. 설계 Playground: 결정의 파라미터를 사용자가 직접 움직여 "언제 이 결정이 뒤집히는가" 를 스스로 찾게 하는 조작 가능한 모델. 아래 상세 규격을 따르십시오.
6. 이해도 검증 퀴즈 (Quiz): 이 설계의 트레이드오프와 동작 원리를 실제로 이해해야만 풀 수 있는 중간 난이도의 객관식 문제를 반드시 5개 출제하십시오. "왜 이 대안을 버렸나", "이 결정이 어떤 리스크를 감수하나" 같은 판단형 문항을 포함하십시오. 사용자가 선지를 클릭하면 정답 여부와 상세한 한국어 해설이 화면에 표시되는 인터랙티브 JS 로직을 포함하십시오.

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

코드 스니펫을 넣을 때는 반드시 <pre> 태그를 사용하거나 CSS에 white-space: pre-wrap을 적용하여 줄바꿈이 깨지지 않게 하십시오.

🎮 설계 Playground 규격

왜 퀴즈만으로는 부족한가

퀴즈는 인출 연습(retrieval practice) 이라 선언적 사실에는 강하지만, 설계 검토가 요구하는 반사실적 판단으로는 잘 전이되지 않습니다. 더 위험한 것은 유창성 착각 입니다 — 잘 정리된 설명은 정확성과 무관하게 수용률만 올리고(Bansal et al. CHI 2021), 객관식을 맞히면 확신만 오릅니다. 이해 없이 확신만 오른 상태는 산출물이 없는 상태보다 나쁩니다.

diff 단계의 진단 질문이 "이 줄을 바꾸면 무엇이 깨지는가"라면, 설계 단계의 진단 질문은 "언제 이 결정이 뒤집히는가" 입니다. 결정은 진공이 아니라 가정(트래픽 규모, 데이터 증가율, 실패율, 팀 규모, 비용 상한) 위에 서 있고, 그 가정이 어디까지 움직여야 채택안이 대안에게 지는지를 알아야 결정을 이해한 것입니다. 객관식은 그 손익분기점을 물을 수는 있어도 찾게 할 수는 없습니다.

최소 조건 (셋 다 만족하지 못하면 넣지 마십시오)

1. 조작 가능 — 사용자가 설계 가정(파라미터)을 직접 바꾼다.
2. 관측 가능 — 조작 결과로 채택안과 대안의 지표가 눈에 보이게 갈라진다.
3. 결론 변경 가능 — 파라미터 범위 어딘가에서 승자가 실제로 바뀌어야 한다. 어떤 값에서도 채택안이 이긴다면 그것은 Playground가 아니라 설득 자료입니다. 그럴 때는 "이 결정은 탐색한 범위 전체에서 견고함"을 명시하고, 대신 가정이 깨지는 조건을 노출하십시오.

충실도 배지 (Fidelity — 상단에 필수, 설계 단계에서 특히 엄격하게)

설계 Playground의 수치는 대개 측정값이 아니라 투영값입니다. 그럴듯한 그래프가 근거 없는 확신을 만드는 것이 이 산출물의 최대 위험이며, AI가 만든 인터랙티브 설명물의 대표 실패 모드는 "코드도 멀쩡하고 보기에도 멀쩡한데 상호작용 논리가 틀린 것"입니다(EE-Eval, arXiv:2606.31012). 배지 없는 Playground는 만들지 마십시오.

각 파라미터 옆에 그 수치의 출처를 표기하십시오(실측 / 인용 / 사용자 가정 / 미확인). 미확인 값이 결과를 좌우하면 그 사실 자체를 결과 화면에 띄우십시오 — 그것이 곧 검증되지 않은 가정의 위치입니다.

Playground 유형 (대상에 맞는 것을 1~2개만 고르십시오)

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

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

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

예측이 틀리는 순간이 이 섹션의 전부입니다. 따라서 예측이 갈릴 만한 지점을 고르십시오 — 누가 봐도 뻔한 값을 묻지 마십시오.

금지 사항

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

• 승자가 바뀌는 구간이 있는가? 없다면 "견고함 + 가정이 깨지는 조건"으로 대체했는가?
• 충실도 배지가 상단에 있고, 파라미터마다 출처가 붙어 있는가? 출처 없는 숫자가 0개인가?
• 예측 게이트가 1회 있고, 제출 전 정답이 화면·소스 어디서도 안 읽히는가?
• 조작 대상이 5개 이하인가?
• "언제 이 결정이 뒤집히는가" 에 Playground만으로 답할 수 있는가?
• 외부 네트워크 요청이 0인가?
• 다이어그램을 넣었다면 확정된 결정만 그렸고, 이미지는 data: URI로 인라인했는가?

🧭 구조 다이어그램

설계 검토에서 구조 자체가 판단의 대상일 때 — 컴포넌트 경계를 새로 긋거나, 레이어 의존 방향을 정하거나, 상태 모델·파이프라인 경로를 설계할 때 — 다이어그램을 넣으십시오.

추측으로 그리지 마십시오. 확정된 결정과 실제 코드에서 확인한 것만 그립니다. 확인 못 한 부분은 그리지 말고 글로 "미확인"이라고 쓰십시오.

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

설계 전용 규칙

• 확정된 것만 그립니다. 결정 원장(ledger current)의 ## 현재 설계에 있는 것만 다이어그램에 넣으십시오. 미확정 대안을 그리면 그림이 결정을 앞질러 버립니다. 대안 비교는 3번 섹션의 표로 하고, 다이어그램은 채택안 한 장입니다.
• current가 비어 있어 상단에 미확정 표기를 달았다면, 다이어그램 캡션에도 같은 표기를 유지합니다.
• 아직 코드가 없으므로 --repo-root 근거는 대개 붙지 않습니다. 따라서 배지는 🔵 구조 모델이 기본이며, 이것이 "제안된 구조이지 현재 코드가 아님"을 뜻한다고 캡션에 밝힙니다.
• 다이어그램은 설계 직관(2번) 또는 영향 범위(4번) 안에 놓습니다. Playground를 대체하지 않습니다 — 구조를 보여줄 뿐 가정을 흔들어 보는 모델이 아닙니다.

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

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

🤝 워크플로우 상 위치

이 스킬은 구현 전 설계 리뷰 단계에 놓입니다. 흐름:

설계 논의 → (explain-design-html: 설계 이해·검토) → ledger decide 로 확정 → /impl-pipeline 구현 → (explain-diff-html: 변경 이해)

• 확정 전(ledger decide 이전)에 결정 근거·대안·리스크를 리뷰어에게 한 번에 각인시켜, 확정 판단의 병목을 줄이는 것이 이 스킬의 존재 이유입니다.
• 이미 확정된 설계라도, 구현에 들어가기 전 팀·본인의 이해도를 맞추는 용도로 재사용할 수 있습니다.
• 산출물은 판단을 돕는 aid이지 gate가 아닙니다. 생성에 실패해도 원문(결정 원장)으로 리뷰는 그대로 진행합니다.