# Version Bootstrap

> 版本規劃波 orchestrator。封裝「提案→spec→教學比對→UC→紅燈測試→建票」6 步 pipeline，標準化每版的規劃波啟動流程。Use for: (1) 新版本開始時的規劃波啟動, (2) 從提案到可執行 ticket 的標準化轉換, (3) 確保教學比對不被跳過。Use when: todolist.yaml 中有新版本的 proposals 待展開、準備進入新版本的 W1 規劃波時。

- Skill: `tarrragon/version-bootstrap` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add tarrragon/version-bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tarrragon/version-bootstrap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tarrragon (https://skillmd.com/u/tarrragon)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tarrragon/version-bootstrap

---


# /version-bootstrap — 版本規劃波 Orchestrator

把版本提案展開成可執行的 ticket，中間不漏教學比對。

---

## 定位

| 工具 | 問的問題 | 關係 |
|------|---------|------|
| /version-bootstrap | 「這個版本要做什麼？怎麼拆成可執行單位？」 | 規劃波 orchestrator |
| /doc | 「文件建好了沒？格式對嗎？」 | 文件系統工具（被呼叫） |
| /spec validate | 「規格夠清楚嗎？和教學一致嗎？」 | 品質閘門（被呼叫） |
| /tdd | 「測試怎麼設計？」 | TDD 流程（Phase 2 被呼叫） |
| /ticket | 「工作怎麼追蹤？」 | 票務系統（被呼叫） |

---

## 使用方式

```
/version-bootstrap --version <version>
```

PM 執行後，依 6 步流程逐步推進。每步有 checkpoint（PM 確認後才進下一步），不是全自動 pipeline。

---

## 6 步流程

### Step 1：列出提案清單（全自動）

**動作**：讀取 `docs/todolist.yaml` 中指定版本的 `proposals` 欄位，列出提案清單和摘要。

```bash
doc list proposals  # 確認提案狀態
```

**輸出**：提案 ID + 標題 + 狀態表格。

**跨提案依賴檢查（強制）**：接著執行依賴檢查腳本，偵測「本版提案依賴的提案排在更晚版本」的排序矛盾。

```bash
uv run .claude/skills/version-bootstrap/scripts/check_proposal_dependencies.py --version <version>
```

腳本讀 `docs/proposals-tracking.yaml` 各提案的 `depends_on` 欄位（選填，list of str，元素為本提案依賴的前置提案 id）比對 `target_version` 排序；若專案已採用 `doc` skill，該欄位格式定義的權威來源見 doc skill 的 `tracking_schema.py`（`PROPOSALS_TRACKING_SCHEMA["proposal_entry_optional"]`），非本 yaml 檔案本身的頭部註解。若未採用 doc skill，本腳本仍可正常運作（腳本本身不 import 該檔，以執行期讀取的 list 格式驗證取代靜態 import），只是欄位格式需自行依上方括號說明推斷，無法查閱該權威定義檔案。輸出 `[WARNING]` 時，PM 必須在本 Checkpoint 前二擇一處理：(1) 把依賴提案移入本版或更早版本一起排入，(2) 把本提案移至依賴提案完成之後的版本。**動機案例**：曾有版本以雙提案啟動，其中一提案依賴另一個排在更晚版本的提案，卻仍排入本版，矛盾拖到規劃波中段才由用戶手動發現，最終將該提案移至依賴對象所在的版本節點。若此檢查在 Step 1 就位，矛盾可在提案確認階段被攔截。

**Checkpoint**：PM 確認版本範圍——哪些提案納入本版、哪些延後；依賴檢查腳本無 `[WARNING]` 輸出，或警告已處理（移版/補前置）。

---

### Step 2：建 Spec 骨架（半自動）

**動作**：用 `/doc batch-init` 批量建立 spec 骨架。

```bash
doc batch-init --proposals PROP-XXX,PROP-YYY --domain <domain>
```

**輸出**：每個提案對應 1 份 spec 骨架檔案。

**PM 工作**：填寫每份 spec 的 FR 列表、介面定義、約束條件。這是規劃波最耗時的人工步驟。

**UI 類提案元件庫前置檢查（強制，元件庫雙向約束方法論落地）**：Why——UI 類提案若跳過 design token 層與元件庫規劃直接進入實作，設計端與工程端會各自決定元件形狀，產生重複造輪與樣式漂移，已上線元件難以回溯套用 token 體系。Consequence——未在本步驟攔截，UI 實作票會在 Step 6 匯總建票時直接開出，等到 Phase 3b 實作階段才發現缺 token 層或元件庫章節，需回頭補規劃甚至推翻已完成的實作。Action——填寫 spec FR 時逐一判別提案是否涉及 UI/頁面/元件（FR 描述含「畫面」「頁面」「元件」「介面」「UI」等關鍵字），判為 UI 類提案者須先確認下列兩項存在，缺則先補齊才可繼續本提案的 UI 實作票規劃：

| 檢查項 | 對應載體 | 缺失時動作 |
|--------|---------|-----------|
| design token 層 | 專案 design-system 樣式檔（顏色/間距/字體/圓角/陰影參數集中管理） | 先建立 design token 層 |
| L3 元件庫章節 | spec 文件的元件庫章節（元件清單 + 原生元件禁用對照表 + 豁免清單；本步驟得先只到此，逐元件元件契約欄位表與容器條目於 Step 4.5 第 3 塊後補齊） | 先建立或補齊 L3 元件庫章節（用 doc skill `component-library-spec-template`） |
| design-system spec 文件 | 用 doc skill `design-system-spec-template` 產出的 design system 專屬 spec（如 `docs/spec/design-system-spec.md`），非混入一般功能 spec | 用 design-system-spec-template 補產 |

判準與分層依據（L1/L2/L3 分層、狀態綁定判準、流程整合點）見 `.claude/methodologies/component-library-bidirectional-constraint-methodology.md`。非 UI 類提案略過本檢查。

> **Why 加 design-system spec 檢查**：doc skill 已提供 `design-system-spec-template`，但 `batch-init` 只產一般功能 spec，UI 版本易漏產 design system 專屬 spec。**Consequence**：漏產則 Step 4.5 地基波的 design-system 實作無契約可依（實證：PM 用 batch-init 產一般功能 spec 卻未產 design-system spec，經指正後才補）。**Action**：UI 版本填 spec 時一併用 design-system-spec-template 產出 design system spec，作為 Step 4.5 design-system 實作的契約。

**Checkpoint**：所有 spec FR 填寫完成；UI 類提案已完成元件庫前置檢查（design token 層、L3 元件庫章節、design-system spec 三者存在或已補齊），非 UI 類提案略過本項。

---

### Step 2.5：Domain 規劃（半自動）

> **Why**：spec 定義 FR（系統做什麼）、UC 定義使用者場景（誰怎麼用），兩者皆為垂直視角，不界定 domain 的水平聚合邊界——aggregate / kernel / read-model 分類、依賴方向、層測試策略。**Consequence**：跳過本步驟，domain 邊界會在實作階段臨場拍板（退化為「哪個檔案太大就拆」），依賴方向底線無文件可依，易出現 read-model 互相耦合、持久化細節混入 domain；測試設計（Step 5）也無 per-bundle 依據。需事後補 domain map（實證：某個移動應用實作案例中於實作前補建）。**Action**：spec FR 填完後、測試設計前，為每個 domain 產出或更新 domain map。

**動作**：用 doc skill 的 domain-map-template 為每個 domain 產出 domain map（多 domain 專案放 domain 子目錄，單 domain 專案放 `docs/` 根層）：

```bash
# 多 domain 專案：放對應 domain 子目錄
cp .claude/skills/doc/templates/domain-map-template.md docs/spec/{domain}/domain-map.md
# 單 domain 專案：放 docs/ 根層
cp .claude/skills/doc/templates/domain-map-template.md docs/domain-map.md
```

**PM 工作**：依模板從 spec FR 反推 bundle 邊界（切分判準見 `.claude/methodologies/domain-bundle-mapping-methodology.md`）——界定 aggregate / kernel / read-model 分類、依賴方向 DAG（**用實際 import 鏈驗證，不憑心智模型宣告**——如 `grep -rn "import.*<lower_layer>" lib/<domain_dir>/` 或 codegraph callers，確認 import 集合不含被禁層）、每 bundle 的目標路徑與測試層、FR→bundle 全覆蓋表。

**產出或更新語意**：saas 起手的版本，saas Stage 1/2 的 DDD 切分已餵入 domain map 的產出端，本步驟將其精修為層/依賴/測試 map；非 saas 起手（提案 / handoff 起手）則從模板新建。此語意消除「domain 規劃綁死 saas 起手」——標準化為所有規劃波的通用步驟。

**被誰消費**：Step 5 測試設計依 domain map 逐 bundle 決定測試層（domain unit / data repository / presentation widget）；Step 6 建票依 domain / data / presentation 分層切分。

**Checkpoint**：每個 domain 有 domain map；依賴方向底線經 import 鏈驗證；spec 全部 FR 在 FR→bundle 覆蓋表有歸屬（含標為非 domain 的 presentation / data FR）。

---

### Step 2.6：資料契約產出（半自動）

> **Why**：spec FR 定義欄位存在，不定義欄位的值域、狀態責任分層、不變式、交易邊界、錯誤語意與恢復模型；domain map §3 Bundle 界定表的 data/infrastructure 列只標「持久化細節屬 data 層」，未展開細節。**Consequence**：跳過本步驟，資料層設計意圖（為何選這個約束、哪些不變式由 DB 保證）無專屬載體，散落於 DDL 註解與 repository 程式碼各處；Step 5 測試設計對資料層契約條目無盤點依據，覆蓋缺口不可審計（見 `.claude/methodologies/data-layer-contract-methodology.md` 第 6 節）。**Action**：spec FR 與 domain map 完成後、紅燈測試設計前，依兩旗標判準決定是否產出資料契約文件。

**動作**：先依 `.claude/methodologies/data-layer-contract-methodology.md` 第 2 節兩正交旗標（契約文件 / migration 治理）判定（本步驟不複寫判準內容，僅引用）。**兩旗標皆否時，僅維持 schema 約束 + DDL 註解即為合法終態，本步驟到此結束**（合法跳過文件產出，非偷懶）。任一旗標為要時，cp 模板產出：

```bash
# 沿用 SPEC-NNN 編號體系，subdomain 固定為 data-contract
cp .claude/skills/doc/templates/data-contract-template.md docs/spec/{domain}/{name}-data-contract.md
```

**消費來源**：spec FR 列表（欄位語意/值域）+ domain map data 層（§3 Bundle 界定表 Infrastructure/data 列的「資料契約文件引用連結」欄）。

**PM 工作**：依模板填寫 A 區（邏輯契約，DB-agnostic）與 B 區（實作綁定，DB-specific），完成後執行 `doc query <SPEC-ID>` 做 doc CLI 驗證——確認 frontmatter 有效、文件可被查詢發現。

**被誰消費（feed Step 5）**：每條契約條目（不變式/欄位語意/邊界行為）登錄至 `docs/traceability.yaml` 第三軸 `data_contract_tests`；Step 5 派發 sage 時一併帶入此軸，供測試設計逐條盤點覆蓋缺口，避免資料層規則只靠「剛好被某測試涵蓋」被動覆蓋。

**Checkpoint**：兩旗標已判定並記錄理由（含合法跳過情形）；旗標=要時，資料契約文件已產出且 `doc query` 查詢成功；`traceability.yaml` 第三軸 `data_contract_tests` 已初始化，契約條目與測試對應無 TODO 佔位。

---

### Step 3：教學比對（半自動）

**動作**：對每份完成的 spec 執行 `/spec validate`（Full 模式，含維度 4 教學一致性）。

**前置**：確認 CLAUDE.md「教學模組對應表」中有對應模組。

**PM 工作**：
- 偏移（高/中）：對齊教學設計或先在 blog 補完
- 教學缺口：在 blog 對應模組補完後再回來

**Checkpoint**：維度 4 無高嚴重度偏移。教學缺口已處理或標記 sync-pending。

---

### Step 4：建 UC + traceability（半自動）

**動作**：Step 2 的 `batch-init` 已同時建立 UC 骨架和 traceability 映射佔位。

**PM 工作**：填寫每份 UC 的 GWT 場景、更新 traceability 映射（spec FR → UC scenario）。

**Checkpoint**：所有 UC 場景填寫完成，traceability 映射無 TODO 佔位。

---

### Step 4.5：地基波（半自動，僅含 UI 提案的版本）

> **Why**：測試設計（Step 5）需驗 zh/en overflow 與元件互動反應，這些依賴 i18n 系統與元件實體先存在；若 Step 4 後直接進 Step 5，UI 版本會在 i18n / design-system / 元件庫尚未 build 時進測試設計，無可驗對象。**Consequence**：跳過本步驟，測試票會假設不存在的 i18n key 與元件，Phase 3b 才暴露缺地基，需回頭補甚至推翻測試設計（實證：地基波經指正後手動插入）。**Action**：對含 UI 提案的版本，於測試設計前編排地基波實作波。

**動作**：依 component-library 方法論〈地基波 build 順序〉為權威，編排四塊地基實作：

| 順序 | 地基塊 | 產出 |
|------|--------|------|
| 1 | i18n 系統 | 多語系資源檔 + 產生器（元件文字取 i18n key，測試可驗 zh/en overflow） |
| 2 | design-system 實作 | design token 集中檔（消費 Step 2 的 design-system spec） |
| 3 | UX 審查 | 每個互動元件的反應/動畫/提示 + 頁面跳轉/退出/生命週期完整性審查（產出反應規格供元件庫與測試點） |
| 3.5 | 元件契約 | L3 元件庫章節補齊逐元件元件契約欄位表與容器條目（程序見 `component-contract-design` skill，判準見方法論〈元件契約判準〉）；checkpoint 為該 skill 的〈契約齊全的定義〉 |
| 4 | 元件庫實作 | 集中元件庫（套 token + i18n + UX 反應，依契約實作），barrel 匯出 |

**PM 工作**：為四塊各建實作票，另為元件契約建 DOC 票——i18n 與 design-system 可並行；UX 審查產出反應規格；元件契約依賴 UX 審查；元件庫依賴前三塊與元件契約為 `blockedBy`。順序與依賴依方法論〈地基波 build 順序〉，本 skill 不重複判準只做 orchestration。

**Checkpoint**：UI 版本的 i18n / design-system / UX 審查 / 元件庫四塊實作完成並測試綠；非 UI 版本略過本步驟（比照 Step 2 UI 判別）。

---

### Step 5：紅燈測試設計（半自動，可並行）

**動作**：對每份 spec 派發 sage-test-architect 做 Phase 2 紅燈測試設計，依紅燈層級順序分兩段產出：

- **5a 外圈驗收紅燈（先）**：對 `runtime_surface: yes` 的 UC 場景產出整合層測試描述，含 on-device / 端對端層級；外圈定義「什麼叫做完」，以 wip tag 與 gate 隔離。`runtime_surface: no` 的場景豁免本段（豁免判準見權威節，此處不複寫）。
- **5b 內圈單元紅燈（後）**：規格分解的單元測試設計，驅動實作紅綠循環。

順序規則、豁免判準與 wip tag 共存機制的權威定義見 `/tdd` skill `references/phase2/rules.md`「紅燈層級順序」節，此處不複寫。

多 spec 可並行派發（每個 spec 1 張子票）。派發時使用 `/tdd` Phase 2 流程，sage 產出紅燈測試規格（5a + 5b 兩段皆屬同一 Phase 2 產出）。

**消費 Step 2.5 domain map（兩軸測試設計）**：

1. **層軸**：依 domain map 逐 bundle 決定測試層——domain bundle 走純函式 unit test、data 走 repository test、presentation 走 widget test（分層測試策略見 `.claude/methodologies/hybrid-testing-strategy-methodology.md`）。
2. **不變式軸**：依 domain map 的「Bundle 不變式清單」節逐 bundle 列舉 domain 行為不變式測試（例：某項缺漏沿用前值、比率分母為 0 的定義值、依賴方向不成環等**各專案自己的** domain 不變式），**與 UC 場景測試並存去重**——UC 場景測試涵蓋垂直使用者行為，不變式測試涵蓋水平 domain 規則，兩軸交集去重、聯集為完整覆蓋。避免 domain 規則只靠「剛好出現於某 UC 場景」被動覆蓋。

> sage 派發 prompt 應同時帶 spec FR / UC 場景（既有）與 domain map 的 bundle 不變式清單（新增），使兩軸都被系統列舉。traceability 的 domain-bundle→test 軸（見下）記錄不變式軸覆蓋。

**PM 工作**：驗收 sage 產出——確認 FR↔AC 覆蓋矩陣（Q12）無空行。

**Checkpoint**：所有 spec 的 Phase 2 完成，紅燈測試規格已提交。

---

### Step 6：匯總建票（半自動）

**動作**：根據 Step 2-5 的產出，建立 W2/W3/W4 的 IMP ticket。

- W2/W3：GREEN 實作票（每個 spec FR 或功能模組 1 張）
- W4：驗收票（E2E + Phase 4）

**建票來源**：
- spec FR 列表 → IMP ticket
- Phase 2 紅燈規格 → 確認 ticket 粒度（每張 ticket 的紅燈數）
- UC 場景 → 整合測試 ticket
- domain map bundle 分層 → 按 domain / data / presentation 切分實作票，並依 domain map §5「對實作票切分指引」對齊各票的層歸屬與依賴方向底線

**PM 工作**：確認 Wave 分配、並行安全（共用檔案需整合票）。

**Checkpoint**：所有 ticket 建立完成，Wave 分配確認。

---

## 反應式工作（不納入 bootstrap）

以下工作在規劃波過程中可能發生，但不屬於 bootstrap pipeline：

| 類型 | 處理方式 |
|------|---------|
| 既有測試回歸 | incident-responder 分析，建 ANA/IMP ticket |
| Spec 約束邊界發現 | 建 ANA ticket，可在 Step 2 填寫時順帶處理 |
| 流程改善發現 | 建 ANA ticket，排入後續 Wave |

---

## 移版硬耦合盤點 SOP

提案因跨提案依賴矛盾（Step 1 檢查結果）或其他理由決定移版時，禁止整包提案原封不動搬到新版本——必須先盤點該提案在**本版**留下的 schema / DDL / 契約級殘留耦合，比照下方動機案例「契約先定形、業務邏輯後移版」的模式先行定形，斬斷後才能讓移出的主體與留在本版的部分變成獨立軌道。

**動機**：曾有版本規劃雙提案，其中一提案因依賴另一個排在更晚版本的提案而整體移版，但其變更清單第一項會動到契約 SOT 檔案（如 schema 定義）並牽動資料庫 DDL——若放任不管、等本版 DDL 凍結後才在移版目標版本定形該欄位，會重演過往「先上線、後補契約定義」造成的多階段漂移。提前在 DDL 凍結前定形該欄位形狀，才讓兩個提案真正解耦。

**盤點步驟**：

| 步驟 | 動作 | 產出 |
|------|------|------|
| 1. 契約掃描 | 對照移版提案的 checklist，逐項檢查是否觸及 `schema/*.schema.json`、`docs/spec/**/*.md` 的 DDL 章節、或其他跨版本共用契約檔案 | 觸及項清單 |
| 2. 凍結時序確認 | 確認本版是否有「DDL 凍結」「schema 定案」類的既定時間點（通常在 PG/儲存實作票之前） | 凍結時間點 + 是否早於移版提案原訂完成時間 |
| 3. 硬耦合分級 | 觸及項逐一判斷：純程式邏輯（無耦合，可整包移版）vs 契約形狀（硬耦合，需本版先定形） | 硬耦合項清單 |
| 4. 定形票建立 | 對每個硬耦合項建立獨立 IMP ticket（比照上方動機案例的定形票模式），範圍限定「只定形契約形狀，不含業務邏輯實作」 | 定形 ticket（本版 Wave 排入） |
| 5. 教學比對 | 依 CLAUDE.md 強制操作 2，定形前讀 blog 對應模組確認欄位設計是否已有教學定義；有則優先採用，無則先在 blog 補完 | Solution 段落記錄教學比對結論 |
| 6. Ticket 交叉標記 | 定形票 `why` 欄位引用移版提案 ID + 目標版本；移版提案的 `checklist` 對應項標記 `verified_by` 指向定形票 | 雙向可追溯 |

**判斷準則（步驟 3 分級）**：

| 觸及類型 | 是否硬耦合 | 處理方式 |
|---------|-----------|---------|
| 修改 `schema/event.schema.json` 等契約 SOT 檔案 | 是 | 建定形票，本版執行 |
| 修改 DDL（`CREATE TABLE` 欄位定義） | 是 | 建定形票，本版執行 |
| 純業務邏輯（middleware、演算法、UI） | 否 | 整包隨提案移版 |
| 僅讀取既有契約、不新增欄位 | 否 | 整包隨提案移版 |

---

## 與早期手動流程的對照

| 早期手動流程 | /version-bootstrap |
|----------------|-------------------|
| 手動 cp 模板建 spec | Step 2 `/doc batch-init` |
| 手動讀 blog 比對 | Step 3 `/spec validate --dim 4` |
| 手動 cp 模板建 UC | Step 2 `/doc batch-init`（同步建立） |
| 手動編輯 traceability | Step 2 自動佔位 + Step 4 填寫 |
| 逐一派 sage | Step 5 批量並行派發 |
| 手動建票 | Step 6 依產出匯總 |

---

版本紀錄在同目錄的 `CHANGELOG.md`。