Explain Plan (플랜 HTML 해설서)
지정된 플랜 파일(Claude Code plan mode 산출물, ~/.claude/plans/*.md, 설계 문서 등)을
읽는 사람이 승인/기각 판단을 내릴 수 있을 만큼 쉽게 이해하도록 대화형 HTML로 옮긴다.
절대 규칙: HTML을 직접 쓰지 마라
마크다운 문서 하나를 작성하고 렌더러를 돌린다:
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 |
플랜 전용 지시자 요약
```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는 선택 사항 — 팀 온보딩용 해설이면 유용하고, 승인 판단용이면 생략한다.
절차
- 플랜 파일을 읽고, 플랜이 언급하는 파일·이슈·문서를 탐색해 맥락을 보강한다.
- 마크다운 문서를 작성한다 — 스크래치패드나
/tmp에 둔다.
frontmatter repo:에 플랜이 대상으로 하는 저장소 절대 경로,
plan:에 플랜 원문 md 절대 경로를 넣는다(원문 패널 + src: 링크 활성).
- 렌더링:
python render.py doc.md --open (render.py는 이 SKILL.md와 같은 디렉터리)
- 출력은
/tmp/YYYY-MM-DD-plan-<slug>.html (날짜 접두사 → 시간순 정렬 + 저장소 밖).
- 렌더가 실패하면 오류 메시지를 읽고 문서를 고친다(대개 deps id 누락/checklist 형식).
- Claude 환경이면 artifact로 업로드한다.
1---2name: explain-plan-html3description: '작업 계획(plan) 파일을 분석해 대화형 HTML 해설서로 만드는 스킬입니다 ("플랜 분석", "플랜 해설", "계획 시각화", "이 플랜 설명해줘", "plan을 html로"). 두 모드 — brief(브리핑, 승인 판단용 요약: "간단히/한눈에")와 full(실행 추적용 전체 커버리지: "상세히/풀") — 를 요청 목적에 맞춰 선택하며, 플랜 골격(Context·핵심 결정·Phase·의존 관계·파일 배치·검증)을 전용 다이어그램(timeline/deps/files/checklist/decision)과 원문 패널(src: 점프 링크)로 옮깁니다. diff·코드 변경 해설은 explain-diff-html 를 사용하세요.'4metadata:5 source: https://skillmd.com/skills/moonklabs/explain-plan-html6---78# Explain Plan (플랜 HTML 해설서)910지정된 플랜 파일(Claude Code plan mode 산출물, `~/.claude/plans/*.md`, 설계 문서 등)을11읽는 사람이 **승인/기각 판단을 내릴 수 있을 만큼** 쉽게 이해하도록 대화형 HTML로 옮긴다.1213## 절대 규칙: HTML을 직접 쓰지 마라1415**마크다운 문서 하나**를 작성하고 렌더러를 돌린다:1617```bash18python render.py plan-doc.md --open # render.py는 이 SKILL.md와 같은 디렉터리에 있다19```2021렌더러는 explain-diff-html 파생이며 공용 지시자(flow/stack/uiwin/code/callout/22snippet/gitdiff/quiz/html)에 더해 **플랜 전용 지시자 5종**을 지원한다.23정확한 문법은 `python render.py --help`(docstring 전문)를 읽어라.2425## 두 가지 모드 — 깊이를 상황에 맞춰라2627같은 렌더러·같은 구조를 쓰되, **저술 깊이**를 요청 목적에 맞춘다.2829| | **brief (브리핑)** | **full (실행 추적)** |30|---|---|---|31| 목적 | 승인/기각 판단, 빠른 공유 | 실행·추적, 팀 온보딩 |32| 분량 | 화면 2~3장 — 5분 안에 읽힌다 | 원문 전체 커버리지 |33| 구성 | ① 한눈에 + ③ 핵심 결정 + ⑤ 의존 관계 + 위험 요약 | 7부 전체 + 체크리스트 |34| 상세 처리 | **생략하되 반드시 src: 링크로 원문 위임** | 간략화 금지 — 본문에 전부 담는다 |3536**모드 선택:**37- 요청에 "간단히·브리핑·요약·한눈에" → brief. "상세히·실행용·풀·온보딩" → full.38- 명시가 없으면: 플랜이 **승인 전**(판단이 목적)이면 brief, **승인 후/실행 중**이면 full.39 애매하면 brief로 만들고 "풀 버전이 필요하면 말해달라"고 안내한다.40- brief에서도 **핵심 결정(기각안 포함)·게이트 조건·총 공수·최상위 위험**은 생략 불가 —41 이것이 승인 판단의 최소 재료다. 세부 수치·파일 목록·절차는 src: 링크 한 줄로 대체한다.42 (원문 패널이 내장되므로 생략해도 정보는 손실되지 않는다 — 링크 없는 생략만 금지.)4344## 해설서 구조 — 7부 구성4546플랜 원문의 순서를 그대로 옮기지 말고, 아래 독자 중심 구조로 재배치한다.47(원문에 없는 부는 생략 가능. 단 ①·④·⑦은 full 필수 / brief는 ①·③·⑤ 중심.)4849| 부 | 내용 | 주력 지시자 |50|---|---|---|51| ① 한눈에 | 목표 한 줄 · 범위 in/out · 전체 로드맵 · 총 공수 | `timeline` |52| ② 배경 | 왜 이 작업인가 — 원문 Context를 초보자도 읽히게 풀어쓰기 | 본문, `flow` |53| ③ 핵심 결정 | 플랜이 내린 선택과 기각안, 그 근거 | `decision`, 표 |54| ④ 실행 계획 | Phase별 하위섹션: 목표 → 파일 배치 → 상세 → 게이트 조건 | `files`, `stack` |55| ⑤ 의존 관계 | 태스크/이슈 간 blocked-by, 외부 이슈와의 related | `deps` |56| ⑥ 위험·열린 질문 | 실패 시나리오, 미확정 사항, 롤백 방법 | `callout warn/bad` |57| ⑦ 검증 | 완료 판정 기준 — 실행하며 체크할 수 있는 목록 | `checklist` |5859## 플랜 전용 지시자 요약6061````markdown62```timeline 실행 로드맵63P0 | 백엔드 착지 | 0.5일 | done64P1 | Skill+Command 도그푸딩 | 1일 | now65P3 | Hook 강제 | 게이트: H-도장 확증 후 | gate66```67```deps 이슈 의존 관계68i1: main 핫픽스 반영 [hi]69i2: GROWTH/AD 차단 <- i170i5: 레거시 축소 <- i2 i371```72```files Phase 1 파일 배치73+ .claude/skills/loop/SKILL.md | 루프 규범 (~150줄)74~ packages/cli/src/connect.ts | 플러그인 설치 추가75- old/legacy.js | 제거76? docs/spec.md | 결정 대기77```78```checklist 검증 체크리스트79- [ ] advisor 테스트 10파일 통과80- [x] zero-collision 확인 (완료)81```82```decision Command인가 Skill인가?83pick: 셋 다 쓰되 역할 분담84why: 개발자는 MCP 툴을 직접 부르지 않는다85drop: Hook 선행 도입 — 확증 전 강제 금지86hold: Codex 변형 — Phase 3에서 재검토87```88````8990## 원문 패널 — 반드시 배선하라9192frontmatter `plan:`에 **플랜 원문 md의 절대 경로**를 넣으면 원문 전체가 md viewer로93렌더되어 드로어(우측 슬라이드 패널)에 내장된다. 독자는 우하단 "플랜 원문" 버튼으로94언제든 원문을 열 수 있다.9596핵심은 **src: 링크**다 — 해설 본문에서 `[원문의 Phase 1 ↗](src:Phase-1)` 처럼 쓰면97클릭 시 드로어가 열리며 원문의 해당 제목으로 스크롤 + 하이라이트된다. 독자가98"이 얘기가 플랜 어느 지점이지?" 하는 순간 바로 원문 맥락으로 점프하게 하는 장치다.99100- 검색어는 원문 제목의 일부면 되고, **공백 대신 하이픈**을 쓴다(매칭은 공백·하이픈·장식 무시).101- 매칭 실패 시 렌더가 실패하므로 원문 제목을 그대로 복사해 쓰는 것이 안전하다.102- **각 부(②~⑦)마다 최소 1개의 src: 링크**를 달아 해설 ↔ 원문 대응을 촘촘히 유지하라.103104## 작성 지침105106- **[full 모드] 간략화 금지 — 요약이 아니라 재구성이다.** 원문에 있는 모든 결정·수치·107 파일 경로·조건·예외가 해설서 **어딘가에는** 담겨야 한다. DSL 한 줄에 안 들어가는 상세는108 다이어그램 아래 본문 문단·표·callout으로 풀어 쓴다(다이어그램은 지도, 본문이 영토다).109 full에서 src: 링크는 점프 보조 장치이지 **내용을 생략하는 면죄부가 아니다**.110 탈고 전에 원문을 한 번 더 훑으며 해설서에 없는 정보가 있는지 대조하라.111- **[brief 모드] 생략에는 반드시 src: 링크.** 세부를 덜어내는 것은 허용되지만, 덜어낸112 자리마다 `[상세는 원문 ↗](src:...)` 한 줄을 남겨 원문 패널로 위임한다. 링크 없는113 생략(독자가 존재 자체를 모르게 되는 것)만 금지다.114- **언어:** 본문·다이어그램은 사용자 대화 언어(기본 한국어). 코드 식별자·기술 용어는 원형 유지.115- **플랜을 넘어 탐색하라.** 플랜이 언급하는 파일·이슈·문서를 repo에서 실제로 확인하고,116 플랜만 읽어서는 알 수 없는 맥락(그 파일이 지금 어떤 상태인지)을 배경에 보태라.117 `snippet`/`gitdiff`로 현재 코드를 인용하면 "왜 이 변경이 필요한지"가 즉시 보인다.118- **상태를 지어내지 마라.** Phase 진행 상태(done/now)는 플랜·대화·git에서 확인된 것만119 표시하고, 모르면 상태 토큰을 생략한다(중립 렌더). 미확정 파일은 `?` 접두어.120- **checklist는 실행 가능한 문장으로.** "테스트 통과"가 아니라 "`cd backend && npm test`121 advisor 10파일 통과"처럼, 체크하는 사람이 그대로 실행할 수 있게 쓴다.122 체크 상태는 브라우저 localStorage에 저장되어 다시 열어도 유지된다 — 이 해설서는123 읽고 끝나는 문서가 아니라 **실행 추적 도구**를 겸한다.124- **decision 카드는 "기각안"이 핵심이다.** 무엇을 안 하기로 했고 왜인지가 승인 판단의125 재료다. 원문에서 기각·보류가 명시되지 않았어도 문맥상 배제된 대안이 있으면 담아라.126- **총 공수·게이트를 ①에 요약하라.** timeline의 chip 자리에 공수(0.5일)나 게이트127 조건(H-도장 확증 후)을 넣고, 게이트가 있는 Phase는 `gate` 상태로 표시한다.128- **의존 관계에 외부 이슈를 포함하라.** 플랜 내부 태스크뿐 아니라 SK-45처럼 참조되는129 외부 이슈도 deps 노드로 넣으면 전체 그림이 잡힌다.130- quiz는 선택 사항 — 팀 온보딩용 해설이면 유용하고, 승인 판단용이면 생략한다.131132## 절차1331341. 플랜 파일을 읽고, 플랜이 언급하는 파일·이슈·문서를 탐색해 맥락을 보강한다.1352. 마크다운 문서를 작성한다 — 스크래치패드나 `/tmp`에 둔다.136 frontmatter `repo:`에 플랜이 대상으로 하는 저장소 절대 경로,137 `plan:`에 플랜 원문 md 절대 경로를 넣는다(원문 패널 + src: 링크 활성).1383. 렌더링: `python render.py doc.md --open` (render.py는 이 SKILL.md와 같은 디렉터리)139 - 출력은 `/tmp/YYYY-MM-DD-plan-<slug>.html` (날짜 접두사 → 시간순 정렬 + 저장소 밖).1404. 렌더가 실패하면 오류 메시지를 읽고 문서를 고친다(대개 deps id 누락/checklist 형식).1415. Claude 환경이면 artifact로 업로드한다.