檢查清單目的:「需求的單元測試」
關鍵概念:檢查清單是需求寫作的單元測試——它們用於驗證特定領域中需求的品質、清晰度與完整性。
非用於驗證/測試:
- ❌ 非「驗證按鈕點擊是否正確」
- ❌ 非「測試錯誤處理是否正常」
- ❌ 非「確認 API 回傳 200」
- ❌ 非檢查程式碼/實作是否符合規格
用於需求品質驗證:
- ✅ 「是否已定義所有卡片類型的視覺層級需求?」(完整性)
- ✅ 「『醒目顯示』是否有以特定尺寸/位置量化?」(清晰度)
- ✅ 「所有互動元件的懸停狀態需求是否一致?」(一致性)
- ✅ 「是否已定義鍵盤導覽的無障礙需求?」(覆蓋率)
- ✅ 「規格是否定義 Logo 圖片載入失敗時的處理方式?」(邊界案例)
比喻:如果你的規格是以英文寫成的程式碼,檢查清單就是它的單元測試套件。你測試的是需求是否寫得好、完整、無歧義且可實施——而不是測試實作是否正常運作。
擁有權與核取方塊生命週期:
- 此命令產生的自訂檢查清單是審查者擁有的需求品質審查產物。
[x]表示審查者已確認該需求品質標準已滿足。[x]不代表實作工作已完成。- 此命令會產生或附加檢查清單項目;不得將產生的項目標記為
[x]。 - 僅在審查者明確要求時,AI Agent 才可協助評估項目。
checklists/requirements.md是/speckit-specify和/speckit-clarify維護的獨立內建規格品質檢查清單;此例外不適用於此處產生的自訂檢查清單。
使用者輸入
$ARGUMENTS
在繼續之前,你必須考慮使用者輸入(若非空白)。
執行前檢查
檢查擴展鉤子(在產生檢查清單之前):
- 檢查專案根目錄是否存在
.specify/extensions.yml。 - 若存在,讀取該檔案並查找
hooks.before_checklist索引鍵下的項目。 - 若 YAML 無法解析或無效,不要跳過:告知使用者
.specify/extensions.yml無法讀取(包含解析器錯誤),以及沒有檢查任何鉤子(包括任何註冊為必要(optional: false)的鉤子),然後繼續正常執行。 - 過濾掉
enabled明確為false的鉤子。將沒有enabled欄位的鉤子視為預設啟用。 - 對於每個剩餘鉤子,不要嘗試解讀或評估鉤子的
condition表達式:- 若鉤子沒有
condition欄位,或該欄位為 null/空,則將該鉤子視為可執行。 - 若鉤子定義了非空的
condition,則跳過該鉤子,將條件評估留給 HookExecutor 實作。
- 若鉤子沒有
- 在從鉤子命令名稱建構命令調用時,將點(
.)替換為連字號(-)。例如,speckit.git.commit→/speckit-git-commit。 - 對於每個可執行的鉤子,根據其
optional旗標輸出以下內容:- 可選鉤子(
optional: true):## 擴展鉤子 **可選前置鉤子**:{extension} 命令:`/{command}` 描述:{description} 提示:{prompt} 執行方式:`/{command}` - 必要鉤子(
optional: false):
在產生上述區塊後,你必須實際調用該鉤子並等待其完成才能繼續。以你自己在此 Agent/工作階段中執行命令的方式執行它(調用方式可能與上面顯示的文字## 擴展鉤子 **自動前置鉤子**:{extension} 正在執行:`/{command}` EXECUTE_COMMAND:{command} 在繼續執行步驟之前,請等待鉤子命令的結果。{command}ID 不同,例如,skills-mode Agent 會以/skill:speckit-...或$speckit-...執行)。僅輸出區塊本身並不代表已執行鉤子。
- 可選鉤子(
- 若未註冊任何鉤子或
.specify/extensions.yml不存在,則跳過。
執行步驟
-
設定:從儲存庫根目錄執行
.specify/scripts/bash/check-prerequisites.sh --json --template checklist-template,並解析 JSON 以取得 FEATURE_DIR、AVAILABLE_DOCS 列表和 TEMPLATE_CONTENT。- 所有檔案路徑必須是絕對路徑。
- 對於引數中的單引號(例如 "I'm Groot"),請使用跳脫語法:例如 'I'''m Groot'(如果可能,請改用雙引號:"I'm Groot")。
-
若存在:載入
.specify/memory/constitution.md以取得專案原則與治理約束。 -
釐清意圖(動態):推導最多三個初始脈絡性釐清問題(無預製目錄)。它們必須:
- 從使用者的措辭 + 從規格/計畫/任務中提取的信號中產生
- 僅詢問會實質改變檢查清單內容的資訊
- 若在
$ARGUMENTS中已無歧義,則個別跳過 - 優先追求精確而非廣度
產生演算法:
- 提取信號:功能領域關鍵字(例如 auth、latency、UX、API)、風險指標("critical"、"must"、"compliance")、利害關係人提示("QA"、"review"、"security team")以及明確交付物("a11y"、"rollback"、"contracts")。
- 將信號分組為候選重點領域(最多 4 個),按相關性排序。
- 若非明確,則識別可能的對象與時機(作者、審查者、QA、發布)。
- 檢測遺漏的維度:範圍廣度、深度/嚴謹度、風險重點、排除邊界、可測量的驗收標準。
- 從以下原型中選擇問題來制定:
- 範圍細化(例如:「這是否應包含與 X 和 Y 的整合接觸點,還是僅限於本地模組的正確性?」)
- 風險優先級(例如:「哪些潛在風險領域應強制加入關卡檢查?」)
- 深度校準(例如:「這是一個輕量級提交前健全性清單,還是正式的發布關卡?」)
- 對象框架(例如:「這將由作者本人使用,還是在 PR 審查期間由同儕使用?」)
- 邊界排除(例如:「我們是否應明確排除本輪的效能調優項目?」)
- 情境類別缺口(例如:「未檢測到復原流程——回退/部分失敗路徑是否在範圍內?」)
問題格式規則:
- 若呈現選項,請產生一個精簡表格,包含欄位:選項 | 候選項 | 重要性
- 最多 A–E 五個選項;若自由回答更清晰,則省略表格
- 切勿要求使用者重述他們已經說過的話
- 避免臆測性類別(不憑空想像)。若不確定,直接詢問:「請確認 X 是否屬於範圍內。」
無法互動時的預設值:
- 深度:標準
- 對象:若與程式碼相關,則為審查者(PR);否則為作者
- 重點:前 2 個相關性群組
輸出問題(標示為 Q1/Q2/Q3)。回答後:若仍有 ≥2 個情境類別(替代/例外/復原/非功能性領域)不明確,你可以最多再問兩個針對性的追問(Q4/Q5),每個附上一行說明理由(例如:「未解決的復原路徑風險」)。總問題數不得超過五個。若使用者明確拒絕,則跳過升級。
-
理解使用者請求:結合
$ARGUMENTS+ 釐清問題答案:- 推導檢查清單主題(例如安全性、審查、部署、UX)
- 彙整使用者提到的明確必備項目
- 將重點選擇映射到類別架構
- 從規格/計畫/任務中推斷任何遺漏的脈絡(不要憑空想像)
-
載入功能脈絡:從 FEATURE_DIR 讀取:
- spec.md:功能需求與範圍
- plan.md(若存在):技術細節、相依性
- tasks.md(若存在):實施任務
脈絡載入策略:
- 僅載入與活躍重點領域相關的必要部分(避免傾倒整個檔案)
- 優先將長章節總結為精簡的情境/需求要點
- 使用漸進式揭露:僅在檢測到缺口時才進行後續檢索
- 若原始文件很大,請產生臨時摘要項目,而非嵌入原始文字
-
產生檢查清單 - 使用 TEMPLATE_CONTENT 作為結構模板,並建立「需求的單元測試」:
- 若不存在,則建立
FEATURE_DIR/checklists/目錄 - 產生唯一的檢查清單檔案名稱:
- 根據領域使用簡短描述性名稱(例如
ux.md、api.md、security.md) - 格式:
[domain].md
- 根據領域使用簡短描述性名稱(例如
- 檔案處理行為:
- 若檔案不存在:建立新檔案,並從 CHK001 開始編號項目
- 若檔案存在:將新項目附加到現有檔案,從最後一個 CHK ID 繼續編號(例如,若最後一個項目是 CHK015,則新項目從 CHK016 開始)
- 絕不刪除或取代現有檢查清單內容——始終保留並附加
- 保留每個新產生的項目為未勾選(
[ ]);核取方塊狀態屬於審查者
核心原則 - 測試需求,而非實作: 每個檢查清單項目必須評估需求本身的以下面向:
- 完整性:是否涵蓋所有必要的需求?
- 清晰度:需求是否無歧義且具體?
- 一致性:需求之間是否一致?
- 可測量性:需求能否被客觀驗證?
- 覆蓋率:是否涵蓋所有情境/邊界案例?
類別結構 - 按需求品質維度分組項目:
- 需求完整性(是否記錄了所有必要的需求?)
- 需求清晰度(需求是否具體且無歧義?)
- 需求一致性(需求之間是否一致且無衝突?)
- 驗收標準品質(成功標準是否可測量?)
- 情境覆蓋率(是否涵蓋所有流程/案例?)
- 邊界案例覆蓋率(是否定義了邊界條件?)
- 非功能性需求(效能、安全性、無障礙等——是否被明確規定?)
- 相依性與假設(是否已記錄並驗證?)
- 模糊性與衝突(哪些需要釐清?)
如何撰寫檢查清單項目 -「英文的單元測試」:
❌ 錯誤(測試實作):
- 「驗證登陸頁面顯示 3 張劇集卡片」
- 「測試懸停狀態在桌機上正常運作」
- 「確認點擊 Logo 導航回首頁」
✅ 正確(測試需求品質):
- 「是否指定了精選劇集的確切數量和版面?」[完整性]
- 「『醒目顯示』是否以特定尺寸/位置量化?」[清晰度]
- 「所有互動元件的懸停狀態需求是否一致?」[一致性]
- 「是否定義了所有互動 UI 的鍵盤導覽需求?」[覆蓋率]
- 「Logo 圖片載入失敗時的備援行為是否已指定?」[邊界案例]
- 「是否定義了非同步劇集資料的載入狀態?」[完整性]
- 「規格是否定義了競爭 UI 元素的視覺層級?」[清晰度]
項目結構: 每個項目應遵循以下模式:
- 以問題形式詢問需求品質
- 專注於書面(或未書面)的規格/計畫內容
- 在方括號中標示品質維度 [完整性/清晰度/一致性/等]
- 在檢查現有需求時引用規格章節
[Spec §X.Y] - 在檢查遺漏的需求時使用
[Gap]標記
各品質維度範例:
完整性:
- 「是否針對所有 API 失敗模式定義了錯誤處理需求?[Gap]」
- 「是否為所有互動元件指定了無障礙需求?[完整性]」
- 「是否為響應式版面定義了行動裝置斷點需求?[Gap]」
清晰度:
- 「『快速載入』是否以具體時間閾值量化?[清晰度, Spec §NFR-2]」
- 「『相關劇集』的選擇標準是否明確定義?[清晰度, Spec §FR-5]」
- 「『醒目』是否以可測量的視覺屬性定義?[模糊性, Spec §FR-4]」
一致性:
- 「所有頁面的導覽需求是否一致?[一致性, Spec §FR-10]」
- 「登陸頁面與詳細頁面的卡片元件需求是否一致?[一致性]」
覆蓋率:
- 「是否定義了零狀態情境(無劇集)的需求?[覆蓋率, 邊界案例]」
- 「是否處理了並發使用者互動情境?[覆蓋率, Gap]」
- 「是否針對部分資料載入失敗定義了需求?[覆蓋率, 例外流程]」
可測量性:
- 「視覺層級需求是否可測量/可測試?[驗收標準, Spec §FR-1]」
- 「『平衡的視覺重量』能否被客觀驗證?[可測量性, Spec §FR-2]」
情境分類與覆蓋率(需求品質重點):
- 檢查是否存在以下需求:主要、替代、例外/錯誤、復原、非功能性情境
- 對於每個情境類別,詢問:「[情境類型] 需求是否完整、清晰且一致?」
- 若缺少某情境類別:「[情境類型] 需求是故意排除還是遺漏?[Gap]」
- 當有狀態變更時,包含復原/回退:「是否針對遷移失敗定義了回退需求?[Gap]」
可追溯性需求:
- 最低要求:≥80% 的項目必須包含至少一個可追溯性參考
- 每個項目應引用:規格章節
[Spec §X.Y],或使用標記:[Gap]、[模糊性]、[衝突]、[假設] - 若無 ID 系統:「是否建立了需求與驗收標準 ID 方案?[可追溯性]」
揭露與解決問題(需求品質問題): 對需求本身提出問題:
- 模糊性:「『快速』一詞是否以具體指標量化?[模糊性, Spec §NFR-1]」
- 衝突:「§FR-10 與 §FR-10a 的導覽需求是否衝突?[衝突]」
- 假設:「『Podcast API 永遠可用』的假設是否已驗證?[假設]」
- 相依性:……
- 若不存在,則建立
[為便於翻譯而截斷]