AgentSkillsCN

speckit

依照 speckit 的標準工作流程，引導式地產生規格文件、澄清需求、產生實作計劃與任務清單，每個階段都需要人工審核確認

中文原作
SKILL.md
--- frontmatter
name: speckit
description: 依照 speckit 的標準工作流程，引導式地產生規格文件、澄清需求、產生實作計劃與任務清單，每個階段都需要人工審核確認

Speckit

這個 skill 提供一個引導式的工作流程，協助你從功能描述開始，階段性地產生完整的 specification、計劃和任務清單。每個階段完成後都會停下來等待你的審核確認，確保品質符合預期後才進入下一階段。

核心功能

  • •引導式執行 speckit 的標準工作流程
  • •每個階段都有強制性的人工審核點
  • •提供清晰的品質檢查清單
  • •支援審核不通過時的修正機制
  • •在每個階段提供詳細的進度報告

工作流程總覽

code
1. Specify → [審核] → (不通過: Clarify) → [再審核]
                   ↓ (通過)
2. Plan    → [審核] → (不通過: 修正)
                   ↓ (通過)
3. Tasks   → [審核] → (不通過: 修正/分析)
                   ↓ (通過)
              (可選) TasksToIssues → 建立 GitHub Issues
                   ↓
4. Implement (包含多個子任務循環)

若我問流程為何，或是在哪個階段時，請應用這個流程圖讓我理解。

輸入參數

當使用者調用此 skill 時，應提供以下資訊：

必要參數

  • •階段選擇：
    • •specify：產生功能規格文件
    • •clarify：澄清規格中的模糊需求（僅在 specify 審核不通過時使用）
    • •plan：產生實作計劃
    • •tasks：產生實作任務清單
    • •taskstoissues：將任務清單轉換為 GitHub Issues（可選）
    • •implement：執行實作任務

條件參數

根據選擇的階段，需要提供不同的資訊：

  • •

    specify 階段：

    • •功能描述（必要）：自然語言描述的功能需求
  • •

    clarify 階段：

    • •Feature 名稱（必要）：要澄清的 feature branch 名稱
  • •

    plan / tasks / taskstoissues / implement 階段：

    • •Feature 名稱（必要）：要處理的 feature branch 名稱

資訊確認

依上下文取得下列相關資訊：

  • •GitHub repo 資訊。例如：MilesChou/claude-spec-kit-plugin
  • •GitHub MCP。確認工具有安裝即可

若無法取得資訊，請詢問我。

重要提醒

IMPORTANT：

使用腳本或讀取檔案的時候，請依下面對應的流程進行。

使用 .specify/scripts/ 裡的腳本

指令可能會提示要使用 .specify/scripts 裡的腳本，遇到時，改使用 Skill 的 scripts 目錄裡下對應的 prompt。

例如：在執行 specify 指令時，會呼叫 .specify/scripts/bash/create-new-feature.sh，這時要改使用 script/create-new-feature.md 並依裡面的提示執行任務。

例外：當呼叫 update-agent-context.sh 的時候，直接跳過不執行。

讀取 ./memory/constitution.md

指令可能會提示要讀取 ./memory/constitution.md，遇到時，請以下面步驟確認：

  1. •如果 Project Knowledge 或對話中有上傳 constitution.md 檔案，使用該檔案
  2. •如果透過 GitHub MCP 讀取 remote HEAD branch 有 memory/constitution.md，使用該檔案
  3. •如果都找不到，就使用 speckit skill 內建的 memory/constitution.md 檔案

讀取 .specify/templates/ 相關樣版

每個指令可能會提示要讀取 .specify/templates/ 相關樣版，總共有五種如下：

  • •agent-file-template.md
  • •checklist-template.md
  • •plan-template.md
  • •spec-template.md
  • •tasks-template.md

大概就是 [類型]-template.md。遇到時，請以下面步驟確認：

  1. •如果 Project Knowledge 或對話中有上傳 [類型]-template.md 檔案，使用該檔案內容
  2. •如果透過 GitHub MCP 讀取 remote HEAD branch 有 .specify/templates/[類型]-template.md，使用該檔案內容
  3. •如果都找不到，使用 speckit 內建的 templates/[類型]-template.md 內容

