# Dev Progress Map

> 開發進度全貌視覺化——讀專案的 progress.md 與路線圖文件（如 docs/sdd-roadmap.md），畫出三層式進度地圖（已完結階段橫幅／里程碑軌道＋「你在這裡」／當前里程碑步驟放大鏡），並搭配固定四段白話敘事。只要使用者問「進度到哪」「全貌」「現在什麼階段」「完成了哪些」「後面還有什麼」「路線圖現況」「幫我看專案狀態」，或在多里程碑的開發專案裡要求視覺化現況，就使用本 skill——即使對方沒說「圖」或「視覺化」這些字。

- Skill: `alanpai/dev-progress-map` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alanpai/dev-progress-map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alanpai/dev-progress-map/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: AlanPai (https://skillmd.com/u/alanpai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alanpai/dev-progress-map

---


# 開發進度全貌圖（dev-progress-map）

把一個多里程碑開發專案的「走到哪了」畫成一張三層式地圖＋一段白話故事。
設計給**非工程背景的專案主人**看：他要的是位置感（我在哪、離終點多遠），不是工項清單。

## 精神：三層鏡頭

一張圖同時回答三個尺度的問題，像地圖的三段縮放：

1. **遠景（第 0 章橫幅）**：已經整段完結的大階段，壓縮成一條綠色橫幅＋一句「產出了什麼」。
   已完結的東西不需要細節，它的作用是給成就感和上下文。
2. **中景（里程碑軌道）**：整個開發計畫的所有里程碑排成一條軌道，每站一張小卡，
   掛「你在這裡」徽章。這層回答「全程有幾站、我在第幾站」。
3. **近景（放大鏡）**：只把**當前那一站**的內部步驟展開成第二條軌道（例如九步循環、
   sprint 內任務），掛「現在」徽章。這層回答「這一站裡我還差什麼」。

只放大當前站，其他站不展開——資訊量的紀律就是這張圖好讀的原因。

## 第一步：查資料（不憑記憶）

進度天天變，**畫圖前必須先讀最新檔案**，即使你自認記得：

1. `progress.md`（或專案的進度交接主檔）——目前狀態、最近大事、下一步。
2. 路線圖文件（常見：`docs/sdd-roadmap.md`、`ROADMAP.md`）——里程碑的**正式定義**與依賴。
   用 Grep 抽里程碑表格，不要憑印象寫里程碑內容；印象與正式定義的落差就是誤導的來源。
3. 本次對話脈絡——今天剛完成、剛拍板的事可能還沒回寫進文件。

找不到路線圖文件時：從 progress.md、git log、README 盡力重建，並在敘事裡明講
「以下依 ×× 推斷，專案沒有正式路線圖」——寧可標注來源不足，不可假裝權威。

## 第二步：抽內容

- **第 0 章**：已整段完結的時期（規劃期、研究期…）→ 一句話列產出物鏈（A → B → C）。
- **里程碑軌道**：全部里程碑，上限約 12 站（更多就合併遠期的）。每站三行：
  編號（M4）＋**白話名（≤6 個字）**＋狀態。白話名是關鍵——把「P0-1 地基 schema」
  改寫成「帳本地基＋引擎」、「cutover」改寫成「新舊並行→切換」。改寫時保留原編號，
  讓它跟正式文件對得上。
- **放大鏡**：當前里程碑的內部步驟（照該專案的方法論，例如九步循環①~⑨），
  同樣格式。部分完成的步驟用「◐ 後端✅ 前端⬜」這種拆半標法。
- **驗收閘**：需要外部條件才能過的關卡（設備到位、連續 N 天零差異）標成虛線框，
  它們不是「做了就完成」的工項，視覺上要區分。

## 第三步：畫圖

狀態詞彙固定四態＋閘，圖例必附：

| 記號 | 意義 | 視覺 |
|---|---|---|
| ✅ | 完成 | 綠色邊框＋綠字 |
| ◐ | 部分完成 | 黃/琥珀字 |
| ▶ | 進行中（目前位置） | 強調色粗框＋「你在這裡」徽章 |
| ⬜ | 未開始 | 整卡淡化（opacity ~0.6） |
| 虛線框 | 驗收閘 | 虛線邊框 |

顏色紀律：**只有兩組語義色**（綠＝完成、強調色＝現在），其他一律中性。
主題適應：用宿主環境的 CSS 變數（`--surface-*`、`--border`、`--text-*`、`--radius`、
`--font-sans/mono`），不寫死背景色，深淺色主題都能看。

渲染管道（依環境擇一）：
1. 有 `show_widget`（visualize MCP）→ 先呼叫其 read_me（diagram 模組），再用
   `assets/widget-template.html` 為骨架填內容渲染。
2. 沒有 widget 工具 → 產出同樣 HTML 存檔，用 Artifact 或 SendUserFile 給使用者；
   都沒有就退化成 Markdown 表格＋文字軌道（`M1✅─M2✅─▶M4─M5⬜…`）。

模板骨架見 `assets/widget-template.html`（讀它、換掉註解標記的三段內容即可）。

## 第四步：白話敘事（固定四段，寫在圖下方的回覆文字裡）

圖管「位置」，文字管「意義」。四段結構：

1. **已經走完的路**——講每段的**價值**（「這一章的價值是：後面每次寫程式都有依據可查」），
   不是重複工項清單。
2. **現在的位置**——精確到步驟；剩下的事**按順序**編號列出，每件一句話。
3. **後面的路**——每個未來里程碑**一句白話**（「M7 出庫線：接單→揀貨→出貨，
   整個系統最複雜的一條線」）。
4. **量級感**——每站是天級/週級/月級、目前大約走到全程幾分之幾，
   並指出「最難的部分是否已付清」這類讓人安心或警醒的判斷。

寫作紀律：對非工程背景的讀者，技術名詞第一次出現先用生活類比；
圖裡放過的內容文字不重複，文字補圖給不了的「為什麼重要」。

## 常見錯誤

- ❌ 憑記憶畫圖（progress 文件才是事實）
- ❌ 每一站都展開細節（只放大當前站）
- ❌ 卡片名照抄文件術語（要白話改寫、≤6 字、保留編號）
- ❌ 五顏六色（兩組語義色＋圖例）
- ❌ 圖和文字講重複的話