RaamPrashathT/spec-it

spec-it 是做什麼的？

將 $ARGUMENTS 轉換為一份規格，讓編碼代理無需追問即可據以建置，同時提供顯示每項需求與邊界情況的原型。

Idea → 1. Context (no questions) → 2. Product questions → 3. Technical questions
     → 4. REQUIREMENTS.md → 5. Mockups → 6. Check

類似 references/… 的路徑是相對於 ${CLAUDE_SKILL_DIR}。輸出會放到 spec-it/<kebab-name>/：

spec-it/<name>/
├── REQUIREMENTS.md      唯一的交付物：意圖、決策、階段、FR、EC、假設
└── mockups/             index.html + 畫面，或 api.html + openapi.yaml，或 cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

規則

1. 事實歸你，決策歸他們。 絕不詢問 repo、附加檔案、網路或標準就能回答的問題。絕不為開發者決定範疇、優先順序或取捨。
2. 每個問題都必須有其價值。 在提出每個問題前，先執行 references/questions.md 中的問題閘門。一個有合理標準預設值的細節，應視為假設 (A-n)，而不是一個問題。
3. 沒有配額。 沒有最低提問數。典型執行會問 5–12 個問題。當你能預測開發者的下一個答案時，就停止提問。
4. 透過選取器提問 (AskUserQuestion；不含它的純編號文字)。每次呼叫最多 3 個獨立的問題；絕不將選項依賴於另一個未回答問題的問題批次送出。
5. 每個問題只出現一次， 作為你訊息中的最後一件事。之後不再回顧。
6. 將狀態寫入磁碟。 在上下文步驟之後，將 REQUIREMENTS.md 作為工作檔案：先草擬第 1–2 節，在決策確定時填入。在上下文壓縮後，先重新讀取它再進行操作。
7. 原型可離線運作。 不使用 CDN、網路或網路字型。
8. 檢查腳本閘控完成： node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<name> 以狀態碼 0 退出。

ID：FR-n 需求，EC-n 邊界情況，D-n 決策，A-n 假設。使用模組時，FR/EC/A 會帶有模組前綴（BOOK-FR-3）。ID 是永久的：絕不重新編號；移除時使用 "(removed)"。

1. 上下文（尚未提問）

在問任何問題前先做這個。平行執行兩個查找，並在可用時使用全新上下文的子代理：

• 程式碼庫掃描（如果資料夾為空則跳過）：技術棧、與該想法重疊的現有功能、資料模型、驗證機制、UI 工具包與設計令牌、API 與 CLI 慣例、任何半成品的東西。最多回饋 25 行。
• 既有成果掃描（網路搜尋，2–4 次）：2–3 個既有產品或標準如何解決此問題；該領域已知的難題（實際使用中會出錯的地方）；標準功能集；任何相關規格（如 RFC、clig.dev、WCAG、支付或隱私規則）。最多回饋 25 行，並附上來源連結。

然後向開發者展示一份上下文摘要，最多 15 行：

我發現了什麼
- 程式碼庫：<此處觸及或重複使用的現有內容>
- 他人如何做：<產品 A 做了 X，產品 B 做了 Y>
- 此領域的難題：<2–4 項，例如缺席導致房間空置；週期性預訂>
- 我的解讀：<一句話假設，說明你想要什麼以及原因> · 信心度 <n>%

分類類型（UI、API、CLI、混合），並從 assets/requirements-template.md 建立 REQUIREMENTS.md，填入第 1 節和上下文區段。你找到的難題就是你最佳問題的素材。

2. 產品問題

閱讀 references/questions.md。從最不確定的風險開始：這是否是正確的問題，為誰服務，首先發布什麼，不包含什麼，然後是該領域的具體難題情境。每當一個答案確定時，將其記錄為 D-n 並放入 §決策 區段。

當以下三點都成立時，切換到技術問題：

• 你能用開發者自己的話寫出重述（成果、使用者、為什麼現在、成功標準、不包含範圍）；
• 第 1 階段的範疇和非目標已達成共識；
• 剩下的問題是關於 如何做，而不是 做什麼、為誰做、為什麼做。

例外：一個會改變範疇的硬性限制（「必須離線運作」、「重用我們 Auth0 的租戶」、「資料留在歐盟」）一旦出現就應立即詢問，因為它會重塑產品問題。

3. 技術問題

僅在分歧點提出：程式碼庫與標準無法解決，且答案會改變資料模型、合約或用戶可見行為的地方。列表在 references/questions.md § Technical。許多執行只需要 0–4 個。絕不詢問程式碼庫已固定的主機、CI、框架或供應商選擇。

確認閘門。 一條訊息：重述（6 行），然後是你所做的每個假設（A-n，一行一個，附上其預設值）。詢問：確認，或指出要更改的項目。將更改納入。只有在得到明確的「是」之後，才在規格的狀態行上寫 Status: Confirmed。

