Communitygithub.com

tangjuyo/reels-blocker

根據使用者需求,為目前功能產生自訂的檢查清單。

reels-blocker 是什麼?

此技能會根據使用者的需求與專案背景,自動產生一份專門用於驗證「需求品質」的檢查清單(Checklist),其核心理念是將檢查清單視為「需求文件的單元測試」。它並非用於測試程式實作的正確性,而是用於評估需求的完整性、清晰度、一致性與可測量性。 該技能支援所有基於 SKILL.md 的 AI Agent 平台(如 Claude Code、Cursor、Codex 等),透過分析使用者的 $ARGUMENTS、專案中的 spec.md、plan.md 與 tasks.md 檔案,並可選用 .specify/extensions.yml 中的鉤子(hook)進行前置擴展。生成的檢查清單會依品質維度(如完整性、清晰度、情境覆蓋率)分類,採用特定格式(例如問題形式並標註 [Gap] 或 [Spec §X.Y])來精準定位需求缺口,協助開發者與審查者在實施前發現潛在問題。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-checklist

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

檢查清單目的:「需求的單元測試」

關鍵概念:檢查清單是需求寫作的單元測試——它們用於驗證特定領域中需求的品質、清晰度與完整性。

非用於驗證/測試:

  • ❌ 非「驗證按鈕點擊是否正確」
  • ❌ 非「測試錯誤處理是否正常」
  • ❌ 非「確認 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):
      ## 擴展鉤子
      
      **自動前置鉤子**:{extension}
      正在執行:`/{command}`
      EXECUTE_COMMAND:{command}
      
      在繼續執行步驟之前,請等待鉤子命令的結果。
      
      在產生上述區塊後,你必須實際調用該鉤子並等待其完成才能繼續。以你自己在此 Agent/工作階段中執行命令的方式執行它(調用方式可能與上面顯示的文字 {command} ID 不同,例如,skills-mode Agent 會以 /skill:speckit-... 或 $speckit-... 執行)。僅輸出區塊本身並不代表已執行鉤子。
  • 若未註冊任何鉤子或 .specify/extensions.yml 不存在,則跳過。

執行步驟

  1. 設定:從儲存庫根目錄執行 .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")。
  2. 若存在:載入 .specify/memory/constitution.md 以取得專案原則與治理約束。

  3. 釐清意圖(動態):推導最多三個初始脈絡性釐清問題(無預製目錄)。它們必須:

    • 從使用者的措辭 + 從規格/計畫/任務中提取的信號中產生
    • 僅詢問會實質改變檢查清單內容的資訊
    • 若在 $ARGUMENTS 中已無歧義,則個別跳過
    • 優先追求精確而非廣度

    產生演算法:

    1. 提取信號:功能領域關鍵字(例如 auth、latency、UX、API)、風險指標("critical"、"must"、"compliance")、利害關係人提示("QA"、"review"、"security team")以及明確交付物("a11y"、"rollback"、"contracts")。
    2. 將信號分組為候選重點領域(最多 4 個),按相關性排序。
    3. 若非明確,則識別可能的對象與時機(作者、審查者、QA、發布)。
    4. 檢測遺漏的維度:範圍廣度、深度/嚴謹度、風險重點、排除邊界、可測量的驗收標準。
    5. 從以下原型中選擇問題來制定:
      • 範圍細化(例如:「這是否應包含與 X 和 Y 的整合接觸點,還是僅限於本地模組的正確性?」)
      • 風險優先級(例如:「哪些潛在風險領域應強制加入關卡檢查?」)
      • 深度校準(例如:「這是一個輕量級提交前健全性清單,還是正式的發布關卡?」)
      • 對象框架(例如:「這將由作者本人使用,還是在 PR 審查期間由同儕使用?」)
      • 邊界排除(例如:「我們是否應明確排除本輪的效能調優項目?」)
      • 情境類別缺口(例如:「未檢測到復原流程——回退/部分失敗路徑是否在範圍內?」)

    問題格式規則:

    • 若呈現選項,請產生一個精簡表格,包含欄位:選項 | 候選項 | 重要性
    • 最多 A–E 五個選項;若自由回答更清晰,則省略表格
    • 切勿要求使用者重述他們已經說過的話
    • 避免臆測性類別(不憑空想像)。若不確定,直接詢問:「請確認 X 是否屬於範圍內。」

    無法互動時的預設值:

    • 深度:標準
    • 對象:若與程式碼相關,則為審查者(PR);否則為作者
    • 重點:前 2 個相關性群組

    輸出問題(標示為 Q1/Q2/Q3)。回答後:若仍有 ≥2 個情境類別(替代/例外/復原/非功能性領域)不明確,你可以最多再問兩個針對性的追問(Q4/Q5),每個附上一行說明理由(例如:「未解決的復原路徑風險」)。總問題數不得超過五個。若使用者明確拒絕,則跳過升級。

  4. 理解使用者請求:結合 $ARGUMENTS + 釐清問題答案:

    • 推導檢查清單主題(例如安全性、審查、部署、UX)
    • 彙整使用者提到的明確必備項目
    • 將重點選擇映射到類別架構
    • 從規格/計畫/任務中推斷任何遺漏的脈絡(不要憑空想像)
  5. 載入功能脈絡:從 FEATURE_DIR 讀取:

    • spec.md:功能需求與範圍
    • plan.md(若存在):技術細節、相依性
    • tasks.md(若存在):實施任務

    脈絡載入策略:

    • 僅載入與活躍重點領域相關的必要部分(避免傾倒整個檔案)
    • 優先將長章節總結為精簡的情境/需求要點
    • 使用漸進式揭露:僅在檢測到缺口時才進行後續檢索
    • 若原始文件很大,請產生臨時摘要項目,而非嵌入原始文字
  6. 產生檢查清單 - 使用 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 永遠可用』的假設是否已驗證?[假設]」
    • 相依性:……

[為便於翻譯而截斷]

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

相關技能