D3 Explainer (저자용 인터랙티브 HTML)은(는) 무엇을 하나요?

<skill-dir> 은 이 스킬의 기본 디렉토리를 의미합니다. Claude Code가 스킬 로드 시 표시합니다 (플러그인으로 설치 시: ${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer; 수동 복사 시: ~/.claude/skills/d3-explainer). 모든 명령어에서 실제 경로로 대체하세요. <wording-dir> 은 <skill-dir>/../d3-scientific-wording을 의미하며, 모든 D3 플러그인이 제공하는 공유 워딩 스킬입니다.

하나의 오프라인 HTML 파일로, 연구 프로젝트를 작성하는 사람들에게 프로젝트를 설명합니다: 질문이 무엇인지, 어떤 격차를 해소하는지, 핵심 아이디어가 어떻게 작동하는지, 각 유도 과정이 어떻게 진행되고 그 이유는 무엇인지, 코드 내 모든 내용이 어디에 있는지, 증거가 무엇을 보여주는지, 그리고 아직 열려 있는 문제가 무엇인지. 대화형 그림이 직관을 전달하며, 텍스트는 출처에 가깝게 유지되고 그렇게 명시됩니다.

독자는 저자와 공동 저자입니다. 이는 아래의 거의 모든 것을 결정합니다:

그들은 해당 분야를 알고 있습니다. 그들의 노트에 취약점으로 표시되지 않는 한 교과서 배경 지식은 생략합니다.
그들은 이해하기를 원하므로, 정직함이 세련미보다 우선합니다: 가정, 논문 대 코드의 불일치, 미해결 질문은 별도 섹션을 가지며, 해석은 그렇게 표시됩니다.
그들은 자신의 파일에 대해 주장을 확인할 것이므로, 모든 실질적 주장은 출처를 가리키며, 빌드는 해당 포인터가 존재하는지 확인합니다.
자세한 설명은 괜찮지만, 지나친 것은 안 됩니다. 일부 독자만 원하는 깊이는 접힌 블록으로 들어갑니다. "모든 세부 사항"은 사용자가 요청할 때만, 그리고 그들이 지정한 부분에 대해서만 제공됩니다.

모든 Python은 uv (uv run, uv run --with <pkg>)를 통해 실행됩니다. pip나 전역 설치는 절대 사용하지 않습니다.

참고 파일 (요청 시 로드)

파일	로드 시점
`references/scanning.md`	1단계: 토큰 예산 내에서 저장소 읽기, 입력 계층, 볼트/리콜/NotebookLM, 기존 설명서
`references/content-design.md`	2단계 및 3단계: 섹션 구성, 깊이 예산, 격차 및 유도 과정 제시 방법, 정직한 인벤토리, 설명서 워딩에 특화된 규칙 (규칙 자체: `d3-scientific-wording`)
`references/components.md`	3단계: HTML 어휘, 소스 칩, 빌드 지시어, `explainer.toml`, `D3X` JavaScript API
`references/visualization.md`	2단계 및 3단계: 가르치는 대화형 그림 설계, 패턴 카탈로그, 함정
`references/review.md`	4단계: 두 검토자 프롬프트, 토큰 규칙, 루프
`assets/example/`	완성된 설명서가 있는 작은 저장소. `assets/example/explainer/sections/*.html`를 한 번 읽어 모든 컴포넌트의 작업 패턴을 파악하세요. 사용자 프로젝트에 절대 복사하지 마십시오.

0단계: 한 번 질문

사용자가 이미 말하지 않은 경우, 한 메시지에 다음을 질문하고 다시 묻지 마십시오:

범위. 전체 프로젝트인가요, 아니면 특정 부분(모델, 유도 과정, 파이프라인)인가요? 깊이. focus (하나의 아이디어 또는 하나의 유도: 1~~3개 섹션, 그림 1~~2개, 약 5분), overview (4~~6개 섹션, 읽는 데 약 10~~15분), standard (기본값: 7~~10개 섹션, 대화형 그림 4~~8개, 유도 1~~3개, 20~~35분), 또는 deep (최대 14개 섹션). "X에 대해 deep"은 standard에 X에 대한 심층 섹션 하나를 추가하는 것을 의미합니다. 검토. light: 자동 검사 및 자체 숫자 통과, 거의 추가 토큰 없음. single: 한 명의 검토 에이전트가 충실도와 그림을 모두 담당, 한 라운드, 약 50~~70k 토큰. standard: 두 명의 검토 에이전트가 병렬로 작업 (출처에 대한 충실도, 그림 및 상호작용), 한 라운드, 함께 약 100~~150k 토큰. 검토 비용은 대부분 고정된 최소 비용이며 프로젝트 크기에 거의 의존하지 않으므로, 권장 사항은 깊이를 따릅니다: focus light, overview single, standard 및 deep 두 에이전트 검토. full: 두 에이전트가 모든 점수가 9/10이 될 때까지 반복, 최대 3라운드, 표준 비용의 2~3배. 워딩. ste (기본값: ASD-STE100 이후 Simplified Technical English, 문장당 최대 25단어, 능동태, 단어당 하나의 의미, 영어를 제2언어로 읽는 공동 저자에게 가장 쉬움) 또는 standard (STE 제한 없는 그룹의 과학적 워딩).

"빠르게", "검토 없음", "저렴하게" 또는 "토큰 부족"은 light를 의미합니다. "철저하게"는 full을 의미합니다. "이 유도 과정만", "X만 설명", "짧게"는 focus를 의미합니다. "일반", "STE" 또는 아무 말도 하지 않으면 워딩 ste; "일반 워딩", "논문 스타일" 또는 "STE 아님"은 standard를 의미합니다. 아무 말도 하지 않으면 깊이는 standard이고, 해당 깊이에 권장되는 검토가 적용됩니다.

아무도 답할 수 없는 경우 (배치 또는 에이전트 실행): 기본값을 사용하고, 이 스킬이 묻는 모든 사항을 결정하며, 각 결정을 brief.md의 0섹션에 기록하고 계속 진행합니다. 브리프는 저자가 자신을 위해 결정된 사항을 볼 수 있는 장소입니다.

워크플로우

다른 D3 스킬과 마찬가지로 각 단계 경계에서 타임스탬프가 포함된 한 줄 상태를 출력합니다: [HH:MM:SS] PHASE: ....

1단계: 프로젝트 매핑 (적절한 순서로 저렴하게 읽기)

uv run <skill-dir>/scripts/scan.py            # 저장소 루트에서 실행; --out explainer/scan.md를 추가하여 유지

스캔은 입력 계층(A: 코드 및 논문, B: 논문만, C: 코드만, D: PDF만, E: 노트만), 오리엔테이션 문서, 논문 및 각 코드 폴더의 마지막 변경 시간 (오래된 CLAUDE.md나 폐기된 접근 방식이 여기서 드러남), 방정식 레이블이 포함된 논문 개요, 기호 이름과 줄 번호가 있는 가장 큰 코드 모듈, 삽입 가능한 결과 파일, 폴더별 저자 자신의 노트가 있는 볼트, 기존 설명서, 그리고 각 오리엔테이션 문서, 논문, 섹션 파일, 코드 모듈 및 노트에 대한 토큰 예상치를 보고합니다. INPUT TIER: X를 출력하고 사용자가 재정의할 수 있도록 합니다.

그런 다음 다음 순서로 읽고, 브리프를 작성할 수 있을 때 중단합니다. 세부 사항 및 예산은 references/scanning.md에 있습니다.

오리엔테이션 문서 (CLAUDE.md, README, 루트의 사양 또는 분석 노트).
논문: 초록, 서론, 기여 설명, 그 다음 모델 및 방법 섹션. 주요 수치에 대한 결과를 훑어봅니다.
스캔에서 찾은 기존 설명서: 개요 (scan.py --explainer <file>), 그 다음 어조를 위한 한 섹션 전체 (--section N). 이는 저자가 이미 이해하고 있는 것과 선호하는 표현 방식을 보여줍니다. 이를 기반으로 구축하고 반복하지 마십시오.
볼트: 개요, 개념, 격차, 결정 및 미해결 질문 노트, 제목으로 선택. 문헌 덤프는 아닙니다.
코드: 핵심 아이디어를 구현하는 모듈만, 심볼 맵을 통해 찾습니다. 대규모 코드 베이스(약 40개 파일 또는 8,000줄 초과)의 경우 하나의 Explore 하위 에이전트를 보내 논문-코드 맵을 생성하고 파일이 아닌 결론을 유지합니다.

선택적 보강: 저장소에서 격차나 프로젝트 기록이 부족할 때만 제공: recall 스킬 (무엇이, 언제 결정되었는지) 또는 NotebookLM (문헌이 말하는 것). d3-abstract와 동일한 프로토콜. 스캔에서 문헌 폴더, 가져온 소스가 있는 볼트 또는 NotebookLM 노트북을 찾은 경우, 동일한 질문에 d3-scientific-wording의 주제 프로필(1b단계)을 제공합니다: 이는 문헌이 각 개념에 대해 사용하는 용어와 철자를 보여주며, 표기법 표와 용어 시트의 기초가 됩니다. ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile]을 출력합니다.

