xt-mahh/sddl

規格驅動開發循環 (SDDL)

已開源：https://github.com/xt-mahh/sddl (2026-08-06, MIT License) 完整方法論 + 檢查器腳本 + 範例專案見 GitHub 倉庫。

概述

SDDL 把 AI 程式設計從「對話驅動」升級為「規格驅動」。核心承諾：先定義清楚做什麼，再動手寫程式碼——以結構化 Spec 為單一事實來源，雙 Loop 閉環保證品質和可審計性。

形成 Loop（回答「做什麼」）       派生 Loop（回答「怎麼做對」）
需求 ──▶ 訪談 ──▶ Spec草稿 ──▶ 凍結 Spec ──▶ tests/code/docs ──▶ 收斂
              └─▶ SQC品質檢查 ──┘                  └─▶ C1-C4一致性檢查 ─┘
              └─▶ 決策點確認 ──┘

為什麼用 SDDL：對話式程式設計的痛點——上下文漂移（聊 50 輪忘了第 3 輪的約定）、多 artifact 不同步（程式碼改了測試/文件沒跟上）、驗收主觀化（「感覺對了」代替「符合規格」）。SDDL 用穩定可全文載入的 Spec + 分層一致性檢查解決三者。

使用時機

觸發：

• 使用者要開始新專案開發、寫核心功能、設計系統架構
• 使用者說「先規劃」「先設計」「先寫規格」「這個功能怎麼做」
• 使用者需要多個 artifact（程式碼+測試+文件）同步產出的任務
• 專案介面 ≥ 5 個，或 must 級驗收 ≥ 5 個，預期生命週期 > 2 週

不適用（直接寫程式碼，不要用本 skill）：

• 一次性腳本 / 原型 / POC / 探索性研究程式碼
• 單檔案小工具（介面 < 5，無多 artifact 需求）
• 使用者明確說「直接寫」「快速做」

分階段命令（本 skill 的核心互動方式）：

