SPEX-SDD 使用指南：各種情境的操作手冊

適用版本：spex-sdd 最後更新：2026 年 8 月

這份指南怎麼讀

核心設計

SPEX-SDD 為系統產生一套可實作、可驗證、可被機器把關的技術文件：規格骨幹、七份正式文件、Harness 工程關卡、AI 可執行任務、追溯性輸出與 UI mockup。

核心命題是一句話：

規範若沒有偵測器，就等於沒有寫。

圍繞這句話，方法設計了五個核心機制：

適合什麼情況：

安裝與位置

已安裝在：

~/.claude/skills/spex-sdd/
├── SKILL.md
├── references/
│   ├── document-specs.md      # 七份文件與各產物的格式規格
│   ├── harness-catalog.md     # 六項指標 × 各語言工具、門檻、斷言產生法
│   └── validation-rules.md    # 人工語意驗證規則
└── scripts/
    └── validate_spec.py       # 可執行結構驗證器（stdlib only）

~/.claude/skills/ 是全域位置，任何專案都能用。要讓團隊共用就複製到 repo 的 .claude/skills/ 或 .github/skills/。

不需要安裝 PyYAML——validator 有內建的 YAML 子集解析器作為 fallback。

觸發方式

斜線強制觸發（推薦，確定會載入）：

/spex-sdd <需求>

自然語言觸發（description 命中即載入）：

用 SPEX-SDD 幫 LedgerPro 產技術文件，slice 模式，先做對帳流程

確認有載入：問它「你現在載入了哪些 skill？SPEX-SDD 的六項工程指標是什麼？」答得出突變測試與依賴結構就是有讀到。

使用前要準備什麼

給得越完整越少來回：

不確定的可以不給，它會問或標為假設。

模式怎麼選

系統已有實作？ ─── 是 ──→ slice（強烈建議）
      │
      否
      ↓
模組數 > 8 ？ ─── 是 ──→ slice
      │
      否
      ↓
需要一次交付完整套件（投標／稽核）？ ─── 是 ──→ full
      │
      否
      ↓
   模組 ≤ 3 ？ ─── 是 ──→ full（slice 管理成本大於效益）
      │
      否
      ↓
    slice

各種情境

情境 1：既有專案第一次導入（最常見）

不要一開口就叫它產全套，分三步走。

第 1 步：只做盤點 + Harness

/spex-sdd
專案：
- 後端 /Users/leo/work/LedgerPro（Go + PostgreSQL）
- 前端 /Users/leo/work/LedgerPro-web（Vue 3 + Vite）
部署：systemd，直推 master 沒有 PR

本次只做兩件事：
1. 實作盤點（含品質基線量測）
2. 設計 Harness：_HARNESS.md + harness.yaml

七份文件先不要產。輸出到 docs/spec/

產出：

• 實作現況對照表（模組 × 實作狀態 × 實際檔案位置 × 差異）

• 實際路由清單、實際資料表清單、測試現況

• 品質基線：覆蓋率多少、最大循環複雜度、最大檔案行數、有無循環依賴

• _HARNESS.md + harness.yaml：六項指標的工具、指令、依現況訂的門檻

這一步通常最有價值。它會量出你專案真實的樣子——多數團隊的第一次基線量測會發現覆蓋率比想像低 20-30%、有幾個破千行的檔案、或某兩個模組互相引用。

時間：中型專案 20-40 分鐘。

第 2 步：挑一個 slice 展開

接著做 SLICE-01：對帳流程
展開它的 FR / US / SC / TASK，其餘模組維持 outline 狀態

產出：backbone（本 slice 完整、其餘 outline）、七份文件的對應章節、agent_tasks.md、agent_execution_plan.json、validator 輸出。

怎麼挑第一個 slice：選「風險最高且目前沒有測試覆蓋」的，不要選最簡單的。第一個 slice 的目的是驗證這套流程走不走得通，簡單的 slice 驗證不出問題。

第 3 步：實作 → 跑 gate → 回寫

依 agent_tasks.md 執行 TASK-RECON-001，先寫測試再實作
完成後跑它的 gate_ids，結果回寫到 _HARNESS.md 與 misfit-log.md

跑完一輪後檢視：gate 有沒有紅？紅的是程式碼問題還是門檻訂太高？有沒有人工發現但 gate 沒抓到的問題（那是 undetected，優先補 detector）。

情境 2：全新專案從零開始