2단계: 콘텐츠 브리프, HTML 전에 승인

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # ./explainer 생성: explainer.toml, brief.md, sections/, d3x/
#   저장소에 여러 논문: --paper <folder> 추가         다른 곳에 설명서: init.py <dir> --repo <repo root>

저장 위치: <repo>/explainer/, 외부 저장소의 루트 (논문 서브모듈 내부 아님: Overleaf는 이를 사용할 수 없음). 브리프와 동일한 메시지에서 위치를 확인합니다.

explainer/brief.md를 작성합니다: 두 문장으로 된 프로젝트 설명, 독자가 이후에 할 수 있어야 하는 것, 읽은 출처와 의도적으로 읽지 않은 출처, 격차, 섹션 계획, 유도 과정, 정직한 인벤토리, 의도적으로 생략된 내용, 그리고 ## Wording 제목 아래의 워딩 브리프 (장르 설명서, 독자는 공동 저자, 분야, 선택된 워딩 모드, 프로젝트 구조와 기호에 대한 용어 시트). 섹션 계획은 섹션당 한 줄이며, 각 대화형 그림에 대해 노브-통찰력 문장이 있어야 합니다: "X를 움직이면 Y가 표시됩니다". 이러한 문장이 없는 그림은 장식이며, 여기서 제거되고, 만들어진 후에 제거되지 않습니다.

