explain-plan-html

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는 선택 사항 — 팀 온보딩용 해설이면 유용하고, 승인 판단용이면 생략한다.

절차

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로 업로드한다.