/spex-sdd
新系統：思沛授權管理系統 v2（LMS2）
業務背景：管理產品授權發放、線上啟用、裝置綁定與稽核，供內部與經銷商使用
技術棧：.NET 9 + PostgreSQL + Redis + Vue 3
模組：授權發放、啟用驗證、裝置綁定、稽核查詢、管理後台
多租戶（經銷商即租戶），有管理後台
部署：Docker + systemd
full 模式，輸出到 ./docs/spec

綠地的特殊處：

• 沒有實作可盤點，gate 基線一律 not_measured

• 所有 gate 先設 report-only，等有程式碼再轉 blocking

• 第一批 TASK 會包含「建立測試骨架 + 架構測試」，這是刻意的——沒有 test runner 就沒有任何後續指標

• implementation_status 全為 not_started，implementation_targets 全列入 new_files

綠地反而更該把 Harness 做好——從第一天就有架構斷言，BC 邊界永遠不會漂掉。

情境 3：只想量現況，還不想產文件

/spex-sdd
只做實作盤點與品質基線量測，輸出一份現況報告
不要產 backbone、不要產文件、不要產 harness

適合：

• 接手陌生專案想快速掌握

• 決定要不要導入前先估工作量

• 給主管看的技術債報告

產出：實作現況對照表 + 六項指標的實測數值。不動任何檔案。

情境 4：推進下一個 slice

/spex-sdd SLICE-03：退貨與折讓流程，接續 docs/spec/ 既有 backbone

它會：讀既有 backbone → 不動既有 ID → 只增補本 slice 的 registry 列與文件章節 → 更新 slice registry → 跑 validator。

檢查點：確認它沒有動到既有 slice 的內容。validator 的 id.duplicate 和版本歷程可以佐證。

情境 5：零測試專案

最常見的棕地狀況。別想一次六項全開。

harness-catalog.md 有建置順序，照這個排 slice：

Prompt：

本專案目前零測試。請依 harness-catalog 的零起點順序，
把六個 gate 的建置各排成一個 TASK-HARNESS-xxx，
並在 agent_execution_plan.json 標好依賴順序

情境 6：多 repo（前後端分離）

這是多 repo 系統最容易出錯的地方，本方法有專門的檢查。

/spex-sdd
本系統橫跨三個 repo：
- /Users/leo/work/XurfGoAPI-Gateway（Go，gateway + 微服務）
- /Users/leo/work/XurfPOS_PLUS（Vue 3，POS 前端）
- /Users/leo/work/xurf-infra（部署腳本與 systemd unit）
三個都要盤點。implementation_targets 必須指對 repo。
harness.yaml 的 gate 要分 repo 定義（Go 與 TS 用不同工具）

驗證方式：

# 分別對每個 repo 檢查路徑
python3 .../validate_spec.py docs/spec --repo /Users/leo/work/XurfGoAPI-Gateway
python3 .../validate_spec.py docs/spec --repo /Users/leo/work/XurfPOS_PLUS

看 path.missing 有沒有出現在不該出現的 repo。

情境 7：只想補某個模組的 UI/UX 規格

/spex-sdd
只針對「訂單管理」模組補 UI/UX 規格：
- FSD 的 Screen Contract（含 State Matrix、Interaction Contract、RWD）
- USD 的 UI 驗收場景
- STO 的 UI/UX 測試矩陣
- UI mockup（HTML→PNG 高擬真，用專案既有 Tailwind token）
- TASK-UI-xxx，含 detector 綁定
其他章節不動

UI/UX 判準（產品級設計水準、避免 AI 生成感的逐項檢查、mockup 與狀態示意圖必須並存）集中放在 references/document-specs.md 管理。

UI 的 detector 現實：多數 UI 規範綁得上 lint rule（window.confirm、技術 enum 直出），但「多個 primary action 競爭」這類綁不上——會被放進 advisory_notes 並登記 misfit-log，這是設計上的誠實，不是漏掉。

情境 8：交付用（投標、稽核、驗收）

/spex-sdd
full 模式，產出完整七份文件套件
用途：客戶驗收交付，需要文件完整性
Harness 部分仍要產，但 gate 全設 report-only（客戶端 CI 我們碰不到）

full 模式下所有模組都會完整展開，不會有 outline 狀態。

注意：full 模式產出的規格量大，其中相當比例沒有經過任何實作驗證。交付前建議在文件標註「本文件為設計規格，實作狀態見實作現況對照表」。

情境 9：AI 違反了規範，被人工發現

這是 misfit log 的核心流程，也是這個方法唯一的學習輸入。

剛才 code review 發現 AI 在 handler 裡直接組 SQL 字串帶 tenantId，
GATE-ARCH-03 沒有抓到（它只檢查參數傳遞，不檢查字串拼接）。
請記入 misfit-log.md