브리프를 채팅에 간결한 형태로 표시하고 승인을 받습니다. 이는 하나의 필수 체크포인트입니다: 수백 토큰이 소요되며 잘못된 6,000 단어를 작성하는 것을 방지합니다. 승인 전에 섹션을 작성하지 마십시오.

3단계: 작성, 한 섹션씩

첫 번째 섹션 전에 d3-scientific-wording을 호출합니다 (스킬 도구: d3-scientific-wording:d3-scientific-wording, 목록에 없으면 <wording-dir>/SKILL.md 읽기), brief.md의 브리프를 사용합니다. ste 모드에서는 <wording-dir>/references/ste.md도 읽습니다. references/components.md 및 references/visualization.md을 로드하고 예제 섹션을 한 번 훑어봅니다. 이들은 STE로 작성되었습니다.

섹션당 하나의 파일: explainer/sections/NN-slug.html, 각각 정확히 하나의 <section id=... data-nav=... data-kicker=...> 포함. 빌드가 번호를 매기고 탐색을 생성합니다.
각 섹션 후에 빌드하여 오류가 국소적으로 유지되도록 합니다: uv run explainer/d3x/build.py --draft (TODO 마커와 아직 작성되지 않은 섹션에 대한 링크는 경고만 표시)
핵심 아이디어 섹션 내부 순서: 간단한 문장, 대화형 그림, 공식 진술, 유도, 코드 내 위치. 직관이 먼저, 대수가 나중에.
저장소가 다시 입력하는 대신 말하게 하십시오. <div class="eq" data-label="eq:prob"></div>는 논문의 .tex에서 방정식을 가져옵니다 (.aux가 있으면 번호 포함). <pre class="code" data-src="src/model.py" data-lines="88-104"></pre>는 실제 줄을 가져옵니다. 둘 다 입력하는 것보다 저렴하고 출처에서 벗어날 수 없습니다.
칩으로 출처를 가리키십시오: [[paper:eq:prob]], [[code:src/model.py:88 def solve]], [[vault:Note name]], [[result:results/table.csv]], 그리고 자신의 해석에는 [[reading]]. 빌드는 존재하지 않는 파일, 줄, 기호, 레이블 또는 노트에서 실패합니다. 볼트 칩은 explainer.toml에 볼트가 구성되지 않은 경우에만 경고합니다. 실패한 칩은 이해에 대한 발견입니다: 주장을 수정하고 칩을 삭제하지 마십시오.
대화형 그림은 다음 순서로 선호도를 보여줍니다: 저장소의 결과 파일; 저장소 자체 코드가 그리드에서 계산한 숫자 (작은 explainer/data/make_data.py, visualization.md 참조); 또는 브라우저에서 장난감 규모로 재구현된 실제 공식, toy: true로 선언되며 "illustrative toy" 배지가 표시됩니다. 기본값은 논문의 설정과 동일합니다. 숫자는 파일에서 삽입되며, 절대 기억에서 입력되지 않습니다.
모든 그림 캡션은 {fig}로 시작합니다 (빌드가 그림 번호를 매깁니다. {fig:figure-id}로 참조). 무엇을 시도하고 무엇을 주목해야 하는지 알려줍니다.

4단계: 검증

uv run explainer/d3x/build.py                  # --draft 없음: TODO 마커는 이제 실패, 깊이 예산에 대한 섹션별 단어 수 출력
uv run explainer/d3x/check.py --shots          # 헤드리스 브라우저: 모든 컨트롤 이동, 모든 핸들 드래그, 모든 유도 단계 진행

check.py는 0 error(s)로 종료되어야 합니다. 그런 다음 섹션의 워딩을 린트합니다 (standard 모드에서 --ste 제거). 모든 오류를 수정하고 모든 경고를 결정합니다:

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

