Spec Kit實作記錄

hackmd連結

Spec Kit的出現似乎讓vibe coding的未來出現一絲光明，即使這名詞的發明者，AI大神Andrej Karpathy，最近也出來說明這並不可行，但是對於一些簡單的專案來說應該還是有幫助才是。

我個人仍然是認為，寫程式重視底韻，你必需要有一定的知識才能有辦法去驅動人工智慧，不然你根本連AI在幹嘛都不知道，仔細想想，這是很恐怖的一件事。

也許你認為在什麼都不懂的情況下可以用自然語言的方式生成一個網頁或是應用程式非常潮，但是在沒有一定知識的情況下你也只知道就是生成一個你想像中的結果，這個結果有沒有什麼安全性的問題可能連自己都是一問三不知了。

步驟

官方連結

在Spec-Kit的官方說明中明確的列出幾個指令，簡單易懂，就跟叫叫ABC一樣，其中Essential Commands是過程中必需執行的指令，而Optional Commands是過程中你可以選擇要不要執行的指令。

我看保哥在一個公開談話中的demo是在specify階段中直接給定PRD文件，這部份當然也是可以另外利用LLM來生成。

🧭 Essential Commands

指令	說明
/speckit.constitution	建立或更新專案的治理原則與開發指導方針
/speckit.specify	定義你想要建構的內容（需求與使用者故事）
/speckit.plan	依據選定的技術棧建立技術實作計畫
/speckit.tasks	產生可執行的實作任務清單
/speckit.implement	依照計畫執行所有任務，完成功能建置

🧩 Optional Commands

指令	說明
/speckit.clarify	釐清未明確定義的部分（建議在 /speckit.plan 之前執行；原名 /quizme）
/speckit.analyze	進行跨產物一致性與覆蓋度分析（建議在 /speckit.tasks 之後、/speckit.implement 之前執行）
/speckit.checklist	生成自訂品質檢查清單，驗證需求的完整性、清晰度與一致性（類似「英文單元測試」）

⚙️ Environment Variables

變數	說明
SPECIFY_FEATURE	用於非 Git 儲存庫的功能偵測覆蓋。設定為功能目錄名稱（例如：001-photo-albums）以指定當前工作的功能。 注意： 在使用 /speckit.plan 或後續指令前，必須於代理環境中設定此變數。

指令簡單說明

/speckit.constitution

在這階段主要定義整個專案過程中不可違逆，必需完全遵守的規則，像我會要求所有文件皆以正體中文書寫，開發過程必需遵守MVP(最小開發原則)

實作記錄

開發工具

我採用的測試開發工具是KILO CODE，然後首次儲值是10美金送20美金，搭配的模型是deepseek 3.2與claude haiku 4.5，一個便宜一個好用，主力是deepseek。

文件導讀工具

目前對於新的技術我的作法都是直接將所有文件利用notebookllm整理，自己會快速的看過一次，後續有問題就直接在notebookllm中詢問。

這樣做的好處在於問題不會發散也不會有所謂的幻覺出現，因為notebookllm的問題回應始終是根據你所給定的文件來回應。

問題記錄

:::warning
這邊的問題都是根據我收集在notebookllm中的資源回應所得，並不保證是正確的
:::

• 第一次的迭代完成之後，第二次執行/speckit.specify並沒有同步建立002-xxx分支，導致後續的執行皆在001-xx分支中執行，雖然發現這問題之後有嚐試設置SPECIFY_FEATURE，但是似乎沒有效果
  • 後續的處理方式是直接利用git branch建立對應的分支，然後git checkout過去該分支之後測試執行，確定相關文件的導讀都是從002-xxx

:::info
理論上在第二次執行/speckit.specify的時候會生成002-xxx的資料結構以及分支，這次的問題在於資料結構有生成，但是分支沒有生成，後續第三次執行的時候要特別確認。
:::

• 001-xxx執行完畢之後，如果要第二次迭代執行/speckit.specify，是否需要切回分支master
  • 建議是需要切回再做執行，並且記得要做合併分支

:::info

• 猜測第一次就是因為沒有切回master才會造成分支沒有成功切換為002-xxx

• 確認即使切回master再執行仍然不會生成分支，所以這部份必需要自己建立分支之後自己切換，不過不確定是不是kilo code才有這問題，後續可以再測試github copilot

• 調整為github copilot之後確認，使用copilot會自動切新分支，也許在kilo code上要有更明確的提示詞才會執行
  :::

• 第2次之後執行/speckit.specify，即使技術棧沒有調整仍然需要執行/speckit.plan

• /speckit.implement之後如果發現與task.md、plan.md上所述不同，那就要再重新執行一次/speckit.implement，並於提示詞中明確說明

開發工具從kilo code轉copilot

uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai copilot --script ps

:::warning

• 執行之後constitution.md也被重置，這部份要特別注意，也許是我的指令錯誤了
  :::

現有專案導入speckit

:::info
下面給出的是notebookllm的說明，後續再用現有的專案來測試看看
:::