執行步驟

階段 1：Specify

目的是產生初始化規格

步驟 1.1：初始化與驗證

  1. •

    驗證功能描述是否完整

    • •如果功能描述為空，要求使用者提供
    • •檢查描述是否足夠清楚以產生規格
  2. •

    檢查專案環境

    • •檢查必要的 templates 是否存在
    • •確認 specs/features/ 目錄結構

步驟 1.2：產生規格文件

  1. •

    執行功能等同於 speckit.specify command

    • •產生 feature branch 的 short name
    • •載入 templates/spec-template.md
    • •根據功能描述產生初始規格
  2. •

    建立品質檢查清單

    • •自動建立 specs/<branch-name>/checklists/requirements.md
    • •驗證規格完整性
    • •標記 [NEEDS CLARIFICATION] 項目

步驟 1.3：報告並等待審核 ⚠️

STOP HERE - 必須等待使用者審核

報告內容：

  1. •Feature branch 名稱
  2. •規格檔案路徑：specs/features/<branch-name>/spec.md
  3. •品質檢查結果：
    • •✅ 已完成的檢查項目
    • •⚠️ 需要澄清的項目
    • •❌ 未通過的檢查項目

詢問使用者：

code
規格文件已產生，請審核以下內容：
- 功能描述是否完整？
- 使用者故事是否清楚？
- 驗收條件是否明確？
- 是否有需要澄清的部分？

請選擇：
1. ✅ 審核通過，繼續產生 Plan
2. 🔄 需要澄清 (Clarify)，請說明需要澄清的問題
3. ❌ 需要修改，請說明修改建議

階段 2：Clarify（澄清需求）

此階段僅在 Specify 審核不通過時執行

步驟 2.1：載入當前規格

  1. •

    讀取 feature 的規格檔案

    • •路徑：specs/features/<branch-name>/spec.md
  2. •

    分析規格的模糊性

    • •掃描各個類別的完整度
    • •識別 [NEEDS CLARIFICATION] 標記
    • •產生優先級排序的澄清問題（最多 5 個）

步驟 2.2：互動式澄清

  1. •

    逐一提出問題

    • •對於選擇題，提供推薦選項
    • •收集使用者回答
  2. •

    整合澄清結果

    • •在規格中建立 ## Clarifications 區段
    • •將澄清結果更新到相關區段
    • •儲存更新後的規格

步驟 2.3：報告澄清成果並再次審核 ⚠️

STOP HERE - 必須再次等待使用者審核

報告內容：

  1. •提出的問題數量
  2. •更新的區段清單
  3. •覆蓋率摘要表

詢問使用者：

code
需求澄清已完成，請再次審核規格：
- 澄清的內容是否符合預期？
- 是否還有其他需要澄清的部分？

請選擇：
1. ✅ 審核通過，繼續產生 Plan
2. 🔄 需要再次澄清
3. ❌ 需要修改規格

階段 3：Plan（產生實作計劃）

前置條件：Specify 階段已審核通過

步驟 3.1：設定計劃環境

  1. •

    解析路徑

    • •FEATURE_SPEC：specs/features/<branch-name>/spec.md
    • •IMPL_PLAN：specs/features/<branch-name>/plan.md
  2. •

    載入上下文

    • •讀取 FEATURE_SPEC
    • •讀取 ./memory/constitution.md（如果存在）

步驟 3.2：Phase 0 - 研究與探索

  1. •

    識別技術選型的未知項

    • •框架選擇
    • •架構模式
    • •第三方整合
  2. •

    產生研究文件

    • •建立 research.md 記錄決策依據

步驟 3.3：Phase 1 - 設計與合約

  1. •

    從規格中提取實體

    • •產生 data-model.md
  2. •

    從功能需求產生 API 合約

    • •建立 /contracts/ 目錄
    • •產生各個 API 的合約檔案
  3. •

    產生快速開始指南

    • •建立 quickstart.md
  4. •

    更新 agent context

    • •更新相關的 context 檔案

步驟 3.4：報告並等待審核 ⚠️