會記兩筆：

第二筆是重點——它代表 harness 有洞。應自動建議一個 TASK-HARNESS-xxx 去補 analyzer 規則。

判斷準則：問自己「這個問題是被 gate 抓到的，還是我人工發現的？」人工發現的一律記 undetected，不管當下有沒有時間補。

情境 10：gate 一直紅，或門檻訂錯了

GATE-COV-01 連續三次紅燈，Domain 覆蓋率卡在 82%，門檻是 90%。
請依 misfit-log 的處理規則判斷這是程式碼問題還是門檻問題

處理規則：

• 同一 gate 連紅 3 次 → 檢討門檻是否不合理，或任務拆得太大

• 門檻要重訂時，必須同時更新 baseline / threshold / target / 期程四欄，並記入版本歷程

不要偷偷把門檻調低就算了，調整要留痕跡，否則半年後沒人知道為什麼標準變鬆了。

反模式：把 gate 從 blocking 改成 report-only 來「解決」紅燈。一個被關掉的 gate 比沒有 gate 更糟——它會製造「我們有在把關」的錯覺。

情境 11：接下游測試產生器

backbone 產完後：

/spex-gen-test-docs-v5     # Unit / Integration / Component / E2E
/spex-gen-e2e-docs-v5      # 前端 App 的 E2E 專家層

它們會自動偵測並消費本方法的 canonical 產物，沿用 SC/SCREEN/FR/US/TASK ID，不另行發明。

額外提供給它們的：harness.yaml 的覆蓋率與突變測試門檻，就是這兩個 skill 的目標值。可以明講：

/spex-gen-test-docs-v5
目標門檻依 docs/spec/harness.yaml：Domain 層 line coverage ≥ 90%、mutation score ≥ 70%

情境 12：接進 CI

harness.yaml 的 ci 區段定義了分類，但實際的 CI 設定要你自己接。建議：

# .github/workflows/spec-check.yml（示意）
- name: 規格結構驗證
  run: python3 .claude/skills/spex-sdd/scripts/validate_spec.py docs/spec --repo .

- name: Harness blocking gates
  run: |
    dotnet test tests/Domain.Tests                      # GATE-UT-01
    dotnet test /p:CollectCoverage=true /p:Threshold=90 # GATE-COV-01
    dotnet test --filter Category=Architecture          # GATE-ARCH-01

把 validator 接進 CI 是最划算的一步——文件跟程式碼一起被把關，才不會又慢慢腐爛回去。exit code 1 代表有 FAIL。

也可以請它幫你產：

依 harness.yaml 產生對應的 GitHub Actions / GitLab CI 設定檔
blocking gate 進 PR check，nightly gate 進排程 workflow

情境 13：多人協作、文件進版控

建議把 docs/spec/ 進 git，和程式碼同 repo。

衝突處理：

• backbone 是唯一 ID registry，多人同時新增 slice 會在 registry 表格處衝突

• 建議約定：一次一個人推一個 slice，或每人負責固定模組

• misfit-log.md 是 append-only，衝突機率低

Code review 時看什麼：

• backbone diff（有沒有動到既有 ID？）

• validator 輸出（PR 描述裡貼）

• _HARNESS.md 的門檻有沒有被偷偷調低

產出物導覽

產出後的三分鐘檢查

1. 打開 _HARNESS.md，看六項指標是不是都有 gate 或不適用理由

2. 打開 agent_tasks.md 第一個 TASK，看它的禁止事項有沒有 Detector 欄

3. 跑一次 validator，確認 FAIL = 0

validator 使用

基本用法

# 結構驗證
python3 ~/.claude/skills/spex-sdd/scripts/validate_spec.py docs/spec

# 加上 repo 檢查 implementation_targets 路徑是否存在
python3 .../validate_spec.py docs/spec --repo /path/to/repo

# JSON 輸出給 CI 解析
python3 .../validate_spec.py docs/spec --json

離開碼：0 = 無 FAIL；1 = 有 FAIL；2 = 找不到必要產物。

輸出解讀

[WARN] harness.to_be_built: 待建置的 gate：GATE-MUT-01（需有對應 TASK）
[FAIL] task.no_gate: TASK TASK-MSG-001 未列出 gate_ids（必填）

--- FAIL 1 / WARN 1 / PASS 5 ---

• FAIL 必須修掉才算完成

• WARN 必須逐條說明處置（可以是「已知，本期不處理，理由是…」）

• PASS 是通過的檢查群組數，不是檢查項數

錯誤代碼表