這是一個非常好的問題，Spec Kit 的設計就是為了能夠導入既有的專案（在 SDD 術語中稱為 Brownfield 專案，即「遺留系統現代化」或「疊代增強」）。

將 Spec Kit 導入現有專案的關鍵在於使用正確的初始化命令，並確保您為 AI Agent 提供了足夠的專案上下文（Context）與原則（Constitution），讓它能理解既有程式碼庫的結構和約束。

以下是導入 Spec Kit 到現有專案的詳細步驟和注意事項：

---

步驟一：導入 Spec Kit 套件

Spec Kit 提供兩種主要方式在現有專案中初始化其骨架：

方法一：使用 Specify CLI 導入（推薦）

您需要使用 specify init 命令並加上 --here 旗標，這會指示 CLI 在當前目錄下初始化 Spec Kit 必要的檔案和資料夾，而不是創建一個新的專案資料夾。

1. 安裝 Specify CLI：如果您尚未安裝 uvx，請先安裝。

2. 在現有專案根目錄執行：

   uvx --from git+https://github.com/github/spec-kit.git specify init --here
   # 或使用句點：
   # uvx --from git+https://github.com/github/spec-kit.git specify init .
   

   您將被提示選擇要使用的 AI Agent（例如 Claude Code、GitHub Copilot 等）和腳本類型（sh 或 ps）。

方法二：手動下載與複製檔案

您可以直接從 Spec Kit 的 GitHub 儲存庫的 Release 頁面 下載針對特定 Agent 的模板壓縮包，然後手動解壓縮並將相關檔案放入您的專案根目錄。

• 複製內容：將包含 Agent 指令（例如 .github 提示或 .claude 提示）的資料夾和 .specify 資料夾（包含記憶體、腳本和模板）拖曳到您的專案根目錄中。

步驟二：建立專案憲章（Constitution）

這是導入現有專案中最關鍵的一步。由於 AI Agent 擅長模式補全，但不擅長讀心術，它需要明確的最高原則來理解現有專案的技術棧和架構。

您必須使用 /speckit.constitution 命令，來定義這些**不可協商（non-negotiable）**的原則。

• 用途：憲章（Constitution）會將 AI 模型鎖定在現有的技術棧、代碼品質標準或架構決策上。
• 內容範例：由於是現有專案，憲章應包含現有技術的約束，例如：「網站使用 Hugo 建構，不使用其他前端框架」、「所有 Web App 必須使用 Next.js 和 Postgress 資料庫」。
• Agent 參考：Agent 在規劃 (/plan) 階段會參考此憲章，以確保其技術計畫符合您已設定的約定。

步驟三：提供既有程式碼庫的上下文（Context Engineering）

您必須主動確保 Agent 能夠獲取足夠的上下文，以便在不破壞現有程式碼的情況下新增功能。

1. Agent 指令文件：許多 Agent（如 Copilot CLI）會讀取 agents.md 或類似的 Agent 檔案，您可以將專案的結構、元件定義和操作方式編碼到這些文件中，以便 LLM 理解組件關係和應在哪裡進行變更。
2. 動態上下文分析：現代 LLM 具備動態解析程式碼樹的能力，但提供主動上下文（Proactive Context）通常效果更好。Agent 在後續的 /speckit.plan 步驟中，也會嘗試解析專案結構（例如尋找 Hugo 配置文件或 Next.js 的檔案結構），並將其應用於新功能的開發。

步驟四：新增功能 (Iterative Enhancement)

一旦基礎設置完成，您就可以像對待全新（Greenfield）專案一樣，開始為現有專案新增功能。Spec Kit 在處理現有程式碼庫的功能新增時，展現了強大的威力。

1. 隔離開發：當您使用 /speckit.specify 命令時，Spec Kit 會自動在您的現有 Git 儲存庫中建立一個新的功能分支，將新功能的工作隔離起來，防止影響主分支的穩定性。
2. 規格化新增功能：針對您要新增的特定功能，運行標準的 SDD 流程：
   • /speckit.specify：定義要新增什麼 (What) 和為什麼 (Why)，專注於新功能如何與現有系統交互，不包含技術細節。
   • /speckit.clarify（可選）：幫助您發現關於新功能要求的盲點或定義不足（underspecification），尤其在複雜的既有程式碼庫中非常有用。
   • /speckit.plan：定義如何實作 (How)， Agent 會參考您在憲章中定義的既有技術棧（例如「使用 Next.js」），並根據新功能生成專屬的技術工件（如新的 API 介面或資料模型）。
   • /speckit.tasks：將計畫分解為可執行的任務，然後使用 /speckit.implement 進行實作。

總結：導入 Spec Kit 到現有專案的流程就是利用 specify init --here 進行初始化，然後利用 /speckit.constitution 來約束 AI Agent，使其遵循您現有專案的技術規則，最後透過結構化的 SDD 流程來疊代新增功能。

相關資源

• 官方文件
• speckit 流程圖