UltraExplainer은(는) 무엇을 하나요?
코드, 시스템, diff, 계획, 데이터, 개념을 하나의 자체 포함된 HTML 페이지로 변환하여 가장 중요한 아이디어를 첫 화면에서 명확하게 보여주고, 앵커된 증거로 입증합니다. UltraExplainer는 세 가지가 함께 작동합니다:
- 합성 방법 (뇌) — 무엇을 보여줄지, 무엇을 강조할지, 무엇을 생략할지 결정하고, 출처에 없는 구조를 절대 그리지 않는 방법.
references/synthesis-method.md참조. - 카멜레온 스튜디오 (공예) — 안정적이고 디자인 언어에 구애받지 않는 컴포넌트 계약(
assets/core.css)이 일곱 가지 완전한 디자인 언어(assets/themes.css)로 리스킨됩니다. 동일한 diff가 Terminal에서는 IDE 거터, Blueprint에서는 줄이 그어진 콜아웃, Editorial에서는 그림으로 렌더링됩니다. 주제에 맞는 언어를 선택합니다. 글로우는 하나의 옵션(Luminous)이며, 기본값이 아닙니다.references/aesthetic-languages.md및references/component-contract.md참조. - 상호작용 레이어(
assets/ux.js) — 하나의 공유 상태→렌더링 엔진으로 슬라이더, 시나리오 토글, 단계별 진행, 정렬/필터 가능한 테이블, 스크롤 스파이 내비게이션, 라우팅된 노드-에지 그래프를 지원합니다.references/interactivity.md참조.
정체성: 진실 + 올바른 디자인 언어 + 검증된 공예. "모든 것이 빛난다"도 아니고, "박스와 화살표 수프"도 아니고, "동일한 카드의 벽"도 아닙니다.
이 스킬을 사용해야 할 때
출력이 본질적으로 시각적, 관계적, 또는 조작 가능하고 ASCII/Markdown이 망가뜨릴 때 HTML 페이지를 사용하세요:
- 다이어그램, 아키텍처 개요, 또는 무언가가 어떻게 연결되거나 흐르는지 보여주는 노드-에지 그래프.
- diff / PR 리뷰 (변경된 코드 + 왜 중요한지 + 영향 범위).
- 계획 / 요구사항 감사 또는 비교 매트릭스.
- 메트릭 대시보드, 또는 4행 이상 / 3열 이상의 테이블.
- 메커니즘을 가르치는 개념 설명자, 또는 독자가 입력을 변경하여 느껴야 하는 대화형 모델.
- 슬라이드 데크, 또는 컨텍스트 전환을 위한 프로젝트 요약.
정직한 답변이 한 문장이나 하나의 숫자에 들어맞는다면 채팅으로 말하세요 — 페이지를 만들지 마십시오(최소 실행 가능 설명자 규칙). 빌드할 때는 한 줄 채팅 요약을 제공하고 파일을 전달하세요.
두 가지 모드 — 차터에서 결정
어느 모드에 있는지 명시하세요 (사용자가 수정할 수 있도록):
- EXPLAIN (기본값) — 논제 우선, 결론을 빨리 필요로 하는 리뷰어 / 의사 결정자 / 컨텍스트 전환자용. 현저성 제한 적용(T0 ≤ 3, T1 ≤ 7).
- TEACH — 질문 우선, 실행 가능한 정신 모델이 필요한 학습자용. 구체적-전-추상적, 예측-후-공개, 전이 확인으로 종료.
references/teaching.md참조.
간략한 방법
중요하지 않은 것을 생성하기 전에 references/synthesis-method.md를 읽으세요. 짧은 형식:
- 차터 — 한 문장: "이것은 *<아티팩트>*를 고도 *<A0–A4>*에서 *<청중>*이 *<작업>*을 할 수 있도록 설명합니다"와 모드(EXPLAIN/TEACH). 하나의 고도를 유지하세요.
- 긴장이 있는 논제 — 독자가 아직 모르는 하나의 선언적 주장(주제가 아님). 척추를 선택하세요(눈이 따르는 단일 축).
- 증거 원장 — 실제 출처를 읽으세요. 모든 노드/에지/레이블/숫자에 대해
{주장, 앵커 (file:line / symbol / git ref / metric+date), 신뢰도 (verified|inferred|assumed)}를 기록하세요. 앵커 없음 → 사실로 렌더링되지 않음. 대화형 모델의 경우 모든 슬라이더 범위/기본값과 입력→출력 함수는 앵커되거나 "예시 모델, 측정되지 않음" 스탬프가 찍힙니다. - 조정 — 모순되는 증거에 대해 논제를 검토하고, 수정하거나, 범위를 조정하거나, 보여주세요. 조용히 삭제하지 마세요.
- 최소 실행 가능 확인 — 과도하게 렌더링하지 마세요. 간단한 답변 → 히어로 문장 + 하나의 시각 자료.
- 현저성 계층화 — T0 (논제 + 척추, ≤3) / T1 (하중 지지 지원, ≤7) / T2 (영수증,
<details>/호버 안). 한도를 초과하면 분할하거나 강등하고, 절대 축소하여 맞추지 마세요. (TEACH 모드는 한도를 바람직한 난이도 예산으로 교체합니다.) - 디자인 언어 선택 — 7개 언어를 주제 × 청중 × 매체로 평가하고 한 줄을 기록하세요:
LANGUAGE: <이름> because <주제 + 청중 + 매체>. 아래 참조. - 표현 — 조작 가능성 질문을 먼저 하세요 ("독자가 입력을 변경하여 관계를 느껴야 합니까?"); 그렇다면 모델/스테퍼/시나리오를 사용하세요. 그렇지 않으면 최소 잉크 정적 형식을 선택하세요. 크기를 정량적으로 (크기/길이/위치) 인코딩하고, 동일한 상자로 하지 마세요.
- 압축 — 생략이 공예입니다. 반복을 축소하세요 ("×12 핸들러"); 하중 지지 라인만 발췌하고, 전체 파일은 발췌하지 마세요.
- 게이트 — 전달 전에 세 가지를 모두 통과하세요 (아래).
세 가지 전달 게이트 — 진실이 모든 것보다 우선
- TRUTH — 모든 노드/에지/숫자가 실제 앵커로 추적 가능함; 추론/가정된 내용은 시각적으로 제한됨; 논제가 모순되는 증거와 조정됨; 앵커를 다시 열었음. 명확하게 표시된 "확인할 수 없음 X"는 자신 있는 조작보다 낫습니다. 상호작용 거짓말(조작된 관계를 스크러빙하는 슬라이더)은 가장 큰 죄입니다.
- CRAFT — 눈가리개 테스트: 멀리서 보면 다시 칠한 템플릿이 아니라 의도적인 디자인 언어로 읽힙니다. 정확히 하나의 T0 초점.
- OBSERVED — 실제로 페이지를 렌더링하고 살펴보았습니다. 빌드하고, 열고(약 1280 및 360에서 헤드리스 스크린샷), 콘솔 오류를 캡처하고, 수평 페이지 스크롤이 없고 논제가 첫 번째 뷰포트에 있는지 확인한 다음, 자체 수정합니다. 측정하지 않은 체크리스트 속성을 주장하지 마세요.
페이지 빌드 방법 (조립)
페이지는 templates/_src/<name>.body.html의 본문 조각에서 scripts/build.mjs에 의해 조립됩니다. 가장 빠른 경로: 가장 가까운 템플릿을 복사하고 preset을 변경한 다음 내용을 조정하세요.
- 1행 지시문 (HTML 주석의 JSON)이 언어와 튜닝을 선택합니다:
<!--ux: {"title":"…","preset":"blueprint","theme":"light","fx":"flat","head":"<style>…</style>"} -->preset:blueprint | editorial | terminal | instrument | notebook | swiss | luminous(기본값luminous)presets: ["…","…"]→ 언어당 하나의 파일을 내보냄 (카멜레온 데모)theme:light | dark(프리셋의 자연스러운 튜닝을 기본값으로 함)fx:glow | flat(Luminous 전용)head/foot: 추가 마크업;<name>.head.html/<name>.foot.html사이드카도 병합됨
- 빌드는
core.css+themes.css+ux.js를 인라인하고, 프리셋의 글꼴을 링크하고,data-theme-preset/data-theme/data-fx를 페인트 전에 설정하고(FOUC 방지),templates/<name>.html을 내보냅니다. - 실행:
node scripts/build.mjs <name-filter>(필터는 부분 문자열; 생략하면 모두 빌드). - 페이지의 유일한 외부 요청은 Google Fonts(시스템 대체 포함 — 레이아웃은 절대 이에 의존하지 않음)와 Mermaid 페이지의 경우 Mermaid CDN입니다. 실패해도 올바르게 보여야 합니다.
중요 리터럴 문자열
</script>를 포함하는 JS를 인라인할 때(예: 예제 스니펫):</script>로 이스케이프하세요. 그렇지 않으면 태그를 일찍 닫아 소스 코드를 페이지에 덤프합니다.
디자인 언어 선택
장점에 따라 경로를 결정하고, 이유를 기록하세요. 전체 점수표 + 언어별 프로필은 references/aesthetic-languages.md에 있습니다.
| 주제 | 기본 언어 |
|---|---|
| 아키텍처, 스키마, 프로토콜, 인프라 토폴로지 | Blueprint |
| 개념, ADR, 사후 분석, 경영진 내러티브 | Editorial |
| Diff, PR, CLI 도구, CI 파이프라인, 로그 | Terminal |
| 메트릭, 벤치마크, 감사, 대시보드 | Instrument |
| 교육, 연습, 온보딩, 부드러운 설명자 | Notebook |
| 비교, 원칙/선언문 페이지, 상태 보고서 | Swiss |
| 시스템 흐름 데모, 제품 비전, wow 요소 브리핑 | Luminous (기본 아님) |
동점 해소: 명시적인 사용자 요청을 존중하세요("터미널로 만들어 주세요"); 세션 단조로움을 피하기 위해 회전하세요; 화려하다고 Luminous를 선택하지 마세요.
표현 선택
콘텐츠 유형이 아닌 인지 작업과 데이터 형태에 따라 경로를 결정하세요. 조작 가능성을 먼저 고려하세요. 전체 카탈로그 + 라우팅은 references/representations.md에 있습니다. 정직한 차트는 references/charts-honesty.md에 있습니다.
| 작업 | 표현 (컴포넌트) |
|---|---|
| 하나의 지배적인 핵심 / 예-아니오 | 타이포그래픽 논제 히어로(.ux-thesis), 아래에 시각 자료 하나 정도 |
| 독자가 관계를 느껴야 함 | 매개변수 모델([data-playground]) — 슬라이더 + 바인딩된 판독값 |
| 순서 / 중간 상태가 의미 | 단계별 진행([data-stepper]) — 코드↔데이터 잠금 단계 |
| 구성에 따라 다르게 동작함 | 시나리오 토글(.ux-seg[data-scenario-ctl])이 하나의 다이어그램을 다시 조명 |
| 진정한 선형 시퀀스 | 번호 목록 / 흐름 스트립(.ux-spine) — 플로우차트가 아님 |
| 분기 / 병합 / 순환 흐름 | 노드-에지 그래프(.ux-graph, ≤12 노드) 또는 테마 적용 Mermaid |
| 조밀한 쌍별 관계 | 매트릭스 히트맵(.ux-matrix) — 헤어볼 그래프보다 나음 |
| 코드 변경 / PR | 주석 diff + 평결(.ux-diff + .ux-verdict) + 영향 범위 |
| 개념 / 오해 | 초보자-대-올바른 패널(.ux-compare) + 하나의 예제 |
| 비교 / 감사 / 매트릭스 | 정렬 가능하고 필터 가능한 테이블(.ux-table, th[data-sort], data-ux-filter) |
| 정량적 메트릭 | 델타 중심 KPI 행(.ux-kpis) + 가장 가벼운 정직한 차트(.ux-bars/.ux-linechart) |
| 계획 / 로드맵 | 현재→목표 블록 + 위험 계층화된 타임라인(.ux-timeline) |
| 프레젠테이션 | 슬라이드 데크(templates/slides) |
| 맞는 것이 없음 | 테마 토큰을 사용한 맞춤 인라인 SVG |
템플릿 (templates/, 소스는 templates/_src/에 있음)
| 템플릿 | 언어 | 설명 |
|---|---|---|
chameleon.<preset>.html | 전체 7개 | 모든 언어로 렌더링된 동일한 설명 — 눈가리개 테스트 |
blueprint → playground | Blueprint | 매개변수 기반 모델(슬라이더, 바인딩된 KPI/막대, 프리셋) |
terminal-diff | Terminal | PR 리뷰: 주석 diff + 평결 + 영향 범위 |
instrument-dashboard | Instrument | KPI 마스트헤드 + 정직한 선/막대 차트 + 정렬/필터 가능한 테이블 |
editorial-concept | Editorial | 개념 설명자: 스크롤 스파이 내비게이션 + 맞춤 SVG + 초보자-대-올바른 + 사이드노트 |
notebook-teach | Notebook | TEACH 모드: 단계별 진행 + 예측-후-공개 + 전이 확인 |
swiss-comparison | Swiss | 의사 결정 매트릭스: 대형 숫자 + 정렬 가능한 비교 테이블 |
luminous-flow | Luminous | 시나리오 토글(히트/미스) + 라우팅된 그래프 + 선택적 글로우 |
mermaid | any | 테마 적용된 Mermaid (줌/팬/확장) |
slides | any | 키보드/스크롤 내비게이션이 있는 전체 뷰포트 데크 |
참조 라우팅 — 현재 출력에 필요한 것만 읽으세요
| 필요 | 읽을 것 |
|---|---|
| 무엇을/어떻게 보여줄지 결정하는 방법 (뇌) | references/synthesis-method.md |
| 7개 언어, 선택 점수표, 눈가리개 테스트 | references/aesthetic-languages.md |
토큰 계층, 모든 .ux- 컴포넌트, 빌드/조립 | references/component-contract.md |
| 표현 카탈로그 + 데이터 형태 × 작업 라우팅 | references/representations.md |
| 슬라이더, 시나리오 토글, 스테퍼, 그래프, 스크롤 스파이 — JS API | references/interactivity.md |
| 정직한 차트: 숫자 원장, 채널 순위, 축 규칙 | references/charts-honesty.md |
| TEACH 모드: 학습자 상태, 구체적 우선, 예측-공개, 전이 | references/teaching.md |
| 작업별 플레이북 (pr-review, postmortem, ADR, perf-profile, …) | references/playbooks.md |
| 자체 포함, 오버플로 안전성, 검증 루프, 전달 체크리스트 | references/self-contained.md |
| 테마 적용 Mermaid (시기 + 방법) | references/mermaid.md |
| 슬라이드 데크 | references/slides.md |
불변 규칙
- 진실은 아름다움과 공예보다 우선합니다. 앵커하거나 생략하세요. 추론/가정된 내용을 제한하세요. 레이어, 대칭, 에지, 근거를 절대 만들어 내지 마세요. 대화형 범위/함수는 앵커되거나 "예시 모델" 스탬프가 찍힙니다.
- 페이지당 하나의 언어, 장점에 따라 선택되고 기록됨. 눈가리개 테스트를 통과해야 합니다. 글로우는 Luminous 전용이며,
--fx-*를 통해 라우팅되므로data-fx="flat"이 깔끔하게 제거합니다. 정적 콘텐츠에서 지속적인 호흡/펄싱 없음. - 수평 페이지 스크롤 없음. 그리드/플렉스 자식에
min-width:0; 넓은 콘텐츠(diff, 테이블, Mermaid)는 자체overflow-x:auto컨테이너 안에서 스크롤됩니다. 360px에서 확인하세요. - 두 테마 모두 구성된 느낌. 라이트는 반전이 아닌 재조정됩니다. 페이지는 선택한 테마로 열리고 독자는 토글할 수 있습니다(프리셋당 유지됨);
prefers-reduced-motion을 존중하세요. 키보드 포커스를 보이게 유지하세요. 인쇄 안전. - 컴포넌트는 시맨틱 +
--fx-*토큰만 사용 — 절대 16진수 사용 안 함. 새로운 모양은 테마 팩에서 나오며 인라인 색상이 아닙니다. - 페이지 수준의
.node클래스를 절대 정의하지 마세요 — Mermaid가 내부적으로 사용합니다. 모든 UltraExplainer 클래스는.ux-접두사가 붙습니다. - 전달하기 전에 관찰하세요. 페이지를 렌더링하고, 보고, 잘못된 것을 수정하세요. 측정하지 않은 것을 주장하지 마세요.
최종 체크리스트
올바른 경로에 자체 포함된 문서 · 선택한 preset으로 빌드됨 · 콘솔 오류 없음 · 데스크탑 및 360px에서 수평 오버플로 없음 · 글꼴이 우아하게 저하됨 · 논제가 정확히 하나의 초점과 함께 첫 번째 뷰포트에서 명확함 · 테이블/diff/다이어그램이 자체 컨테이너 안에서 스크롤됨 · 테마(및 Luminous 글로우) 토글이 작동함 · 모든 주장이 앵커되거나 제한됨 · 페이지가 실제로 렌더링되고 검사됨.