追溯性

任務

Harness

計畫與追溯檔

Prompt 範本集

盤點與基線（第一次導入必跑）

/spex-sdd
專案 repo：<路徑清單>
技術棧：<...>
本次只做實作盤點與品質基線量測 + Harness 設計，不產七份文件
輸出到 docs/spec/

展開一個 slice

/spex-sdd
SLICE-0X：<模組或流程名稱>
接續 docs/spec/ 既有 backbone，只展開本 slice，其餘維持 outline
完成後跑 validator 並附輸出

全套（綠地或交付）

/spex-sdd
新系統：<名稱>
業務背景：<兩三句>
技術棧：<...>
模組：<清單>
權限/租戶：<...>
部署：<...>
full 模式，輸出到 ./docs/spec

記錄 misfit

<描述發現的問題>
這是被哪個 gate 抓到的？如果是人工發現，記為 undetected 並提出 detector 方案

只補 Harness

/spex-sdd
docs/spec/ 已有完整文件。只產 _HARNESS.md 與 harness.yaml：
先量基線，門檻訂在現況+合理增量，六項指標缺的寫不適用理由

產 CI 設定

依 docs/spec/harness.yaml 產生 GitHub Actions workflow：
blocking gate 進 PR check、nightly gate 進排程、validator 每次都跑

要求驗證報告

對 docs/spec/ 跑完整驗證：
1. 實跑 scripts/validate_spec.py 並貼出原始輸出
2. 依 validation-rules.md 做語意驗證（UI 水準、實作對齊、規範 forces）
3. 列出所有 FAIL 的修正方案與所有 WARN 的處置說明

常見錯誤

錯誤一：一開口就要全套

棕地專案叫它 full 模式產七份文件，會得到大量沒經過驗證的規格，且改起來要動七個檔案。先盤點、再 slice。

錯誤二：門檻訂理想值

「覆蓋率就該 90%」——現況 45% 的專案設 90%，第一天全紅，一週內 gate 被關掉。應該訂在現況 + 合理增量，把 90% 放在 target 欄配期程。

錯誤三：把紅燈 gate 改成 report-only 了事

這是最危險的反模式。改門檻可以，但要留痕跡、記版本歷程、寫理由。偷偷關掉等於自欺。

錯誤四：不記 undetected

「這次人工抓到了，修掉就好」——下次同樣的問題還是只能靠人工抓。每一筆人工發現都代表 harness 有洞，不記就永遠補不起來。

錯誤五：規範沒寫 Why

不可使用 EF Core——AI 在遇到規範沒提到的 ORM 時無法判斷該不該用。寫上 Why（「團隊統一用 Dapper，混用會造成 transaction 邊界混亂」）它才能推理。

錯誤六：跳過 validator

「AI 說它檢查過了」不算。這個方法的整個設計前提就是不信任自我宣稱，輸出要貼出來。

錯誤七：只掃 cwd

前後端分 repo 卻只給一個路徑，會得到一半的盤點結果和指錯 repo 的 implementation_targets。

錯誤八：突變測試一開始就全開

它很慢。第一次只對 Domain 層開、nightly 跑。整個 repo 全開會讓 CI 變成幾小時。

完成定義

一個 slice 或一次生成算完成，必須：

• scripts/validate_spec.py 實跑，FAIL = 0，輸出已貼出

• _HARNESS.md 與 harness.yaml 存在，六項指標各有 gate 或不適用理由

• 每條 forbidden_actions 都是物件格式且 detector 存在

• 每個可測量 NFR 綁 gate 或說明為何不能

• 每個 TASK 有 gate_ids、test_first、可執行的 acceptance_command

• implementation_status 正確（不會叫 AI 重寫已完成的功能）

• uncovered_risks 已顯式聲明，且 _HARNESS.md 說明人工補償措施

• slice 模式：本 slice 完整、其餘 outline 且未被寫成細節、slice registry 已更新

• 有 UI 者：Screen Contract + mockup + 狀態示意圖三者齊備

• misfit-log 已記錄本次的 gate 結果與發現

建議的實務節奏

一句話

這個方法不是要你寫更多文件，是要你把已經寫下的規範變成機器會執行的檢查。

沒有 detector 的規範，寫得再好也只是願望。

相關文件

• 設計歷程：spex-sdd_設計歷程_把規範變成機器可驗證的關卡.md

• v4 方法論（backbone / DDD-BDD-TDD 的原始設計）：generate-tech-docs-v4_從規格到開發的技術文件方法論.md

• Skill 內部規格：~/.claude/skills/spex-sdd/references/