---
# System prepended metadata

title: 在 Claude Code 裡玩轉 GitHub Spec Kit：一場規格驅動開發的探索之旅

---

# 在 Claude Code 裡玩轉 GitHub Spec Kit：一場規格驅動開發的探索之旅

前幾天在 GitHub 上閒逛，看到一個有趣的專案叫 Spec Kit。標題寫著「Spec-Driven Development」，規格驅動開發？這概念聽起來挺新鮮的。我一直覺得寫程式就像蓋房子，先畫設計圖再動工總比邊蓋邊改來得靠譜。既然 GitHub 官方都推出這個工具了，那肯定有它的道理，不如就來試試看吧。

剛好我最近都在用 Claude Code 這個 AI 助手寫程式，想說直接在這個環境裡安裝應該挺方便的。結果呢，過程倒是遇到了一些小插曲，不過最後還是順利搞定了。這篇文章就來分享一下這段探索之旅，順便聊聊我對這種開發方式的一些想法。

![規格驅動開發概念圖](https://hackmd.io/_uploads/rynsPmU6xx.jpg)

## Spec Kit 到底是什麼東西？

說實話，剛看到「規格驅動開發」這個詞的時候，我還真不太確定它跟 TDD（測試驅動開發）或 BDD（行為驅動開發）有什麼不一樣。後來查了一下資料才發現，原來 GitHub 推出這個工具是想解決一個很實際的問題：AI 寫程式雖然快，但常常會「理解偏差」。

你有沒有過這種經驗？跟 AI 說「幫我做個登入功能」，結果它給你寫了一堆程式碼，但跟你想的不太一樣。可能你想要的是 OAuth 登入，它卻給你做了傳統的帳號密碼。或者你想要簡單一點的介面，它卻搞得很複雜。這就是所謂的「vibe coding」問題，憑感覺寫程式，結果常常不如預期。

Spec Kit 的想法很簡單：在 AI 開始寫程式之前，先把需求講清楚。就像蓋房子一定要先有設計圖一樣，你不會跟建築師說「蓋個漂亮的房子」就讓他開始動工吧？你得先說清楚要幾個房間、什麼風格、預算多少，對吧？

根據 GitHub 官方部落格的說法，這個工具支援各種 AI 編碼助手，包括 GitHub Copilot、Claude Code、Gemini CLI 等等。它會引導你經過幾個階段：

1. **Constitution（建立原則）** - 確立專案的核心理念和限制
2. **Specification（詳細規格）** - 把需求寫清楚，越詳細越好
3. **Plan（技術規劃）** - 決定用什麼技術、怎麼實作
4. **Tasks（任務分解）** - 把大工程拆成小任務
5. **Implementation（開始實作）** - AI 才真正開始寫程式

這個流程聽起來挺嚴謹的，但實際上會不會太繁瑣呢？這得等我真的用過才知道。

## 開始安裝：先裝個 uv

Spec Kit 的安裝需要用到一個叫 `uv` 的工具。欸，這又是什麼東西？原來這是 Astral 公司開發的 Python 套件管理工具，用 Rust 寫的，號稱速度超快。

以前用 Python 的人都知道，`pip` 安裝套件有時候慢得要命，特別是依賴關係複雜的時候。`uv` 就是要來解決這個問題的。根據他們官方的說法，速度可以快 10 到 100 倍。聽起來有點誇張，但既然 Spec Kit 選用它，應該是真的有兩把刷子。

安裝 `uv` 很簡單，就一行指令：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

執行之後，幾秒鐘就裝好了。終端機顯示：

```
installing to /Users/oliver/.local/bin
  uv
  uvx
everything's installed!
```

看到 `everything's installed!` 的時候還挺開心的，第一步很順利嘛。不過後面有個警告說 `uv` 和 `uvx` 被 PATH 裡的其他指令覆蓋了。我猜是因為之前就裝過，所以暫時先不管它，反正能用就好。

## 安裝 Spec Kit：第一次踢到鐵板

有了 `uv` 之後，就可以開始裝 Spec Kit 了。根據官方文件，有兩種安裝方式：

1. 持久安裝：用 `uv tool install` 裝在系統裡，之後隨時可以用
2. 一次性使用：用 `uvx` 執行，用完就消失

我想說既然要認真試試看，那就裝個持久版本吧：

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

這次安裝過程稍微久一點，畢竟要從 GitHub 下載原始碼然後編譯。看著終端機跑了一堆訊息：

```
Resolved 20 packages in 483ms
   Building specify-cli @ git+https://github.com/github/spec-kit.git
      Built specify-cli...
Installed 20 packages in 11ms
```

看到這裡我想說，11 毫秒安裝 20 個套件？這速度也太扯了吧。難怪人家說 `uv` 快。

裝好之後，當然要來初始化一個專案試試看。我打了這個指令：

```bash
specify init blog-project
```

結果呢，終端機跳出了一個選單，要我選擇要用哪個 AI 助手。畫面顯示了各種選項：copilot、claude、gemini、cursor 等等。看起來是要我用方向鍵選擇，然後按 Enter 確認。

問題來了。

在 Claude Code 這個環境裡，互動式選單根本沒辦法用。終端機直接噴了一大堆錯誤訊息：

```
error: (19, 'Operation not supported by device')
```

啊，原來是這樣。Claude Code 是個 AI 助手環境，不是真正的互動式終端機。它可以執行指令、看結果，但沒辦法用鍵盤上下鍵選東西。這種限制以前也遇過，只是沒想到在這裡又碰上了。

## 解決問題：查文件找答案

遇到問題怎麼辦？當然是看 help 啊。我執行了：

```bash
specify init --help
```

這次終端機乖乖地顯示了完整的使用說明。我仔細看了一下參數列表，果然找到解決方案：

```
--ai TEXT  AI assistant to use: claude, gemini, copilot, cursor...
```

原來可以直接用 `--ai` 參數指定要用哪個助手，不用經過互動式選單。這就好辦了！

我重新執行指令，這次加上參數：

```bash
specify init blog-project --ai claude
```

這次終端機顯示了一個漂亮的進度畫面，而且還有 ASCII 藝術字：

```
███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔════╝╚██╗ ██╔╝
███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝
╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝
███████║██║     ███████╗╚██████╗██║██║        ██║
╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝

         GitHub Spec Kit - Spec-Driven Development Toolkit
```

看到這個我就知道成功了。後面接著顯示初始化的各個步驟：

```
Initialize Specify Project
├── ● Check required tools (ok)
├── ● Select AI assistant (claude)
├── ● Fetch latest release (release v0.0.58)
├── ● Download template
├── ● Extract template
├── ● Ensure scripts executable
├── ● Initialize git repository
└── ● Finalize (project ready)

Project ready.
```

每一步都打勾通過，最後顯示 `Project ready.`，這感覺真好。就像玩遊戲解完一個任務一樣，有種成就感。

![規格驅動開發流程圖](https://hackmd.io/_uploads/ry9qDXU6xx.jpg)

## 探索功能：斜線命令系統

安裝完成後，Spec Kit 給了一堆說明。最引人注目的是它提供的斜線命令系統。這讓我想到遊戲裡的快捷指令，打個 `/help` 就能看到所有可用功能，很直覺。

核心工作流程有五個命令：

1. **`/speckit.constitution`** - 建立專案的核心原則
2. **`/speckit.specify`** - 撰寫詳細規格
3. **`/speckit.plan`** - 規劃技術架構
4. **`/speckit.tasks`** - 產生任務清單
5. **`/speckit.implement`** - 開始實作

除了這些核心命令，還有一些選用的增強功能：

- **`/speckit.clarify`** - 在規劃前先釐清模糊的需求
- **`/speckit.analyze`** - 檢查各個文件之間的一致性
- **`/speckit.checklist`** - 產生品質檢查清單

這個設計挺聰明的。核心流程很清楚，但如果你想要更嚴謹一點，可以加上那些選用功能。就像寫文章一樣，基本的起承轉合一定要有，但要不要加個引言、加個註解，就看你的需求了。

不過 Spec Kit 也很貼心地提醒了一件事：`.claude/` 資料夾可能會存放一些敏感資訊，像是認證 token 之類的，建議加到 `.gitignore` 裡面。這個提醒很重要，不然一不小心把私密資料推上 GitHub 就糗大了。

## 實際感受：這種開發方式適合誰？

裝完 Spec Kit 之後，我還沒真正用它做過完整的專案，但從這個安裝過程和文件說明來看，我覺得這個工具有幾個有趣的地方。

首先，它強迫你在寫程式之前先想清楚。這聽起來很理所當然，但實際上有多少人（包括我自己）是邊寫邊想的？特別是用 AI 寫程式的時候，很容易就陷入「試試看這樣寫會不會 work」的循環。Spec Kit 的流程讓你慢下來，先把需求講清楚。

其次，它提供了一個結構化的思考框架。Constitution、Specification、Plan、Tasks 這幾個階段，其實就是在幫你釐清：「我為什麼要做這個？」「我要做什麼？」「我要怎麼做？」「具體步驟是什麼？」這種思考方式不只適用於寫程式，做任何專案都能用。

不過說實話，我也有點擔心它會不會太繁瑣。如果只是寫個小工具、做個簡單的功能，需要經過這麼多步驟嗎？可能對於大型專案、需要多人協作的情況，這種嚴謹的流程才真正發揮價值。

還有一個有趣的觀察：在 Claude Code 這種 AI 助手環境裡使用 Spec Kit，某種程度上是「AI 幫你用 AI」。你用 Claude 執行 Spec Kit 的指令，然後 Spec Kit 又引導 Claude 按照規格寫程式。這種雙層 AI 協作的方式還挺新鮮的，不知道實際用起來會是什麼感覺。

## 一些技術細節的補充

在安裝過程中，我也學到了一些有趣的技術知識。

**關於 uv 這個工具**：它不只是快而已。根據 Astral 官方的說法，uv 的野心是成為「Python 的 Cargo」（Cargo 是 Rust 的套件管理工具，公認做得很好）。它不只能裝套件，還能管理 Python 版本、建立虛擬環境、發布套件，基本上想成為 Python 開發的一站式解決方案。

**關於互動式命令行的限制**：這次遇到的問題其實滿有啟發性的。很多命令行工具都會用互動式選單，看起來很友善，但在某些環境下（像是 CI/CD、Docker 容器、或者像 Claude Code 這種 AI 助手）就會碰壁。好的工具應該同時提供互動式和非互動式兩種使用方式，Spec Kit 就做到了這點。

**關於斜線命令**：這個概念其實不算新，Discord、Slack 這些工具早就在用了。但把它應用到開發工作流程上，讓 AI 助手能夠理解和執行這些結構化的命令，這個想法很聰明。它把複雜的操作包裝成簡單的指令，降低了使用門檻。

## 接下來想試試看的

雖然目前只是把 Spec Kit 裝起來，還沒真正用它做過完整專案，但我已經有一些想法想要實驗：

1. 用它來重構一個現有的小專案，看看「補寫規格」的過程是什麼感覺
2. 試試看那些選用的增強功能，像是 `clarify` 和 `analyze`，看看它們能不能真的提升品質
3. 比較一下用 Spec Kit 和不用 Spec Kit，開發同樣功能的時間和品質差異

有機會的話，再來寫一篇實戰經驗分享。

## 寫在最後

這次安裝 Spec Kit 的過程，讓我對「規格驅動開發」這個概念有了初步的認識。雖然過程中遇到了互動式選單的小問題，但也因此學到了一些東西。

回想起來，這個經驗讓我想到一句話：「工具只是工具，重要的是思考方式。」Spec Kit 提供了一個結構化的框架，但它不能代替你思考。你還是得自己想清楚要做什麼、為什麼做、怎麼做。它只是幫你把這些思考過程記錄下來，讓 AI 能更準確地理解你的意圖。

如果你也在用 AI 寫程式，也常常遇到「寫出來的跟想的不一樣」的問題，或許可以試試看 Spec Kit。它可能不是萬靈丹，但至少提供了一個值得嘗試的方向。

記得，如果你也是用 Claude Code 或類似的 AI 助手環境，遇到互動式選單的時候，先看看有沒有參數可以用。這個小技巧可以省下不少時間。

祝你探索愉快。

---

**參考資源**

- [GitHub Spec Kit 官方 Repository](https://github.com/github/spec-kit)
- [GitHub 官方部落格：Spec-driven development with AI](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
- [uv 官方文件](https://docs.astral.sh/uv/)
- [Astral 關於 uv 的介紹文章](https://astral.sh/blog/uv)