---
name: dz-progress-dashboard
description: 복잡·다단계 작업의 진행을 HTML 대시보드로 자동 생성·갱신·표시하는 범용 스킬. 작업 시작 시 유형 선택, 단계 전환마다 자동 갱신·표시(완전 자동), 작업 목록(TaskList) 중심, 진행률은 순수 칸 비율, 마커 부분 치환으로 미학 보존, 개인 세션에 보관. dz-status-show(전사 4축 현황 스냅샷)와 영역 분리 — 본 스킬은 개별 작업의 단계 진행 추적. "대시보드 만들어줘"·"진행 대시보드"·"대시보드 갱신·반영"·"진행 가시화" + 다단계 작업(신호 3개+) 자동 감지 시 활성.
version: 0.1.0
---

# 범용 진행 대시보드 (dz-progress-dashboard)

> **의존 SSoT**: `참고자료/리포트/2026-06-01-dz-progress-dashboard-스킬설계안.md` §11 범용 재정의(설계 근거) · `규칙/프로세스/HTML-원피스-작성-표준.md` D-02(미학 — frontend-design 1차 인용) · `CLAUDE.md` 「범용 진행 대시보드 운영」 절(발동 지침)

> **용어 풀이**: 대시보드(진행을 한 화면에 그려 보여주는 현황판) · 마커(HTML에 심어두는 `<!-- 표식 -->`, 갱신 위치를 가리킴) · 부분 치환(전체를 다시 만들지 않고 표시 부분만 바꿈) · 멱등(같은 입력이면 여러 번 돌려도 결과 같음) · TaskList(이 세션의 할 일 목록 도구) · 순수 칸 비율(완료 칸 ÷ 전체 칸) · 표시본(브라우저가 읽는 사본)

## 0. 한 줄 정의

복잡하거나 단계가 많은 작업을 **시작할 때 대시보드를 만들어 보여주고, 단계가 바뀔 때마다 자동으로 갱신해 다시 보여준다.** 특정 프로젝트 전용이 아니라 **모든 다단계 작업에 쓰는 범용 도구**다.

## 1. 트리거 / 발동

**사용자 호출** (한글 키워드):
- "대시보드 만들어줘" · "진행 대시보드" · "대시보드 갱신·반영" · "진행 가시화" · "대시보드 보여줘"

**자동 발동** (자비스 판단 — §6 신호 3개 이상):
- 다단계·다영역 작업을 감지하면 자비스가 먼저 **"대시보드로 추적하겠습니다" 1줄 고지** 후 생성

## 2. 영역 분리 (기존 현황 스킬과 — 중복 회피)

| 스킬 | 영역 | 단위 |
|---|---|---|
| `dz-status-reporter` | 종합·인벤토리 (텍스트 보고) | 전사 |
| `dz-status-show` | 4 축 현황 시각화 (스냅샷) | 전사·세션 |
| **`dz-progress-dashboard`** (본 스킬) | **단계 진행 HTML 대시보드 (자동 생성·갱신)** | **개별 작업** |

→ status 계열 = "지금 전체 어디"(스냅샷). 본 스킬 = "이 작업이 어디까지"(작업 1건의 단계 흐름·자동 갱신).

## 3. 동작 흐름 (5 단계)

```
작업 시작
 → ① 복잡도 판단 (§6 신호 3개 이상)
 → ② 복잡하면 작업 유형 선택 (§4 카탈로그) + "대시보드로 추적합니다" 고지
 → ③ 공통 코어(§5) + 유형 변주로 대시보드 생성 → 표시
 → ④ 단계 전환마다 자동 갱신 + 표시 (완전 자동)
 → ⑤ 작업 종료 시 개인 세션에 보관 (§11)
```

## 4. 작업 유형 카탈로그 (6 종 — 자비스가 고름, 무한 변형 아님)

| 유형 | 예시 | 유형 특화 영역 (공통 코어에 더함) |
|---|---|---|
| 분석형 | 시장조사·벤치마킹 | 조사 단계 + 출처 격자 + 검증 상태 |
| 산출물 파이프라인형 | md→html→원피스→pptx | 단계 흐름 띠 + 산출물별 완료 체크 |
| 설계형 | 요구사항→IA→화면설계 | 산출물 단계 + 검토 게이트(G-입력·G-출력) |
| 개발형 | TDD 구현 | RED→GREEN→REFACTOR + 빌드·테스트 상태 |
| 표준화·다영역형 | 다영역 표준화 | 영역 분할 진행바 + 산출물 매트릭스 |
| 일괄·마이그레이션형 | 다수 파일 일괄 변환 | 대상 목록 + 진행률 + 완료/실패 카운트 |

> 애매하면 사용자에게 한 번 확인. 카탈로그에 없는 작업은 가장 가까운 유형 + 공통 코어만으로. 카탈로그 확장은 별도 결정.

## 5. 공통 코어 (어떤 유형이든 같은 5 요소)

