Spec Kit 把設定變成導引流程

Spec Kit 把專案設定變成一套可複製的 AI-agent 導引流程。

我用 AI coding assistant 已經夠久了，久到一看 setup 流程就知道哪裡會卡。通常都是這樣：工具裝好了、repo 也開了、模型看起來很勤奮，然後我開始當保母。它每次都很會接話，卻完全不知道這個專案現在在哪個狀態、有哪些規則、哪些決策已經定案。最後變成我一直補上下文，它只負責點頭。這種「很幫忙」的感覺，我其實很膩。

所以我看到 DeepWiki 的 Spec Kit getting started 時，第一個反應不是「哇好酷」，而是「終於有人不把 setup 當成一次性安裝」。Spec Kit 的做法很硬：先初始化，再走 spec、plan、tasks、implement，順序不能亂。它不是在討好你，它是在逼你先把專案講清楚。我反而覺得這比較像正常工作方式。

我也回頭對了 github/spec-kit 的原始倉庫、quickstart、installation，避免只吃 wiki 摘要。因為這種東西最怕被二手轉述轉到只剩漂亮話，真正有用的是它怎麼要求你在 repo 裡放哪些檔案、跑哪些指令、先做哪一步。

不要把 agent setup 當成裝完就能用

“The typical path from zero to a working project follows this sequence: Installation and Initialization.”

翻譯一下就是，Spec Kit 不認同「裝好」等於「可以開始亂問」。它把 setup 拆成兩段：先安裝 CLI，再在真正要工作的 repo 裡初始化。這聽起來很基本，但多數人其實都在偷懶，裝完工具就直接開聊，期待模型自己長出專案記憶。

我以前也幹過這種事。某個 side project 我一直覺得 agent 很鈍，後來才發現不是模型不行，是我根本沒給它專案級規則。每次開新 session，它都像第一次來這個世界，永遠從零開始猜。Spec Kit 的思路很直接：把專案本身變成上下文來源，不要把記憶責任丟給人腦。

實操上，我會把這件事拆成三個動作：先裝 CLI，再在 repo root 初始化，最後才讓 agent 進場。這不是儀式感，這是避免 workflow 一開始就散掉。你如果跳過初始化，後面那些 slash command、context file、scripts 都只是空名詞。

• 先安裝 CLI，不要先開 prompt。
• 在你真的要做事的 repo root 跑 init。
• 把 initialization 當成「讓專案變成 agent-aware」的步驟。

我現在看 setup flow，都會先問一句：這套流程有沒有把專案狀態寫進 repo？如果沒有，那大概又是個靠人肉補洞的設計。Spec Kit 至少不是這樣，它是把洞補在流程裡。

CLI 只是入口，不是你要一直依賴的東西

“Install the specify-cli command globally using uv or pipx.”

Spec Kit 先給你一個 CLI，因為 CLI 的工作不是陪你聊天，是把專案骨架寫進 repo。官方文件也明講，真正維護的來源是 github/spec-kit，不是你在 PyPI 上隨便看到的同名套件。這種提醒我很買單，因為包名撞車這種事在 Python 世界實在太常見，踩一次就知道痛。

白話一點說，CLI 是 scaffolding tool，不是產品本體。它負責把 agent 需要的檔案、模板、命令和腳本放好，然後你就回到 repo 裡面工作。文件提到 uv 和 pipx 都是正常安裝路徑，也有一次性 setup 的選項給不想永久安裝的人。這種設計比「請自行想辦法」好多了。

我喜歡這種分工，因為它讓 setup 很明確。工具如果會偷偷改 repo、偷偷跑背景流程，我會很煩。我要的是一個有名字的命令，跑下去後有可預期的結果，而不是某種神秘魔法。

實操寫法我會這樣抓：

• 先用官方路徑裝 CLI，別亂找同名包。
• 跑 specify version 或 specify check 確認環境正常。
• 如果是企業環境或離線環境，就照文件的 local wheel / one-time setup 走，不要自己拼。

很多文件都假裝大家機器乾淨、網路順、權限全開。現實不是。Spec Kit 至少有把這種情境考慮進去，這點我給過。

init 才是骨架真正冒出來的地方

“The init command sets up the necessary scaffolding for your chosen AI agent.”