命令	階段	做什麼	產出
/sddl:init	初始化	建目錄結構、讀已有程式碼/需求	sddl/ 骨架 + state.yaml
/sddl:interview	形成	分層需求訪談（L0-L2 必答）	需求陳述
/sddl:spec	形成	生成 L1-L5 spec 草稿 + 決策點標記	specs/<domain>/spec.yaml
/sddl:confirm	形成	決策點摘要 clarify 確認	decisions/<domain>-confirmation.yaml
/sddl:freeze	形成	SQC 檢查 + 凍結	spec_status: frozen
/sddl:derive	派生	從 spec 派生 tests/code/docs	src/ tests/ docs/
/sddl:verify	派生	C1-C4 分層檢查 + 收斂判定	checks/*.json + 收斂/路由
/sddl:archive	歸檔	變更歸檔、spec 合併	specs/ 更新 + CHANGELOG

核心原則

1. Spec 是神諭，但可被質疑：派生中發現的 spec 缺陷 → 解凍 → 回形成 Loop 修訂 → 重新凍結（走完整品質門禁，不繞過）
2. 確定性優先：能用靜態分析/schema/測試執行解決的，絕不用 LLM 猜
3. 收斂是工程系統：硬條件門禁 + 軟條件共識率 + 預算約束 + 人工兜底
4. 決策點不靜默：模糊處 AI 給預設值 + 標記決策點，使用者確認後才凍結
5. 進度即目錄：階段完成 = 檔案存在（Convention over Config），中斷恢復免費

目錄即狀態（Convention over Config）

不看狀態檔案，看目錄就知道進度。這是本 skill 的進度可見性機制（配合 git commit 作為 checkpoint）。

<project>/
├── sddl/
│   ├── specs/                    # 存在 = 訪談完成，spec 已生成
│   │   └── <domain>/spec.yaml    # status: frozen = 凍結完成
│   ├── changes/                  # 變更提案（增量開發，可並行）
│   ├── decisions/                # 決策點確認記錄
│   │   └── <domain>-confirmation.yaml
│   ├── checks/                   # 檢查報告存檔（機器可讀 JSON）
│   │   ├── sqc-<domain>-v1.json
│   │   └── c1-c4-<domain>-v1.json
│   └── state.yaml                # 唯一元資料：階段指標 + 預算 + 最近檢查
├── src/                          # 派生 Loop 後出現
├── tests/                        # 派生 Loop 後出現
├── docs/                         # 派生 Loop 後出現（含 current/planned 分區）
└── (git commit 在每個階段完成時)

state.yaml 最小化（只存指標，不存進度詳情）：

spec_status: frozen          # interviewing | drafting | reviewing | frozen | evolved
current_phase: derivation    # formation | derivation | complete
budget: { formation: 40%, implementation: 12%, revision: 100% }
last_check: { type: sqc, spec: auth-v0.1.0, result: pass, at: 2026-08-06T16:00 }

恢復規則：skill 重新載入時掃目錄——specs/ 無 = 從 interview 開始；specs/ 有但無 decisions/ = 從 confirm 開始；decisions/ 有但 spec 未 frozen = 從 freeze 開始；src/ 有但無 checks/ = 從 derive 開始；checks/ 有 = 從 verify 開始。

階段完成 = git commit（E 輔助）：每個命令成功結束後 commit（feat(sddl): interview complete），保證可回溯。

雙 Loop 流程編排

形成 Loop（做對的事）——5 個命令

/sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
     │              │              │              │
     └─ 修訂 ──────┴──────┴──────┘
       （SQC 不過 / 使用者改決策點 → 回上一步，最多 5 輪）

命令	關鍵動作	檢查點
interview	分層提問 L0-L2（≤10 問必答），產出需求陳述	需求陳述完整
spec	生成 L1-L5 spec + 決策點標記（模糊處登記 DP）	SQC-def 骨架通過
confirm	決策點摘要 → clarify 逐項確認（含自訂輸入）	決策點無 pending
freeze	SQC 全檢 + 確認記錄簽署	SQC 無 blocker + frozen

派生 Loop（把事做對）——3 個命令

/sddl:derive → /sddl:verify → (收斂) → 完成
     │              │
     └─ 路由 ───────┘
       （violation → 重派 code/tests/docs 或 解凍回形成 Loop）

命令	關鍵動作	檢查點
derive	從 spec 派生 tests/code/docs	artifacts 可執行
verify	C1-C4 分層檢查 + 收斂判定	硬門禁 + 軟共識 + must 覆蓋
archive	變更歸檔、spec 合併	CHANGELOG + spec 更新

檢查器腳本（scripts/）——確定性證據，不是語義判斷

腳本只負責確定性證據（型別檢查/測試執行/符號表/YAML），語義審核由 agent 的 LLM 能力執行：

# SQC 確定性檢查（形成 Loop 門禁）—— 腳本給出事實
python3 scripts/check_sqc.py sddl/specs/<domain>/spec.yaml --verbose

# C1-C4 確定性檢查（派生 Loop 門禁）—— 腳本給出事實
python3 scripts/check_c1_c4.py . --verbose

# 狀態恢復（中斷後）—— 掃目錄輸出當前進度 + 下一步命令
python3 scripts/sddl_status.py .

• 退出碼：0 = pass/converged，1 = fail（可掛 CI）
• --json 輸出機器可讀證據（供 LLM 審核引用）

分工原則（重要）：

層	誰負責
確定性證據（硬條件）：schema 合法/介面存在/測試通過/符號表	腳本
語義審核（軟條件）：行為覆蓋/THEN 可斷言/測試真覆蓋/文件真實性	agent 的 LLM（見 references/llm-review.md）

不要用腳本啟發式做語義判斷——字串匹配會假陰性爆炸（T1 實測 C1-sem 0.48）。腳本是證據收集器，agent 是裁判。

何時讀哪個 Reference

按需載入，不一次全讀（漸進披露）：

場景	讀
執行 interview	references/formation-loop.md（階段 1）
生成 spec	references/spec-schema.md + templates/spec-template.yaml
SQC 檢查	references/sqc-checklist.md（def 用腳本，sem 用 LLM）
決策點確認	templates/decision-summary.md
派生 artifacts	references/derivation-loop.md（階段 1-2）
C1-C4 檢查	references/checker-matrix.md（def 用腳本，sem 用 LLM）
語義審核操作	references/llm-review.md（核心：LLM 如何做審核）
路由/回寫/預算	references/derivation-loop.md（階段 3-5）
變更提案	references/formation-loop.md（變更管理）

預算與降級

• 三預算：formation（2M token / 5 輪）/ implementation（15M / 4 sessions）/ revision（5M，L2 扣 10%、L3 扣 25%、首次 L3 免費）
• 預算記錄在 state.yaml，每命令更新
• 預算耗盡 → 轉人工驅動，不自動降級（spec 品質是地基）
• 降級路徑：D1 語義降級 → D2 should/could 移風險清單 → D3 縮變異 → D4 拆 spec → D5 最佳努力交付

體驗規範（重要）

1. 分階段命令：絕不在一個回覆裡跑完整個雙 Loop——每個命令是獨立互動單元，之間有檢查點
2. 決策點用 clarify，自訂輸入顯式可見：每個決策點一個 clarify，附影響說明；choices 業務選項 ≤3 個，第 4 位固定放「自訂輸入（Other）」（實測 clarify 無自動 Other、choices 上限 4，必須顯式佔位）；question 文字提示「其他值請選自訂輸入」；使用者自訂值走捕獲協議（記錄 value+reason → 同步 spec → 確認記錄標 modified）；開放式決策點直接用無 choices 的 clarify
3. 進度可見：每個命令開始/結束時報告當前階段 + 下一步
4. 狀態寫入：每個命令結束寫 state.yaml + git commit
5. 檢查報告：每次檢查（SQC/C1-C4）寫 checks/*.json，報告可讀摘要 + 機器可讀詳情

常見陷阱

1. 跳過形成 Loop 直接派生——Spec 沒凍結就寫程式碼 = 回到對話式程式設計。/sddl:freeze 是硬邊界，未凍結不派生。
2. 決策點靜默決定——模糊處不標記 DP 直接寫預設值 = 使用者意圖失真。任何「替使用者選擇」必須登記 DP。
3. 檢查器自證循環——信任 AI 貼的標籤。C1-def 必須做結構反推（解析測試 AST），不信任標籤。
4. 語義檢查絕對分數——LLM 打 0-100 分不可信。用 Checklist 二分 + 投票共識率（客觀計票）。
5. 回寫繞過品質門禁——spec_error 直接改 spec = 自我放鬆標準。必須解凍 → 回形成 Loop → 重新凍結。
6. 狀態檔案膨脹——把所有進度寫進 state.yaml = 又回到「文件謊言」。state.yaml 只存指標，詳情在檔案本身。
7. 預算無記錄——不更新 state.yaml 預算 = 成本失控。每命令結束更新。
8. 語義檢查用粗糙字串匹配——T1 實測：關鍵詞匹配把 C1-sem 打到 0.48（假陰性爆炸）。優先使用 Checklist LLM 投票；啟發式僅作 fallback，且必須語義化（AST 提取斷言 + 結構化關鍵詞），首輪結果不可信，需人工複核。
9. 測試間共享狀態洩漏——T1 實測：記憶體 store 跨測試共享導致斷言失敗。派生時必須加隔離 fixture（autouse 重置）；測試斷言走公開介面，不直接存取內部 _store。
10. 純查詢函式帶副作用——T1 實測：detectDiscrepancy 內部改 status 違反 spec B006（應保持 draft）。純查詢介面（返回報告/查詢）不得修改狀態，C2-sem 應檢查。

驗證清單

• sddl/ 目錄結構正確（specs/changes/decisions/checks/state.yaml）
• spec.yaml 通過 SQC-def（schema 合法/引用完整/可斷言性/決策點覆蓋）
• 決策點全部 confirmed/modified/delegated（無 pending）
• 確認記錄簽署（overall: approved）
• spec_status: frozen 後才進入派生
• C1-def 做了結構反推（非信任標籤）
• 硬條件（C1-def/C2-def/C3/C4b-def）全過
• 軟條件共識率達標（c1_sem≥0.95 c2_sem≥0.95 c4a≥0.90 c4b_sem≥0.90）
• must 級驗收覆蓋 100%
• state.yaml 預算已更新
• 階段完成 git commit 已打

單次完成配方

從零開始新專案

/sddl:init → /sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
           → /sddl:derive → /sddl:verify → /sddl:archive

已有程式碼回填 spec（改造專案）

/sddl:init（讀已有程式碼）→ /sddl:spec（反向提取現狀 + 標記決策點）
  → /sddl:confirm → /sddl:freeze → /sddl:verify（驗證 spec↔code 一致性）

增量功能開發（spec 已凍結）

/sddl:init → 寫 changes/<name>/ 提案 → /sddl:confirm（受影響決策點）
  → /sddl:freeze → /sddl:derive → /sddl:verify → /sddl:archive

相關 Skill

• writing-plans：寫實施計畫（SDDL 的 changes/tasks.md 可用它）
• test-driven-development：TDD 是 SDDL 的驗證手段（C3 測試執行）
• hermes-agent-skill-authoring：本 skill 自身的創作規範