작업 목록(TaskList)에서 바로 도출:
1. **진행바** — 전체 진척 % (§7)
2. **단계 목록** — 할 일별 상태 (완료·진행·대기)
3. **현재 위치** — 지금 어느 단계
4. **다음 단계** — 바로 다음 + 선택지
5. **갱신 시점·주체**

## 6. 판단 가이드 (언제 켜나 — 신호 3개 이상)

- 단계(할 일) **3개 이상**
- 여러 **영역·파일**에 걸침
- **장시간·여러 세션** 예상
- **산출물 다수**(보고서·발표자료 등)
- 사용자가 "복잡하다" 언급

→ 3개 이상이면 **"대시보드로 추적하겠습니다" 1줄 고지** 후 생성 (자율이되 투명 — 원치 않으면 끔).

## 7. 진행률 산정 (순수 칸 비율 — 확정)

**완료 칸 ÷ 전체 칸**. 손어림·가중 없음.
- 단순 작업: 완료 task ÷ 전체 task
- 단계 매트릭스형: 완료 셀 ÷ 전체 셀 (예: 6/21 = 29%)

> 진행률 밖 성과(인프라·표준 신설 등)는 진행바에 섞지 않고 **별도 성과 배지**로 표기 — 진행바는 정직한 칸 비율만.

## 8. 마커 기반 부분 치환 (구현 핵심 — 전체 재생성 ✗)

미학·정적 영역을 보존하려면 **동적 영역만** 마커 사이를 교체한다:
1. 동적 영역에 앵커 마커 1회: `<!-- DZ:키 -->값<!-- /DZ:키 -->`
2. 갱신 = 마커 사이만 데이터로 교체 (정적·CSS·여백 불변)
3. **멱등** — 같은 데이터면 결과 동일(diff 없음)

동적 영역 예(표준화·다영역형 1호 기준): 판본·날짜·진행률(바+%)·상세·매트릭스 셀·작업추적·카운트·현재위치·다음단계·footer.
정적(불가침): 의제·골격·`<style>`·범례.

**마커 한계 + 1호 적용 방식** (2026-06-01 실측): `<title>` 안·inline `style`(진행바 width)·class 속성엔 HTML 주석을 넣을 수 없다. 그래서 12곳에 마커를 일일이 넣는 대신, **대시보드 상단에 「DZ:DASHBOARD 갱신 맵」 주석 1개**로 동적/정적 영역 셀렉터(요소 주소)를 명시하고, 자비스가 그 맵을 보고 **셀렉터로 정밀 치환**한다. 텍스트·블록은 직접 치환, inline style·`<title>`은 셀렉터 기반. 마커(`<!-- DZ:키 -->`)는 텍스트 노드·블록에 선택 적용.

## 9. 표시본 동기화 + 캐시 우회 (수동 3단계의 자동화)

원본만 고치면 화면이 안 바뀐다. 갱신 시 항상 셋 함께:
1. 원본 HTML 갱신
2. 표시 서버 위치로 복사 (현재 `/tmp/`, 작업별 분리)
3. 캐시 우회 — 탭 주소 `?v=N+1`

## 10. 함정 6 종 (실측 2026-06-01)

| 함정 | 회피 |
|---|---|
| 한글 경로·괄호 | 경로 항상 따옴표 |
| 표시본 분리 | 원본 + 표시본 2곳 항상 함께 |
| 브라우저 캐시 | 갱신마다 `?v=` +1 |
| 캡처 차원 한계(2000px) | 배율 0.6 축소 + 상·하단 2장 |
| 날짜 임의 생성 | 호출 시 주입 (재현성) |
| 셀 오매핑 | 산출물 폴더 ↔ 셀 1:1 매핑 고정 |

## 11. 보관 (개인 세션 연계 — 확정)

작업 종료 시 대시보드를 `_개인/sessions/{작업}/` 에 보관. 작업별 1 파일. 세션 체크포인트(`_current.md`)와 나란히 두어 진행 추적의 **시각 층** 역할.

## 12. 상시 인지 (3 중 — 본 스킬의 위치)

| 층 | 역할 | 위치 |
|---|---|---|
| CLAUDE.md 운영 절 | "무엇을·왜" 지침 | douzone-forge/CLAUDE.md |
| UserPromptSubmit 훅 1줄 | "잊지 마" 매 입력 환기 | `.claude/강제규칙-주입.md` 계열 |
| **본 스킬** | "어떻게" 실행 | 본 SKILL.md |

→ CLAUDE.md만으로는 길어서 희석된다(검증된 패턴 — 강제 작업 수행 원칙도 훅으로 매 입력 보강). 3 중이 서로 보완.

## 13. 관련 자산

- 설계안: `참고자료/리포트/2026-06-01-dz-progress-dashboard-스킬설계안.md`
- 미학: `규칙/프로세스/HTML-원피스-작성-표준.md` D-02 (frontend-design 1차 인용)
- 1호 대시보드: `프로젝트/PRJ-2026-014_douzone-forge-구축/04_시각화/2026-05-28-기획설계-표준화-대시보드.html`
- 영역 분리: `dz-status-show`(전사 스냅샷) · `dz-status-reporter`(종합 인벤토리)

End of dz-progress-dashboard