# Explain Plan HTML

> Analyzes a plan file and converts it into an interactive HTML explainer with brief and full modes, featuring dedicated diagrams and source links.

- Skill: `moonklabs/explain-plan-html` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add moonklabs/explain-plan-html`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moonklabs/explain-plan-html/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend, Productivity
- Tags: Claude Code, Diagrams, Documentation, Explainer, Html, Plan, Visualization
- Author: moonklabs (https://skillmd.com/u/moonklabs)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/moonklabs/explain-plan-html

---


# Explain Plan (플랜 HTML 해설서)

지정된 플랜 파일(Claude Code plan mode 산출물, `~/.claude/plans/*.md`, 설계 문서 등)을
읽는 사람이 **승인/기각 판단을 내릴 수 있을 만큼** 쉽게 이해하도록 대화형 HTML로 옮긴다.

## 절대 규칙: HTML을 직접 쓰지 마라

**마크다운 문서 하나**를 작성하고 렌더러를 돌린다:

```bash
python render.py plan-doc.md --open   # render.py는 이 SKILL.md와 같은 디렉터리에 있다
```

렌더러는 explain-diff-html 파생이며 공용 지시자(flow/stack/uiwin/code/callout/
snippet/gitdiff/quiz/html)에 더해 **플랜 전용 지시자 5종**을 지원한다.
정확한 문법은 `python render.py --help`(docstring 전문)를 읽어라.

## 두 가지 모드 — 깊이를 상황에 맞춰라

같은 렌더러·같은 구조를 쓰되, **저술 깊이**를 요청 목적에 맞춘다.

| | **brief (브리핑)** | **full (실행 추적)** |
|---|---|---|
| 목적 | 승인/기각 판단, 빠른 공유 | 실행·추적, 팀 온보딩 |
| 분량 | 화면 2~3장 — 5분 안에 읽힌다 | 원문 전체 커버리지 |
| 구성 | ① 한눈에 + ③ 핵심 결정 + ⑤ 의존 관계 + 위험 요약 | 7부 전체 + 체크리스트 |
| 상세 처리 | **생략하되 반드시 src: 링크로 원문 위임** | 간략화 금지 — 본문에 전부 담는다 |

**모드 선택:**
- 요청에 "간단히·브리핑·요약·한눈에" → brief. "상세히·실행용·풀·온보딩" → full.
- 명시가 없으면: 플랜이 **승인 전**(판단이 목적)이면 brief, **승인 후/실행 중**이면 full.
  애매하면 brief로 만들고 "풀 버전이 필요하면 말해달라"고 안내한다.
- brief에서도 **핵심 결정(기각안 포함)·게이트 조건·총 공수·최상위 위험**은 생략 불가 —
  이것이 승인 판단의 최소 재료다. 세부 수치·파일 목록·절차는 src: 링크 한 줄로 대체한다.
  (원문 패널이 내장되므로 생략해도 정보는 손실되지 않는다 — 링크 없는 생략만 금지.)

## 해설서 구조 — 7부 구성

플랜 원문의 순서를 그대로 옮기지 말고, 아래 독자 중심 구조로 재배치한다.
(원문에 없는 부는 생략 가능. 단 ①·④·⑦은 full 필수 / brief는 ①·③·⑤ 중심.)

| 부 | 내용 | 주력 지시자 |
|---|---|---|
| ① 한눈에 | 목표 한 줄 · 범위 in/out · 전체 로드맵 · 총 공수 | `timeline` |
| ② 배경 | 왜 이 작업인가 — 원문 Context를 초보자도 읽히게 풀어쓰기 | 본문, `flow` |
| ③ 핵심 결정 | 플랜이 내린 선택과 기각안, 그 근거 | `decision`, 표 |
| ④ 실행 계획 | Phase별 하위섹션: 목표 → 파일 배치 → 상세 → 게이트 조건 | `files`, `stack` |
| ⑤ 의존 관계 | 태스크/이슈 간 blocked-by, 외부 이슈와의 related | `deps` |
| ⑥ 위험·열린 질문 | 실패 시나리오, 미확정 사항, 롤백 방법 | `callout warn/bad` |
| ⑦ 검증 | 완료 판정 기준 — 실행하며 체크할 수 있는 목록 | `checklist` |

## 플랜 전용 지시자 요약

````markdown
```timeline 실행 로드맵
P0 | 백엔드 착지 | 0.5일 | done
P1 | Skill+Command 도그푸딩 | 1일 | now
P3 | Hook 강제 | 게이트: H-도장 확증 후 | gate
```
```deps 이슈 의존 관계
i1: main 핫픽스 반영 [hi]
i2: GROWTH/AD 차단 <- i1
i5: 레거시 축소 <- i2 i3
```
```files Phase 1 파일 배치
+ .claude/skills/loop/SKILL.md | 루프 규범 (~150줄)
~ packages/cli/src/connect.ts | 플러그인 설치 추가
- old/legacy.js | 제거
? docs/spec.md | 결정 대기
```
```checklist 검증 체크리스트
- [ ] advisor 테스트 10파일 통과
- [x] zero-collision 확인 (완료)
```
```decision Command인가 Skill인가?
pick: 셋 다 쓰되 역할 분담
why: 개발자는 MCP 툴을 직접 부르지 않는다
drop: Hook 선행 도입 — 확증 전 강제 금지
hold: Codex 변형 — Phase 3에서 재검토
```
````

## 원문 패널 — 반드시 배선하라

frontmatter `plan:`에 **플랜 원문 md의 절대 경로**를 넣으면 원문 전체가 md viewer로
렌더되어 드로어(우측 슬라이드 패널)에 내장된다. 독자는 우하단 "플랜 원문" 버튼으로
언제든 원문을 열 수 있다.

핵심은 **src: 링크**다 — 해설 본문에서 `[원문의 Phase 1 ↗](src:Phase-1)` 처럼 쓰면
클릭 시 드로어가 열리며 원문의 해당 제목으로 스크롤 + 하이라이트된다. 독자가
"이 얘기가 플랜 어느 지점이지?" 하는 순간 바로 원문 맥락으로 점프하게 하는 장치다.

- 검색어는 원문 제목의 일부면 되고, **공백 대신 하이픈**을 쓴다(매칭은 공백·하이픈·장식 무시).
- 매칭 실패 시 렌더가 실패하므로 원문 제목을 그대로 복사해 쓰는 것이 안전하다.
- **각 부(②~⑦)마다 최소 1개의 src: 링크**를 달아 해설 ↔ 원문 대응을 촘촘히 유지하라.

## 작성 지침

- **[full 모드] 간략화 금지 — 요약이 아니라 재구성이다.** 원문에 있는 모든 결정·수치·
  파일 경로·조건·예외가 해설서 **어딘가에는** 담겨야 한다. DSL 한 줄에 안 들어가는 상세는
  다이어그램 아래 본문 문단·표·callout으로 풀어 쓴다(다이어그램은 지도, 본문이 영토다).
  full에서 src: 링크는 점프 보조 장치이지 **내용을 생략하는 면죄부가 아니다**.
  탈고 전에 원문을 한 번 더 훑으며 해설서에 없는 정보가 있는지 대조하라.
- **[brief 모드] 생략에는 반드시 src: 링크.** 세부를 덜어내는 것은 허용되지만, 덜어낸
  자리마다 `[상세는 원문 ↗](src:...)` 한 줄을 남겨 원문 패널로 위임한다. 링크 없는
  생략(독자가 존재 자체를 모르게 되는 것)만 금지다.
- **언어:** 본문·다이어그램은 사용자 대화 언어(기본 한국어). 코드 식별자·기술 용어는 원형 유지.
- **플랜을 넘어 탐색하라.** 플랜이 언급하는 파일·이슈·문서를 repo에서 실제로 확인하고,
  플랜만 읽어서는 알 수 없는 맥락(그 파일이 지금 어떤 상태인지)을 배경에 보태라.
  `snippet`/`gitdiff`로 현재 코드를 인용하면 "왜 이 변경이 필요한지"가 즉시 보인다.
- **상태를 지어내지 마라.** Phase 진행 상태(done/now)는 플랜·대화·git에서 확인된 것만
  표시하고, 모르면 상태 토큰을 생략한다(중립 렌더). 미확정 파일은 `?` 접두어.
- **checklist는 실행 가능한 문장으로.** "테스트 통과"가 아니라 "`cd backend && npm test`
  advisor 10파일 통과"처럼, 체크하는 사람이 그대로 실행할 수 있게 쓴다.
  체크 상태는 브라우저 localStorage에 저장되어 다시 열어도 유지된다 — 이 해설서는
  읽고 끝나는 문서가 아니라 **실행 추적 도구**를 겸한다.
- **decision 카드는 "기각안"이 핵심이다.** 무엇을 안 하기로 했고 왜인지가 승인 판단의
  재료다. 원문에서 기각·보류가 명시되지 않았어도 문맥상 배제된 대안이 있으면 담아라.
- **총 공수·게이트를 ①에 요약하라.** timeline의 chip 자리에 공수(0.5일)나 게이트
  조건(H-도장 확증 후)을 넣고, 게이트가 있는 Phase는 `gate` 상태로 표시한다.
- **의존 관계에 외부 이슈를 포함하라.** 플랜 내부 태스크뿐 아니라 SK-45처럼 참조되는
  외부 이슈도 deps 노드로 넣으면 전체 그림이 잡힌다.
- quiz는 선택 사항 — 팀 온보딩용 해설이면 유용하고, 승인 판단용이면 생략한다.

## 절차

1. 플랜 파일을 읽고, 플랜이 언급하는 파일·이슈·문서를 탐색해 맥락을 보강한다.
2. 마크다운 문서를 작성한다 — 스크래치패드나 `/tmp`에 둔다.
   frontmatter `repo:`에 플랜이 대상으로 하는 저장소 절대 경로,
   `plan:`에 플랜 원문 md 절대 경로를 넣는다(원문 패널 + src: 링크 활성).
3. 렌더링: `python render.py doc.md --open` (render.py는 이 SKILL.md와 같은 디렉터리)
   - 출력은 `/tmp/YYYY-MM-DD-plan-<slug>.html` (날짜 접두사 → 시간순 정렬 + 저장소 밖).
4. 렌더가 실패하면 오류 메시지를 읽고 문서를 고친다(대개 deps id 누락/checklist 형식).
5. Claude 환경이면 artifact로 업로드한다.