這句話很重要，因為 specify init 不只是建資料夾，它會根據你選的 integration 去放對應檔案。DeepWiki 也有列出常見整合像 claude、copilot、gemini、codebuddy、pi、zed。而且舊的 --ai 旗標已經被 --integration 取代，這種細節很煩，但也很真實。

翻譯一下就是，Spec Kit 不想讓每個 agent 都變成你腦中的特例。你不用每次手刻 folder layout，不用自己猜這個工具讀哪個 context file。你選 integration，CLI 幫你把該放的東西放好。這種做法很像把「工具相容性」變成初始化責任，而不是把錯誤留到後面才爆。

我自己最有感的是，當你在不同 agent 之間切換時，差異不只在 prompt 語氣，而是檔案位置和命名規則真的不同。以前我常常拿同一套 prompt recipe 到處塞，然後怪模型表現不一致。後來才懂，是我自己在亂套模板，不是工具真的一樣。

實操上我會這樣做：

• 先選你真的會用的 integration，不要貪多。
• 優先用 --integration，別再碰被棄用的 --ai。
• 只有在你知道理由時才加 --no-git、--force 這類旗標。

重點不是背 flag，而是讓初始化產生一致的 baseline。這樣你後面才有東西可以檢查、可以修、可以交接。

Context file 不是附屬品，是 agent 的工作記憶

“Agent context files providing project metadata and instructions.”

Spec Kit 會生出像 CLAUDE.md、GEMINI.md 這種 context file，也會放對應的 command 目錄，例如 .claude/commands/ 或 .github/agents/。這些東西看起來很像附加檔，實際上是 model 在這個專案裡到底該怎麼做事的依據。

白話講，模型不是靠「看懂整個 codebase」就能自動知道規則。它需要一份穩定的指令集。這比你每次重新解釋架構、重講 conventions、重提邊界條件有效太多了。那種一直重講的感覺，就像你在幫一個失憶症同事做短期記憶外包，累的是你。

我以前很常遇到 agent 明明在 repo 裡，卻像沒進場。它能看到檔案，但不知道什麼重要、什麼只是歷史垃圾。context file 的價值，就是把「什麼是這個專案的規則」寫成固定資訊。它不會解決所有問題，但至少能少掉一大堆重複解釋。

實操寫法我會守三條：

• 先讀生成的 context file，再決定要不要改。
• 把新成員也需要知道的規則寫進去。
• 保持短，別寫成小說。

我很在意這點：context file 一旦長到像規格書，模型根本不會好好用。最好的文件通常都很無聊，因為它們只做一件事：讓 agent 不用猜。

工作流是階梯，不是「邊聊邊看」

“Constitution → Specify → Plan → Tasks → Implement”

這就是 Spec-Driven Development 的核心。它不是叫你一直聊天，聊到某天 code 自己冒出來。它要的是一串有順序的產物和命令：先用 /speckit.constitution 定義原則，再用 /speckit.specify 寫 feature spec，接著 plan、tasks，最後才 implement。DeepWiki 也把這些階段對應到像 .specify/memory/constitution.md、specs/NNN-feature/spec.md、plan.md、tasks.md 這些檔案。

也就是說，Spec Kit 想強迫你先講清楚再寫 code。不是哲學，是成本控制。因為一旦 code 先出現，人就會莫名其妙對它產生感情，明明 spec 還在糊，卻開始捨不得砍。這種情況我看太多了，最後常常是把錯誤實作養成技術負債。

我自己最喜歡這種流程的原因很簡單：它讓我有機會在最便宜的時候抓錯。spec 還沒定，改起來很便宜；code 都寫完了，改起來就開始付利息。Spec Kit 其實是在幫你把「先討論後實作」這件事流程化。

實操上可以這樣落地：

• 每個專案先跑 constitution，建立共同原則。
• 任何 feature 先寫 spec，不要先叫 agent 生 code。
• plan 和 tasks 要真的拿來管進度，不要只是裝飾文件。

如果你習慣 prompt-first，這套會讓你覺得慢。但我自己的經驗是，慢一點通常比較不會在第三輪才發現方向整個歪掉。

腳本才是把流程黏起來的真正骨架

“The automation scripts in .specify/scripts/ provide shared utilities to ensure consistency across the workflow.”