STOP HERE - 必須等待使用者審核

報告內容：

  1. •Branch 名稱
  2. •IMPL_PLAN 路徑
  3. •產生的 artifacts 清單：
    • •plan.md
    • •research.md
    • •data-model.md
    • •contracts/
    • •quickstart.md

詢問使用者：

code
實作計劃已產生，請審核以下內容：
- 技術選型是否合適？
- 架構設計是否完整？
- 資料模型是否正確？
- API 合約是否清楚？

請選擇：
1. ✅ 審核通過，繼續產生 Tasks
2. ❌ 需要修改，請說明修改建議

階段 4：Tasks（產生任務清單）

前置條件：Plan 階段已審核通過

步驟 4.1：設定任務環境

  1. •

    取得 FEATURE_DIR

    • •路徑：specs/features/<branch-name>/
  2. •

    取得 AVAILABLE_DOCS

    • •列出所有可用的設計文件

步驟 4.2：載入設計文件

  1. •

    必要文件：

    • •plan.md（技術棧、架構）
    • •spec.md（使用者故事、優先級）
  2. •

    可選文件：

    • •data-model.md
    • •contracts/
    • •research.md

步驟 4.3：產生任務清單

  1. •

    使用 ./templates/tasks-template.md 作為結構

  2. •

    依使用者故事組織任務

    • •建立依賴關係圖
    • •識別可平行執行的任務
  3. •

    任務組織：

    • •Phase 1: Setup（專案初始化）
    • •Phase 2: Foundational（基礎建設）
    • •Phase 3+: User Stories（依優先級）
    • •Final Phase: Polish（收尾工作）

步驟 4.4：報告並等待審核 ⚠️

STOP HERE - 必須等待使用者審核

報告內容：

  1. •tasks.md 路徑
  2. •總任務數量
  3. •每個使用者故事的任務數
  4. •平行執行機會
  5. •預估工作量

詢問使用者：

code
任務清單已產生，請審核以下內容：
- 任務分解是否合理？
- 依賴關係是否正確？
- 優先級排序是否適當？
- 是否有遺漏的任務？

請選擇：
1. ✅ 審核通過，開始 Implement
2. 📋 將任務轉換為 GitHub Issues（TasksToIssues）
3. 🔄 需要分析任務（Analyze tasks）
4. ❌ 需要修改，請說明修改建議

階段 4.5：TasksToIssues（轉換為 GitHub Issues）

此階段為可選，適用於需要團隊協作的專案

前置條件：

  • •Tasks 階段已審核通過
  • •Git remote 為 GitHub repository
  • •已安裝並配置 GitHub MCP server

步驟 4.5.1：環境檢查

  1. •

    驗證 Git remote URL

    • •執行 git config --get remote.origin.url
    • •確認是 GitHub URL（格式：https://github.com/<owner>/<repo>.git 或 git@github.com:<owner>/<repo>.git）
    • •如果不是 GitHub URL，終止此階段並警告使用者
  2. •

    驗證 GitHub MCP 工具可用性

    • •確認 github/github-mcp-server/issue_write 工具可用
    • •如果工具不可用，提示使用者安裝配置

步驟 4.5.2：讀取任務清單

  1. •

    執行前置檢查腳本

    • •取得 FEATURE_DIR 和 tasks.md 路徑
  2. •

    解析 tasks.md 內容

    • •提取所有任務項目
    • •識別任務的依賴關係
    • •保留任務的優先級順序

步驟 4.5.3：建立 GitHub Issues

  1. •

    從 Git remote URL 解析 repository 資訊

    • •提取 owner 和 repo name
  2. •

    為每個任務建立對應的 GitHub Issue

    • •Issue 標題：任務名稱
    • •Issue 內容：
      • •任務描述
      • •依賴關係（如有）
      • •所屬的使用者故事
      • •驗收條件
    • •Issue 標籤：根據任務類型自動添加（如：setup, feature, bug, documentation）
  3. •

    記錄建立結果

    • •成功建立的 issues 清單
    • •Issue 編號與任務的對應關係

步驟 4.5.4：報告並確認 ⚠️

STOP HERE - 必須等待使用者確認