이는 출처를 읽는 것으로는 잡을 수 없는 것을 잡아냅니다: 경로의 NaN, 아무것도 변경하지 않는 컨트롤, MathJax가 렌더링할 수 없는 공식, 슬라이더 극단에서 잘리는 레이블, 전화 폭에서 페이지 오버플로. 특정 머신에서 첫 번째 실행 시 브라우저를 한 번 요청할 수 있습니다: uv run --with playwright playwright install chromium (설치된 Chrome 또는 Edge로 대체됨).

explainer/review/shots/에 있는 스크린샷 두세 개를 직접 확인하십시오. 그런 다음 선택한 깊이에서 검토합니다. 프롬프트와 토큰 규칙은 references/review.md에 있습니다:

single: 하나의 읽기 전용 검토자가 references/review.md의 병합된 프롬프트로, 두 패킷, check.md 및 스크린샷을 한 라운드에서 읽습니다. 그런 다음 아래와 같이 확인하고 적용합니다.
light: 검토 에이전트 없음. 직접 숫자 검증을 한 번 수행합니다: 텍스트의 모든 숫자, KPI 타일, 그림 기본값을 논문이나 인용된 결과 파일과 대조합니다. 그런 다음 중단합니다.
standard: 두 명의 읽기 전용 검토자가 병렬로, 한 라운드. 각 빌드는 explainer/review/에 두 개의 패킷을 작성합니다: fidelity-packet.md (줄 번호가 있는 설명서 텍스트, 이유가 있는 유도 단계, 각 칩에 대해 인용된 방정식 또는 증거로서의 코드 줄) 및 figures-packet.md (모든 그림의 캡션과 스크립트). 충실도 검토자는 첫 번째 패킷에서 유도, 숫자, 격차 주장 및 워딩 (콜드 리드 및 d3-scientific-wording 규칙)을 확인합니다. 경험 검토자는 두 번째 패킷에서 모든 그림이 노브-통찰력 문장을 가르치는지 확인하고, check.md 및 스크린샷도 확인합니다. 둘 다 저장소를 탐색할 필요가 없으며, 이는 검토 비용을 낮게 유지합니다. 검토자가 실행되는 동안 섹션 파일을 편집하지 마십시오. 그런 다음 각 차단 및 주요 사항을 직접 확인하고 적용하고, 재빌드하고, check.py를 다시 실행합니다. 두 번째 확인은 차단 사항에 대해서만, 해당 검토자가 제기한 경우에만, 변경된 파일에 대해서만 발생합니다.
full: 동일한 두 검토자가 모든 범주가 9 이상이 될 때까지 반복, 최대 3라운드; 그런 다음 남은 지점을 사용자에게 전달합니다.

5단계: 전달

경로 explainer/dist/<name>.html (하나의 파일, 오프라인에서 작동, 이메일로 안전하게 전송 가능), 사용된 검토 깊이, 수정된 사항에 대한 병합된 결과 표를 제공합니다. 언급: n은 표기법 서랍을 열고, 유도는 "다음 단계"로 진행하며, 칩은 원격이 GitHub에 있을 때 빌드된 커밋의 GitHub permalink로 연결됩니다. 저장소에 볼트가 있는 경우, 작성자의 이전 설명서가 있는 곳에 HTML 복사본을 넣을 것을 제안합니다. d3-scientific-wording의 워터마크 질문(5단계)을 한 번 합니다. 승인 시 explainer/sections/*.html을 정리하고 (내장된 MathJax 및 글꼴이 있는 빌드된 파일은 절대 아님) 재빌드합니다. 변경 사항을 커밋하고 설명서의 썸네일을 포함할 것을 제안합니다.

# 예시 파이프라인 전체 보기:
explain/d3-explainer/playbooks/example.avif

결과

일반적인 standard 깊이의 설명서는 다음을 포함합니다:

하나의 자체 포함된 HTML, <repo>, <vers> 및 작성자를 포함한 제목 표시줄
표기법 서랍 (보거나 닫을 수 있는 용어 시트)
7~10개의 <section> 요소, 각각 탐색 제목과 킥커 포함
4~8개의 대화형 그림, 각각 {fig} 캡션 포함
1~3개의 유도 과정, 각각 단계별 진행
인라인 "소스 칩", 이 파일의 줄, 방정식 라벨, 볼트 노트, 결과 파일 및 [[reading]] 해석에 대한 링크
방정식 및 코드 조각에 대한 인라인 인용
정직한 인벤토리 섹션
빈 후크가 없는 check.py 실행
구축의 심층성에 대한 워딩 검사 통과 (STE / 표준)

D3 Explainer (저자용 인터랙티브 HTML)