階段與模組

階段（總是考慮）。 由「首先發布什麼」這個產品問題決定。第 1 階段是使用者能端到端完成核心工作的最精簡部分（步行骨架）。如果開發者想要一次全部完成，則只有一個階段。每個 FR 都帶有 Phase: n。第 1 階段需完整定義；後續階段在 --next-phase 詳細描述之前，每個功能在 §交付計畫 中只需一個要點的 bullet。

模組（僅在有信號時）。 只有當一個領域符合兩個或以上條件時，才將其視為模組：不同的人或詞彙；擁有自己的資料；若單獨發布也有用；需要自己的一套 10 個以上問題。當有 2 個以上符合條件的領域時，問一次：一個規格包含模組區段 (推薦)，或者現在定義最重要的模組並概述其餘部分。永遠不要僅憑想法聽起來很大就推斷出模組。模組應留在同一個 REQUIREMENTS.md 中，作為 §功能需求 下的 ## 區段，並帶有 ID 前綴。

規模限制。 如果第 1 階段超過大約 25 個必須 FR 或 12 個原型成品，詢問哪些應移至第 2 階段。

4. 撰寫 REQUIREMENTS.md

填寫範本。每個 FR 都有一個 ID、優先順序、階段、Given/When/Then，以及 Source: 決策 ID；每個被提出的邊界情況都成為一個 EC-n，並附上具體的 fixture 值。FR 描述用戶能觀察到的內容；技術細節放在 §技術決策。然後根據此清單進行一次自我審查，並修正未通過的部分：

• 兩個無法同時成立的陳述；同一條規則被陳述兩次。
• 一個 FR 開發者可以用兩種不同方式建置（缺少限制、單位、角色或失敗行為）。
• 一個無法通過觀察判斷通過或失敗的標準，或一個沒有數字的不明確詞彙。
• 一個沒有 FR 的角色、實體或流程；一個沒有被任何東西引用的決策。
• 一個違反詞彙表中定義的用詞。

5. 原型

列出成品（畫面、端點群組或命令群組），最多 12 個，每個都包含其狀態，並將每個 EC 映射到一個狀態。在一條訊息中顯示該列表，除非開發者反對，否則直接進行。然後閱讀 references/screens.md（UI）或 references/api-cli.md（API、CLI）並建置：

1. 先撰寫 mockups/assets/fixtures.js：任何成品中顯示的每個名稱、ID、金額和日期。
2. UI：將設計方向寫入 §設計方向。如果程式碼庫已有設計系統或令牌，則遵循它並跳過設計問題；否則，用 ASCII 草圖作為選項預覽，問一個設計方向的問題。
3. 將 ${CLAUDE_SKILL_DIR}/assets/theme.css 和 app.js 複製到 mockups/assets/，設置令牌，並執行檢查直到對比度通過。
4. 根據 references/renderer.md 建置每個成品：如果有 4 個以上成品且可使用子代理工具，則每個成品平行使用一個子代理；否則在此處逐一建置。CLI：撰寫 mockups/transcripts.md，然後執行 node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<name>。
5. 從 ${CLAUDE_SKILL_DIR}/assets/index.html 填入 mockups/index.html。
6. 若 UI 有瀏覽器工具：可選擇執行 references/critic.md 並套用其頂層修復一次。

6. 檢查與報告

執行檢查腳本直到它以狀態碼 0 退出；將模糊性警告視為需要精煉措辭的提示。在最多 10 行內報告：路徑、計數（提出的問題、FR、EC、假設、成品）、檢查摘要行、如何檢視原型（打開 mockups/index.html，或執行 node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<name>），以及如果有的話，下一個階段。node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<name> 可依請求建立單一檔案副本以供分享。

後續執行

• --next-phase： 讀取規格，提取下一個階段的要點，僅對它們執行步驟 2–6（問題從第 1 階段留下的開放事項開始）。新的 FR 繼續編號；先前的 ID 永不改變。
• --revise（或一個變更請求）：記錄新的決策，更新受影響的 FR 和 EC，僅重新渲染受影響的成品，再次執行檢查。

合理化思考

想法	現實
「我應該涵蓋每個領域，所以我會問關於整合的問題。」	僅當答案會改變規格時才問。「第一版沒有」是一個假設。
「我會問他們想要哪個時間步長。」	存在標準預設值。記錄為 A-n；確認閘門會顯示它。
「這個想法很明確，跳過上下文步驟。」	上下文步驟是產生好問題的來源。總是執行它。
「這個想法聽起來很大，所以要有模組。」	模組需要信號，然後是開發者的選擇。
「他們接受了所有建議，太好了。」	建議可能過於安全。你的下一個問題應該是他們可能會不同意的。