報告內容：

  1. •Repository 資訊：<owner>/<repo>
  2. •建立的 Issue 總數
  3. •Issue 清單（編號 + 標題）
  4. •Issue URLs

詢問使用者：

code
已成功在 <owner>/<repo> 建立 X 個 GitHub Issues：

[列出所有 Issue 的編號、標題和 URL]

請選擇：
1. ✅ 確認無誤，開始 Implement
2. 📝 查看 Issues 後再決定
3. ⏸️ 暫停，之後再處理

階段 5：Implement（執行實作）

前置條件：Tasks 階段已審核通過

步驟 5.1：分析任務（Analyze Tasks）

  1. •

    讀取 tasks.md

  2. •

    識別當前可執行的任務

    • •檢查依賴關係
    • •列出無依賴的任務（可立即開始）
  3. •

    提供任務選擇

    • •顯示任務清單
    • •詢問使用者要執行哪個任務

步驟 5.2：執行單一任務

對於每個選中的任務：

  1. •

    實作

    • •根據任務描述編寫程式碼
    • •遵循 plan.md 中的架構設計
    • •參考 contracts/ 中的 API 規格
  2. •

    測試

    • •編寫或更新測試案例
    • •執行相關測試
    • •確保測試通過
  3. •

    驗證

    • •檢查是否符合驗收條件
    • •執行程式碼品質檢查
    • •確認沒有引入新的問題

步驟 5.3：更新任務狀態

  1. •

    標記任務為完成

    • •在 tasks.md 中更新狀態
  2. •

    記錄實作細節

    • •更新相關文件
    • •記錄技術決策

步驟 5.4：報告並詢問下一步 ⚠️

STOP HERE - 每個任務完成後都要停止

報告內容：

  1. •完成的任務名稱
  2. •修改的檔案清單
  3. •測試結果
  4. •剩餘任務數量

詢問使用者：

code
任務已完成，請檢視實作結果。

剩餘任務：X 個

請選擇：
1. ✅ 繼續下一個任務
2. 🔄 修正當前任務的問題
3. 📊 查看整體進度
4. ⏸️ 暫停實作

步驟 5.5：最終審核與驗證 ⚠️

當所有任務都完成後

  1. •執行完整測試套件
  2. •執行程式碼品質檢查
  3. •驗證所有驗收條件
  4. •產生實作報告

報告內容：

  1. •完成的功能清單
  2. •測試覆蓋率
  3. •程式碼品質指標
  4. •已知問題清單（如有）

詢問使用者：

code
所有任務已完成，請進行最終審核：
- 功能是否符合規格？
- 測試是否充分？
- 程式碼品質是否達標？
- 是否有需要修正的問題？

請選擇：
1. ✅ 審核通過，準備合併
2. 🔄 需要修正問題
3. 📝 需要補充文件

輸出結果

根據執行的階段，會產生以下檔案：

Specify 階段輸出

  • •specs/features/<branch-name>/spec.md：功能規格文件
  • •specs/features/<branch-name>/checklists/requirements.md：規格品質檢查清單

Clarify 階段輸出

  • •更新 spec.md，新增 ## Clarifications 區段

Plan 階段輸出

  • •specs/features/<branch-name>/plan.md：實作計劃
  • •specs/features/<branch-name>/research.md：技術研究與決策
  • •specs/features/<branch-name>/data-model.md：資料模型
  • •specs/features/<branch-name>/contracts/：API 合約檔案
  • •specs/features/<branch-name>/quickstart.md：快速開始指南

Tasks 階段輸出

  • •specs/features/<branch-name>/tasks.md：可執行的任務清單

TasksToIssues 階段輸出

  • •在 GitHub repository 中建立的 Issues
  • •Issue 編號與任務的對應關係（記錄在終端輸出中）

Implement 階段輸出

  • •實際的程式碼檔案
  • •測試檔案
  • •更新的文件
  • •更新的 tasks.md（標記完成狀態）

使用範例

範例 1：開始新功能（Specify）

code
使用者：請使用 speckit，我要開發一個使用者認證系統，支援 email/password 登入和社群媒體登入。