這段我反而最重視。Spec Kit 在 .specify/scripts/ 裡放了 bash 和 PowerShell 的輔助腳本，像 create-new-feature、check-prerequisites、update-agent-context。這代表它不是只給你 markdown 文件而已，它有把流程落地的執行層。

翻譯一下就是，這套方法論不是靠大家自覺。它靠腳本減少人為漂移。因為一旦流程只存在於文件裡，每個人都會有自己的解讀，最後專案會長成一堆不相容的版本。腳本至少能把共識鎖住，讓人跟 agent 都走同一條路。

我以前看過不少團隊想做 spec-driven，但只有文件沒有工具，結果就是每個人都說自己有照流程，實際上根本不是同一套。腳本的好處是，它讓「應該怎麼做」變成「真的可以執行」。這差很多。

實操寫法：

• 先確認你平台對應的腳本有沒有生成完整。
• 能用 helper script 就不要手動重做流程。
• 當 context 變動時，記得用提供的腳本刷新。

這種 refresh 機制很重要。流程最怕不是一開始沒做好，而是做一做就過期，然後大家還以為自己在同一個版本上工作。

先把 agent 放進 repo，再開始工作

“After initialization, launch your AI agent in the project directory.”

這句其實把前面所有東西串起來了。agent 不是先在外面開一個泛用 session，再丟進 repo。它應該直接在初始化過的專案目錄裡啟動，這樣它才能看到剛剛產生的 commands、context files、workflow artifacts。

白話講，目錄位置不是瑣事，是權限和可見性的問題。你如果在錯的地方開 agent，它看不到該看的東西，最後又會回到「我猜一下」的模式。然後你會覺得它不穩，其實只是你把它放錯場景。

我自己以前很常偷懶，直接在任意 session 裡貼路徑，期待它自己懂。結果通常都像帶觀光客逛工廠：看得到門口，看不到流程。後來我才改成先進 repo root，再讓 agent 開始做事，整個體感差很多。

實操上我會這樣檢查：

• 在 initialized repo root 打開 Claude Code、Copilot、Windsurf 或你自己的 agent。
• 確認它能看到 /speckit.* 這些命令。
• 所有 workflow 都從 repo root 跑，不要從臨時 scratch session 開始。

這就是差別：一邊是「我有個 AI 工具」，另一邊是「我有一套專案工作流」。前者很熱鬧，後者才真的能交付。

可抄的模板

# Spec Kit 起手式模板（可直接貼進新專案筆記或 README 草稿）

## 1. 安裝 CLI
# 擇一使用官方路徑
# uv tool install specify-cli
# pipx install specify-cli

specify version
specify check

## 2. 在 repo root 初始化
# 請在真正要工作的專案目錄執行
specify init --integration claude

# 其他整合範例：
# specify init --integration copilot
# specify init --integration gemini
# specify init --integration zed

## 3. 在初始化後的專案目錄啟動 agent
# 不要在外部泛用 session 裡硬塞路徑
# 直接從 repo root 開啟 AI agent

## 4. 依序走 spec-driven flow
/speckit.constitution
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

## 5. 每次變更後檢查這份清單
- [ ] CLI 來自官方 github/spec-kit
- [ ] init 在正確的 repo root 執行
- [ ] integration 選對了
- [ ] agent 是在專案目錄裡啟動的
- [ ] constitution 先寫，再談 feature
- [ ] spec、plan、tasks 都有產生
- [ ] 需要時用 helper scripts 更新 context

## 6. 預期會看到的檔案
- .specify/memory/constitution.md
- .specify/templates/
- .specify/scripts/
- specs/NNN-feature-name/spec.md
- specs/NNN-feature-name/plan.md
- specs/NNN-feature-name/tasks.md

## 7. 我自己的使用原則
- context file 要短、要明確、要能被模型真的讀進去
- 不要先寫 code 再補 spec
- 能用腳本就不要手動重做流程
- 把 setup 當成專案 onboarding，不是安裝完成就結束

如果我今天要新開一個 repo，我會直接拿這段當底稿。它不是花俏版本，但就是夠用，而且夠不容易走歪。這類工具最怕你把它玩成自由發揮，Spec Kit 的價值剛好相反：它逼你先把框架立住。

這篇的拆解主要來自 DeepWiki 的 getting-started 頁面，再對照 github/spec-kit、quickstart、installation。上面的中文整理、判讀和模板是我自己重新整理過的版本，不是原文照抄。