# Gemini 說明 ## 指令說明 這些指令構成一個稱為 "SpecKit" 的工作流程，旨在引導使用者從一個模糊的想法，逐步走向一個結構清晰、可執行的開發計畫。 --- 1. speckit.specify.md - (想法 -> 規格) * 功用: 將您用自然語言描述的一個功能想法，轉換成一份結構化的規格文件 (`spec.md`)。 * 流程: 您提供功能的描述後，此指令會自動建立一個新的 Git 分支，並根據範本填寫規格文件的各個章節，如使用者故事、功能需求、成功標準等 。如果描述中有不明確之處，它會標記出來並向您提問以進行澄清。 2. speckit.clarify.md - (澄清規格) * 功用: 透過提問來消除 spec.md (規格文件) 中的模糊地帶。 * 流程: 它會掃描規格文件，找出定義不清或遺漏的部分，然後向您提出最多 5 個目標明確的問題（通常是選擇題或簡答題）。在您回答後，它會自動將澄清後的資訊寫回 spec.md 文件中，從而提高規格的明確性。 3. speckit.plan.md - (規格 -> 計畫) * 功用: 根據 spec.md (規格) 來產生技術規劃與設計文件。 * 流程: 它會建立一份 plan.md 檔案，在其中定義技術棧、架構，並識別出需要進一步研究的未知問題。接著，它會產出更詳細的設計文件，例如 data-model.md (資料模型)、API 合約等，為後續的任務拆解和實作做好準備。 4. speckit.tasks.md - (計畫 -> 任務) * 功用: 根據 plan.md (計畫) 和 spec.md (規格) 等設計文件，自動產生一份可執行的、詳細的任務清單 (`tasks.md`)。 * 流程: 這份清單會將所有開發工作拆解成具體的小任務（例如：建立某個檔案、撰寫某個函式），並安排好它們的執行順序與相依性。一個關鍵特 點是任務會圍繞著「使用者故事」來組織，以便可以一個故事一個故事地獨立開發和測試。 5. speckit.implement.md - (執行任務) * 功用: 實際執行開發任務。 * 流程: 它會讀取 tasks.md (任務清單) 中定義的所有工作項目，並按照規劃的階段和相依順序來執行它們。在開始前，它會先檢查相關的 checklist 是否都已完成。執行過程中，它會遵循 TDD (測試驅動開發) 的原則（如果有的話），並在完成任務後將其標記為完成。 --- 輔助與品質保證指令： 6. speckit.analyze.md - (分析產出) * 功用: 分析 spec.md (規格)、plan.md (計畫) 和 tasks.md (任務) 這三個核心文件，找出它們之間不一致、重複、模糊不清或規格不足的地方。 * 流程: 它是一個唯讀操作，只會產生一份分析報告，並不會修改任何檔案。報告會對問題進行嚴重性分級，並提供後續建議。 7. speckit.checklist.md - (產生檢查清單) * 功用: 產生一份客製化的檢查清單，用來「測試需求規格本身寫得好不好」。 * 核心概念: 它的核心概念是把檢查清單當成「需求的單元測試」，專注於驗證需求是否完整、清晰、一致且可衡量，而不是用來測試最終的程式碼 功能。例如，它會問「'快速載入'是否有量化指標？」，而不是「驗證載入速度很快」。 8. speckit.constitution.md - (管理專案原則) * 功用: 建立或更新專案的「憲法」檔案 (`.specify/memory/constitution.md`)。 * 流程: 這個檔案定義了專案的核心原則與不可動搖的規則。此指令會處理原則的增修、版本號的更新，並確保專案中其他相關的範本檔案（如計畫 、規格範本）與新的憲法保持同步。 ---- ## 使用範例 > 從無到有開始一個專案的話（例如一個 todo list 工具製做），我要一步步準備哪些文件，用哪些指令來進行 使用 SpecKit 這套流程，從零到有建立一個專案（例如一個 CLI 待辦事項工具）會非常有條理。 ✦ 以下是您需要遵循的步驟、對應的指令，以及每一步會產生的文件。 事前準備 (一次性設定) 在開始第一個功能之前，可以先為整個專案建立「憲法」，定義共同的開發原則。 * 指令: /speckit.constitution * 目的: 建立或修改 .specify/memory/constitution.md 檔案。這能確保整個專案（包括 AI）在開發時遵循一致的最高原則，例如「優先考慮安全性」、「所有 API 都必須有文件」等。對於新專案，這一步可以幫助奠定基礎。 --- 標準開發流程 (一步步來) 假設您要做的專案是「一個簡單的 CLI 待辦事項 (To-do list) 工具」。 第 1 步：定義您的想法 (Specify) 您需要做的就是用一句話或一段話描述您想要的功能。 * 您的輸入: 1 /speckit.specify 我想做一個簡單的待辦事項 CLI 工具，讓使用者可以新增、查看、完成和刪除待辦事項。資料可以先存在一個 JSON 檔案裡。 * 產生的主要文件: spec.md (規格文件) * 內容: 這份文件會將您的想法轉化為結構化的內容，包含： * 使用者故事: "作為一個使用者，我希望能新增一個待辦事項..." * 功能需求: "系統必須提供 add 指令..." * 成功標準: "使用者能在 5 秒內完成新增事項的操作。" 第 2 步：澄清模糊之處 (Clarify) AI 在第一步產生的 spec.md 可能有些地方不夠明確。這一步就是用來解決這些問題。 * 指令: /speckit.clarify * 目的: AI 會主動閱讀 spec.md，找出模糊點並向您提問。 * 互動範例: AI 可能會問： * "待辦事項完成後，應該直接刪除，還是標記為『已完成』狀態？" * "當查看所有待辦事項時，是否需要按照特定順序（如新增時間）排序？" * 產生的主要文件: 更新後的 spec.md。您的回答會被記錄下來，讓規格更完整。 第 3 步：規劃技術細節 (Plan) 有了清晰的規格後，現在要規劃「如何」實現它。 * 指令: /speckit.plan * 目的: 決定技術棧、資料結構、檔案架構等。 * 互動: 您可以提供偏好，例如「請用 Python 開發」。如果沒提供，AI 會根據專案類型推薦（例如 CLI 工具推薦 Python 或 Go）。 * 產生的主要文件: * plan.md: 技術藍圖，說明將使用哪些技術和架構。 * data-model.md: 定義「待辦事項」這個資料物件長什麼樣子（例如：有 id, title, status 三個欄位）。 第 4 步：產生開發任務 (Tasks) 這是將宏觀的計畫分解成微觀、可執行的步驟。 * 指令: /speckit.tasks * 目的: 產生一份給開發者（或 AI）看的詳細施工清單。 * 產生的主要文件: tasks.md (任務清單) * 內容: 這份文件會非常詳細，例如： * T001: 建立專案目錄結構與 main.py 檔案。 * T002: 在 main.py 中，使用 argparse 函式庫設定 'add', 'list', 'done', 'delete' 四個子指令。 * T003: 實作讀取與寫入 todo.json 檔案的輔助函式。 * ... 等等 第 5 步：開始實作 (Implement) 萬事俱備，只欠東風。現在，讓 AI 開始寫程式。 * 指令: /speckit.implement * 目的: AI 會嚴格按照 tasks.md 的指示，一步一步完成所有開發任務。 * 產生的主要文件: 專案的原始碼 (例如 main.py, utils.py, todo.json 等)。 --- 總結 整個流程和產出的文件鏈是： 1. 您: 「我想要一個 To-do List 工具。」 * -> `/speckit.specify` -> spec.md (要做什麼) 2. AI: 「『完成』是指刪除嗎？」 * -> `/speckit.clarify` -> 更新後的 spec.md (把事情講清楚) 3. 您/AI: 「我們用 Python 來做吧。」 * -> `/speckit.plan` -> plan.md, data-model.md (要怎麼做) 4. AI: 「這是詳細的施工步驟。」 * -> `/speckit.tasks` -> tasks.md (一步步教我怎麼做) 5. AI: 「好的，我開工了。」 * -> `/speckit.implement` -> 專案原始碼 這個流程能確保最終產出的專案最大程度地符合您的初始想法，同時過程清晰、有條理，並減少了來回溝通的成本。 ---- ## 現有專案 > 我可不可以把這些流程用在現有的專案裡， speckit 可以自動分析專案內容來產生 spec 文件嗎？ ✦ 這兩個都是非常好的問題。讓我分開來回答： 1. 我可以把這些流程用在現有的專案裡嗎？ 絕對可以。 事實上，這正是 SpecKit 流程的一個主要用途：為一個已經存在的專案有條理地新增功能。 流程幾乎完全一樣，但 AI 在執行時會更加關注「與現有程式碼的整合」： 1. `/speckit.specify`: 您像平常一樣描述您想新增的功能。例如：「我想在現有的 To-do List 工具中，增加一個『設定優先級』的功能。」 2. `/speckit.clarify`: 流程不變，澄清新功能的模糊之處。 3. `/speckit.plan`: (關鍵區別) 在這一步，AI 會先使用工具 (read_file, glob 等) 去分析您現有的專案架構、程式碼風格和慣例。然後，它會規劃出一個能無縫整合到現有專案的技術方案，而不是從零開始。 4. `/speckit.tasks`: 產生的任務清單會包含修改現有檔案或新增檔案的具體步驟。例如，任務可能會是「修改 todo_item.py 類別，增加 priority 屬性」或「在 cli.py 中新增 --priority 參數」。 5. `/speckit.implement`: AI 會根據任務清單，精確地修改或新增相關檔案來完成新功能。 所以，結論是：可以，而且非常適合。 您只需要專注於描述「新功能」，AI 會負責處理與舊有專案的整合問題。 --- 2. Speckit 可以自動分析專案內容來產生 spec 文件嗎？ 這個問題可以理解為「逆向工程」：從現有的程式碼反向推導出規格文件 (spec.md)。 這裡的答案比較微妙： * 沒有一個專門的 `speckit` 指令可以做到這件事。 speckit.specify 指令的設計是從「自然語言描述」到「規格」，而不是從「程式碼」到「規格」。 * 但是，作為一個 AI 助理，我可以為您完成這項任務。 這不是一個預設好的 speckit 自動化流程，而是需要我動用我的核心能力來達成。如果您提出這個要求，我的處理步驟會是： 1. 接收指令: 您可以對我說：「請幫我分析這個現有的專案，並為它產生一份 spec.md 文件。」 2. 分析程式碼: 我會使用 glob 和 read_many_files 等工具，讀取您專案中的所有相關原始碼。 3. 理解功能: 我會分析程式碼的邏輯、API 端點、UI 介面和資料結構，來理解這個專案「到底在做什麼」。 4. 撰寫規格: 基於我的理解，我會模擬 speckit.specify 的過程，將我從程式碼中「讀懂」的功能，以使用者故事和功能需求的形式，撰寫成一份完整的 spec.md 文件。 總結 * 為現有專案增加新功能：可以，這是 SpecKit 的標準用法。 * 為現有專案反向生成規格文件：沒有一鍵完成的指令，但您可以直接要求我這麼做，我會手動（以 AI 的角度）為您分析並產生文件。 ---- # Claude 說明 ## SpecKit 指令功能簡介 speckit.analyze.md - 跨檔案分析工具 用於檢測 spec.md、plan.md、tasks.md 三個核心文件之間的一致性問題，包括重複、歧義、覆蓋率缺口等，並產生分析報告以確保實作前的品質。 speckit.checklist.md - 需求品質檢核清單生成器為當前功能生成客製化檢核清單，專門驗證需求文件的完整性、清晰度、一致性等品質面向，就像是「英文寫作的單元測試」。 speckit.clarify.md - 規格說明澄清工具 透過最多5個有針對性的澄清問題，識別並減少功能規格中的模糊之處或缺失的決策點，並將澄清結果直接寫回規格檔案。 speckit.constitution.md - 專案憲章管理工具 建立或更新專案憲章檔案，包含專案原則、治理規則等，並確保相關範本檔案保持同步。 speckit.implement.md - 實作執行引擎 根據 tasks.md 中定義的任務計畫執行完整的功能實作，包含檢核清單狀態檢查、階段性執行、進度追蹤等。 speckit.plan.md - 實作規劃工作流程 使用規劃範本產生設計文件，包含技術研究、資料模型、合約定義等設計產出物的生成。 speckit.specify.md - 功能規格建立器 從自然語言的功能描述建立或更新功能規格文件，包含需求分析、使用者情境、成功準則等完整規格定義。 speckit.tasks.md - 任務分解產生器 基於可用的設計文件產生可執行的、有依賴順序的任務清單，按照使用者故事組織並包含並行執行策略。 ## 產生步驟 > 從無到有開始一個專案的話（例如一個 todo list 工具製做），我要一步步準備哪些文件，用哪些指令來進行 步驟1: 建立專案憲章 /speckit.constitution 定義專案的核心原則、開發標準和治理規則。 步驟2: 撰寫功能規格 /speckit.specify 我要做一個個人用的 todo list 工具，可以新增、編輯、刪除待辦事項，支援分類和優先級設定，有簡潔的網頁介面 這會建立功能分支並產生完整的 spec.md 規格文件。 步驟3: 澄清模糊需求（可選） /speckit.clarify 如果規格中有 [NEEDS CLARIFICATION] 標記，用此指令進行澄清。 步驟4: 建立實作規劃 /speckit.plan 產生技術規劃，包含： - research.md（技術研究） - data-model.md（資料模型） - contracts/（API 合約） - plan.md（實作計畫） 步驟5: 產生任務清單 /speckit.tasks 基於規劃文件產生詳細的 tasks.md 執行任務清單。 步驟6: 品質檢核（建議） /speckit.checklist ux /speckit.checklist api /speckit.analyze 產生品質檢核清單並分析整體一致性。 步驟7: 開始實作 /speckit.implement 根據任務清單執行實際的程式開發。 整個流程會產生一個結構完整的專案，包含規格、設計、任務規劃和實作代碼。 ---- ## 現有專案 > 我可不可以把這些流程用在現有的專案裡， speckit 可以自動分析專案內容來產生 spec 文件嗎？ ● 從我看到的 speckit 指令檔案來看，目前的 speckit 並不支援自動分析現有專案來產生 spec 文件。 現有專案的限制 speckit 的設計思路是： - /speckit.specify 需要你提供功能描述作為輸入 - 它是從自然語言描述建立新的功能規格 - 並不會掃描現有程式碼來反向工程出規格 建議的現有專案流程 如果要在現有專案使用 speckit，你可以： 方案1: 手動描述現有功能 /speckit.specify 這是一個現有的 [描述你的專案功能，例如：音樂播放器，支援播放列表管理、音樂搜尋、用戶收藏等功能] 方案2: 逐功能建立規格 為現有專案的個別功能建立規格： /speckit.specify 為現有系統新增用戶權限管理功能，包含角色分配、權限控制等 方案3: 使用程式碼分析工具 你可能需要先用其他工具（如 code-archaeologist agent）分析現有程式碼： /code-archaeologist 分析這個專案的現有功能和架構 然後根據分析結果手動撰寫功能描述給 /speckit.specify。 總結 speckit 更適合新功能開發或為現有專案新增功能的情境，而不是反向工程現有程式碼。