使用者輸入
$ARGUMENTS
在繼續之前,您必須考慮使用者輸入(如果不為空)。
執行前檢查
檢查擴充鉤子(規格化前):
- 檢查專案根目錄中是否存在
.specify/extensions.yml。 - 如果存在,讀取它並查找
hooks.before_specify鍵下的條目。 - 如果無法解析 YAML 或 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} 在繼續到大綱之前,請等待鉤子命令的結果。{command}ID 不同,例如,技能模式代理以/skill:speckit-...或$speckit-...運行)。僅發出區塊並不會運行該鉤子。
- 可選鉤子(
- 如果沒有註冊鉤子或
.specify/extensions.yml不存在,則跳過。
大綱
使用者在觸發訊息中 /speckit-specify 後面輸入的文字就是功能描述。假設您始終可以在本次對話中使用它,即使下方出現了文字 $ARGUMENTS。除非使用者提供了空命令,否則不要要求他們重複。
根據該功能描述,執行以下操作:
-
產生簡潔的短名稱(2-4 個單詞)來命名該功能:
- 分析功能描述並提取最有意義的關鍵字。
- 建立一個 2-4 個單詞的短名稱,以捕捉功能的精髓。
- 盡可能使用「動作-名詞」格式(例如 "add-user-auth"、"fix-payment-bug")。
- 保留技術術語和縮寫(OAuth2、API、JWT 等)。
- 保持簡潔但足夠描述性,以便一目了然。
- 範例:
- "I want to add user authentication" → "user-auth"
- "Implement OAuth2 integration for the API" → "oauth2-api-integration"
- "Create a dashboard for analytics" → "analytics-dashboard"
- "Fix payment processing timeout bug" → "fix-payment-timeout"
-
建立分支(可選,透過鉤子):
如果上述執行前檢查中的
before_specify鉤子成功運行,它將已建立/切換到一個 git 分支,並輸出包含BRANCH_NAME和FEATURE_NUM的 JSON。請記下這些值以供參考,但分支名稱不決定規格目錄的名稱。如果使用者明確提供了
GIT_BRANCH_NAME,則將其傳遞給鉤子,以便分支腳本將該確切值用作分支名稱(繞過所有前綴/後綴產生)。 -
建立規格功能目錄:
除非使用者明確提供
SPECIFY_FEATURE_DIRECTORY,否則規格檔案位於預設的specs/目錄下。SPECIFY_FEATURE_DIRECTORY的解析順序:- 如果使用者明確提供了
SPECIFY_FEATURE_DIRECTORY(例如,透過環境變數、參數或設定),則按原樣使用。 - 否則,在
specs/下自動產生:- 檢查
.specify/init-options.json中的feature_numbering(首選)或branch_numbering(已棄用,僅用於遷移——將在未來版本中移除)。 - 如果是
"timestamp":前綴是YYYYMMDD-HHMMSS(當前時間戳記)。 - 如果是
"sequential"或缺失:前綴是NNN(掃描specs/中現有目錄後的下一個可用 3 位數字)。 - 建構目錄名稱:
<前綴>-<短名稱>(例如003-user-auth或20260319-143022-user-auth)。 - 將
SPECIFY_FEATURE_DIRECTORY設定為specs/<目錄名稱>。 - 如果使用了
branch_numbering(且feature_numbering不存在),則發出一行警告:「⚠️branch_numbering在 init-options.json 中已棄用。請重新命名為feature_numbering。」
- 檢查
建立目錄和規格檔案:
mkdir -p SPECIFY_FEATURE_DIRECTORY- 透過 Spec Kit 預設/範本解析堆疊解析活躍的
spec-template(相當於specify preset resolve spec-template)。 - 將解析後的
spec-template檔案複製到SPECIFY_FEATURE_DIRECTORY/spec.md作為起點。 - 將
SPEC_FILE設定為SPECIFY_FEATURE_DIRECTORY/spec.md。 - 將解析後的路徑持久化到
.specify/feature.json:寫入實際解析後的目錄路徑值(例如{ "feature_directory": "<解析後的功能目錄>" }specs/003-user-auth),而不是文字字串SPECIFY_FEATURE_DIRECTORY。 這允許下游命令(/speckit-plan、/speckit-tasks等)在不安裝 git 分支名稱約定的情況下找到功能目錄。
重要:
- 每次
/speckit-specify調用只能建立一個功能。 - 規格目錄名稱和 git 分支名稱是獨立的——它們可能相同,但那是使用者的選擇。
- 規格目錄和檔案始終由此命令建立,從不透過鉤子建立。
- 如果使用者明確提供了
-
載入解析後的活躍
spec-template檔案,以了解所需的章節。 -
如果存在:載入
.specify/memory/constitution.md以獲取專案原則和治理約束。 -
遵循以下執行流程:
- 從引數解析使用者描述。 如果為空:錯誤「未提供功能描述」。
- 從描述中提取關鍵概念。 識別:參與者、動作、資料、約束。
- 對於不明確的部分:
- 根據上下文和行業標準做出有根據的猜測。
- 僅在以下情況標記 [NEEDS CLARIFICATION: 具體問題]:
- 選擇會顯著影響功能範圍或使用者體驗。
- 存在多種具有不同影響的合理解釋。
- 不存在合理的預設值。
- 限制:總共最多 3 個 [NEEDS CLARIFICATION] 標記。
- 依影響程度優先釐清:範圍 > 安全性/隱私 > 使用者體驗 > 技術細節。
- 填寫「使用者情境與測試」章節。 如果沒有明確的使用者流程:錯誤「無法確定使用者情境」。
- 產生功能需求。 每個需求必須是可測試的。 對未指定的細節使用合理的預設值(在「假設」章節中記錄假設)。
- 定義成功標準。 建立可衡量、與技術無關的結果。 同時包含量化指標(時間、性能、數量)和質化指標(使用者滿意度、任務完成率)。 每個標準必須在不安裝實作細節的情況下可驗證。
- 識別關鍵實體(如果涉及資料)。
- 返回:成功(規格已準備好可以規劃)。
-
使用範本結構將規格寫入
SPEC_FILE,用從功能描述(引數)中得出的具體細節替換預留位置,同時保留章節順序和標題。 -
規格品質驗證:在寫入初始規格後,根據品質標準對其進行驗證:
a. 建立規格品質檢查清單:在
SPECIFY_FEATURE_DIRECTORY/checklists/requirements.md產生一個檢查清單檔案,使用檢查清單範本結構,包含以下驗證項目:# 規格品質檢查清單:[功能名稱] **目的**:在進行規劃之前驗證規格的完整性和品質 **建立日期**:[日期] **功能**:[連結到 spec.md] ## 內容品質 - [ ] 沒有實作細節(語言、框架、API) - [ ] 專注於使用者價值和商業需求 - [ ] 為非技術利益相關者撰寫 - [ ] 所有強制性章節已完成 ## 需求完整性 - [ ] 沒有遺留 [NEEDS CLARIFICATION] 標記 - [ ] 需求是可測試且無歧義的 - [ ] 成功標準是可衡量的 - [ ] 成功標準是與技術無關的(沒有實作細節) - [ ] 所有驗收情境均已定義 - [ ] 已識別邊緣案例 - [ ] 範圍有明確界限 - [ ] 已識別依賴關係和假設 ## 功能就緒狀態 - [ ] 所有功能需求都有明確的驗收標準 - [ ] 使用者情境涵蓋主要流程 - [ ] 功能滿足成功標準中定義的可衡量結果 - [ ] 沒有實作細節洩漏到規格中 ## 備註 - 標記為不完整的項目需要在 `/speckit-clarify` 或 `/speckit-plan` 之前更新規格b. 執行驗證檢查:針對每個檢查清單項目審查規格:
- 對於每個項目,確定其通過或失敗。
- 記錄發現的具體問題(引用相關的規格章節)。
c. 處理驗證結果:
-
如果所有項目都通過:將檢查清單標記為完成,並繼續執行「強制性執行後鉤子」章節。
-
如果項目失敗(不包括 [NEEDS CLARIFICATION]):
- 列出失敗的項目和具體問題。
- 更新規格以解決每個問題。
- 重新執行驗證,直到所有項目都通過(最多 3 次迭代)。
- 如果 3 次迭代後仍然失敗,將剩餘問題記錄在檢查清單備註中並警告使用者。
-
如果 [NEEDS CLARIFICATION] 標記仍然存在:
-
從規格中提取所有 [NEEDS CLARIFICATION:...] 標記。
-
限制檢查:如果存在超過 3 個標記,只保留 3 個最關鍵的(按範圍/安全性/UX 影響),並對其餘部分做出有根據的猜測。
-
對於每個需要的釐清(最多 3 個),以以下格式向使用者呈現選項:
## 問題 [N]:[主題] **上下文**:[引用相關規格章節] **我們需要知道的是**:[來自 NEEDS CLARIFICATION 標記的具體問題] **建議答案**: | 選項 | 答案 | 影響 | |--------|--------|--------------| | A | [第一個建議答案] | [這對功能意味著什麼] | | B | [第二個建議答案] | [這對功能意味著什麼] | | C | [第三個建議答案] | [這對功能意味著什麼] | | 自訂 | 提供您自己的答案 | [解釋如何提供自訂輸入] | **您的選擇**: _[等待使用者回應]_ -
關鍵 - 表格格式:確保 Markdown 表格格式正確:
- 使用一致的間距,對齊管道符。
- 每個儲存格兩側應有空格:
| 內容 |而不是|內容|。 - 標題分隔符必須至少有三個破折號:
|--------|。 - 在 Markdown 預覽中測試表格是否正確呈現。
-
按順序為問題編號(Q1、Q2、Q3 - 總共最多 3 個)。
-
在等待回應之前一起呈現所有問題。
-
等待使用者回應他們對所有問題的選擇(例如,「Q1:A,Q2:自訂 - [詳細資訊],Q3:B」)。
-
透過將每個 [NEEDS CLARIFICATION] 標記替換為使用者選擇或提供的答案來更新規格。
-
在所有釐清解決後重新執行驗證。
-
d. 更新檢查清單:在每次驗證迭代後,使用當前的通過/失敗狀態更新檢查清單檔案。
強制性執行後鉤子
在向使用者報告完成之前,您必須完成此章節。
檢查專案根目錄中是否存在 .specify/extensions.yml。
- 如果不存在,或者
hooks.after_specify下沒有註冊鉤子,則跳轉到完成報告。 - 如果存在,讀取它並查找
hooks.after_specify鍵下的條目。 - 如果無法解析 YAML 或 YAML 無效,不要跳過:告訴使用者無法讀取
.specify/extensions.yml(包含解析器錯誤),並且包括任何在此註冊的強制(optional: false)鉤子在內的所有鉤子都未被檢查,然後繼續執行完成報告。 - 過濾掉
enabled被明確設為false的鉤子。將沒有enabled欄位的鉤子視為預設啟用。 - 對於其餘的每個鉤子,不要嘗試解釋或評估鉤子的
condition表達式:- 如果鉤子沒有
condition欄位,或者它為 null/空,則將該鉤子視為可執行。 - 如果鉤子定義了非空的
condition,則跳過該鉤子,將條件評估留給 HookExecutor 實作。
- 如果鉤子沒有
- 在從鉤子命令名稱建構命令調用時,將點(
.)替換為連字符(-)。例如,speckit.git.commit→/speckit-git-commit。 - 對於每個可執行的鉤子,根據其
optional標記輸出以下內容:- 強制鉤子(
optional: false)— 您必須為每個強制鉤子發出EXECUTE_COMMAND::
在發出上述區塊之後,您必須實際調用該鉤子並等待其完成,然後再繼續。## 擴充鉤子 **自動鉤子**:{extension} 正在執行:`/{command}` EXECUTE_COMMAND:{command} 在繼續到完成報告之前,請等待鉤子命令的結果。 - 可選鉤子(
optional: true):
不要執行可選鉤子;只需通知使用者即可。## 擴充鉤子 **可選鉤子**:{extension} 命令:`/{command}` 描述:{description} 提示:{prompt} 要執行:`/{command}`
- 強制鉤子(
完成報告
向使用者輸出以下內容:
## 功能規格已建立
**功能**:{feature-short-name}
**規格目錄**:{specify-feature-directory}
**規格檔案**:{spec-file-path}
**檢查清單**:{checklist-path}
### 需要釐清
如果有 [NEEDS CLARIFICATION] 標記:
詢問使用者上述問題(Q1、Q2...),並等待回覆。
如果沒有:
無。
### 下一步
使用 `/speckit-plan` 從此規格產生規劃。
如果使用了 branch_numbering,並發出了棄用警告,請在訊息中將其重複給使用者。