# Spec Kit實作記錄

[hackmd連結](https://hackmd.io/@shaoeChen/rJ0wY4OCxe)

Spec Kit的出現似乎讓vibe coding的未來出現一絲光明，即使這名詞的發明者，AI大神Andrej Karpathy，最近也出來說明這並[不可行](https://www.managertoday.com.tw/articles/view/71103?)，但是對於一些簡單的專案來說應該還是有幫助才是。

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

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

## 最新心得
最近利用SDD的概念開發一個工作日誌系統，心得上就是，這實在是很花費時間，也許就如不少大神說的，這真的是陷入MARKDOWN地獄，還不如一個功能好好的說明讓AGENT開發。

實作過程中有發現，即使有TASK LIST，AGENT還是會在沒有完成的情況下勾選完成，這過程也確實是很花時間的在DEBUG，而且為了遵守流程，可能還需要回頭從`specify`或是`task`來重新執行。

上下文的部份，也許我們可以更依賴`AGENTS.md`(https://agents.md/)或是COPILOT本身所自帶的`instruction`、`prompt`。

當然也有可能是因為我是在"微軟大戰程式碼"(vscode)中使用的，導致SDD的效能沒有辦法被完整的釋放，改天有機會再來試著在COPILOT CLI上執行看看，也許會有不一樣的感受才是。

技術債會累積，即使使用SDD仍然會有相同的問題，不過也有可能是我不會使用，不一定是Spec Kit所造成的就是。

## 步驟
[官方連結](https://github.com/github/spec-kit)

在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`）以指定當前工作的功能。<br>**注意：** 在使用 `/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`，並於提示詞中明確說明

- 目前的迭代為 `003-xxx`，測試於`specs`中加入 `004-xxx` 的空資料夾，然後再執行`/speckit.specify`，系統會判定目前的執行版本為`004`，然後從`005`開始
- 雖然很廢話，不過我還是很好奇的測試了一下就是，即使我在提示詞中很直接的說明目前為`004-xxx`，系統仍然是從`005-`來建置
### 開發工具從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 頁面](https://github.com/github/spec-kit) 下載針對特定 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
當初使用`speckit`開發的工作日誌系統準備進版，所以要來嚐試更新一下`speckit`，相關操作就記錄在這邊。

首先，怎麼安裝就怎麼更新：

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

Installed 1 package in 99ms
 - specify-cli==0.0.18 (from git+https://github.com/github/spec-kit.git@ec782979f003eb1d969d56769f8bae2ed80a436f)
 + specify-cli==0.0.22 (from git+https://github.com/github/spec-kit.git@9111699cd27879e3e6301651a03e502ecb6dd65d)

然後更新現有專案的內容，這一步執行之前我有先把`constitution.md`，也就是憲章的部份複製一份：

specify init . --here --force

:::warning
注意：這相當於初始化的動作，強制蓋版，憲章的部份一定要先複製一份。
:::

接下來的操作流程都還是跟原本的一樣。

## 相關資源
- [官方文件](https://github.com/github/spec-kit)
- [speckit 流程圖](https://github-production-user-asset-6210df.s3.amazonaws.com/105573924/496883771-0138fda2-babd-45c7-9797-c16474ea0ac8.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAVCODYLSA53PQK4ZA%2F20251027%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20251027T050241Z&X-Amz-Expires=300&X-Amz-Signature=2282bb862dff42e03e69de788b55ff7fe1c863224827b4f2c33bf11eec8620f3&X-Amz-SignedHeaders=host)