階段：specify
功能描述：建立一個使用者認證系統，支援 email/password 登入和社群媒體登入。

預期流程：

  1. •產生 spec.md 和 checklists/requirements.md
  2. •停止並等待審核
  3. •使用者審核後決定：通過 → Plan / 澄清 → Clarify / 修改 → 重新 Specify

範例 2：澄清規格（Clarify）

code
使用者：我審核後發現有些部分不夠清楚，請幫我澄清。

階段：clarify
Feature 名稱：user-authentication

預期流程：

  1. •載入 spec.md
  2. •分析並提出澄清問題
  3. •收集使用者回答
  4. •更新 spec.md
  5. •停止並等待再次審核

範例 3：產生計劃（Plan）

code
使用者：規格審核通過，請產生實作計劃。

階段：plan
Feature 名稱：user-authentication

預期流程：

  1. •產生 plan.md、research.md、data-model.md、contracts/
  2. •停止並等待審核

範例 4：產生任務（Tasks）

code
使用者：計劃審核通過，請產生任務清單。

階段：tasks
Feature 名稱：user-authentication

預期流程：

  1. •產生 tasks.md
  2. •停止並等待審核

範例 5：轉換為 GitHub Issues（TasksToIssues）

code
使用者：任務清單審核通過，請將任務轉換為 GitHub Issues。

階段：taskstoissues
Feature 名稱：user-authentication

預期流程：

  1. •檢查 Git remote 是否為 GitHub
  2. •驗證 GitHub MCP 工具可用性
  3. •解析 tasks.md 內容
  4. •為每個任務建立對應的 GitHub Issue
  5. •停止並報告建立結果

範例 6：執行實作（Implement）

code
使用者：任務清單審核通過，開始實作。

階段：implement
Feature 名稱：user-authentication

預期流程：

  1. •分析任務，列出可執行的任務
  2. •使用者選擇要執行的任務
  3. •執行單一任務（實作 → 測試 → 驗證）
  4. •停止並詢問下一步
  5. •重複 2-4 直到所有任務完成
  6. •最終審核

注意事項

審核點的重要性 ⚠️

  • •每個階段都必須停下來等待使用者審核
  • •不可自動跳過任何審核點
  • •審核不通過時，必須先修正問題才能繼續
  • •這是確保品質的關鍵機制

互動式處理

  • •Clarify 階段會需要使用者回答問題
  • •Implement 階段會需要使用者選擇任務
  • •每個問題都會提供推薦答案
  • •使用者可以接受推薦或自行提供答案

檔案管理

  • •所有檔案會建立在 feature branch 的專屬目錄中
  • •路徑格式：specs/features/<branch-name>/
  • •不會覆蓋現有檔案（除非明確要求）
  • •建議使用版本控制追蹤變更

錯誤處理

  • •如果規格驗證失敗，會嘗試自動修正（最多 3 次）
  • •如果仍有問題，會記錄在 checklist notes 並警告使用者
  • •任何階段失敗都會中止流程並報告錯誤
  • •使用者可以選擇修正後重試

最佳實踐

  1. •

    功能描述越詳細越好

    • •清楚說明使用者需求
    • •提供具體的使用場景
    • •說明預期的成果
  2. •

    認真對待每個審核點

    • •仔細檢視產生的文件
    • •確認是否符合預期
    • •不要急於通過審核
  3. •

    善用澄清階段

    • •對於模糊的需求，不要跳過澄清
    • •仔細思考推薦答案的影響
    • •必要時提供自訂答案
  4. •

    循序漸進地實作

    • •一次只執行一個任務
    • •確保每個任務都經過測試
    • •保持程式碼品質
  5. •

    保持文件同步

    • •實作時如發現設計問題，及時更新文件
    • •記錄重要的技術決策
    • •維護文件的準確性

重要提醒

  • •IMPORTANT: Think in English, but generate responses in Traditional Chinese (思考以英語進行，回應以繁體中文生成)
  • •CRITICAL: 每個階段完成後都必須停下來等待使用者審核，不可自動進入下一階段
  • •CRITICAL: 使用者未明確表示通過審核前，不可進行下一階段