實際使用 Spec-kit 建立簡單的專案
讓大家體驗 Spec-driven Development
🔽
speckit-playgroundgit clone https://github.com/chechiachang/speckit-playground.git
# 確認 uv 可用
uv --version
# 沒有的話安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安裝指定穩定版
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.9
[
{
"name": "Azure",
"vendor": "azure",
"apiKey": "${input:chat.lm.secret.-3df80c78}",
"models": [
{
"id": "gpt-5.4-nano",
"name": "Azure GPT-5.4 Nano",
"url": "https://chechia-ws.cognitiveservices.azure.com/openai/responses?api-version=2025-04-01-preview",
"toolCalling": true,
"vision": true,
"maxInputTokens": 272000,
"maxOutputTokens": 128000
}
]
}
]
workshop 重點在累積動手的經驗
本次 workshop 以 hands-on 為主，講解為輔。
還沒講什麼是 Spec-kit 之前，先讓大家實際體驗一次
🔽
/specify -> /plan -> /tasks -> /implement
# VS Code Terminal
specify init --here --integration copilot
Warning: Current directory is not empty (7 items)
Template files will be merged with existing content and may overwrite existing files
Do you want to continue? [y/N]: y
specify check
打開 .specify/templates 資料夾，看一下裡面的內容
在 Chat 中輸入 /spec 看看會發生什麼事
# 在 Chat 輸入指令，等待 copilot 生成憲法（Constitution）
# 今天 workshop LAB1 先用中文，比較好理解
/speckit.constitution 用zh-tw 專案建立憲法：規格從簡，程式簡潔，及早執行。
# 用英文 llm performance 會比較好，大概是 5-10% benchmark 提升（請見最後論文參考）
# 但如果英文會讓人類 performance 下降 10%，就請都用中文好了
# 看一下 .specify/memory/constitution.md 內容，是否滿意
# 如果不滿意，可以透過 chat 要求 copilot 修改，直到滿意為止
/speckit.constitution extreme compact constitution.
constitution 是 agent 的行為準則，會在每次 agent 行動時被參考
# 打開範例專案 example-ubike.md
# 如果你有準備其他題目，請用自己的題目
# agent 會產生 specs/001-branch-name/spec.md
# 清除之前的對話紀錄，讓 agent 從一個乾淨的狀態開始理解需求
/clear
/speckit.specify 建立一個單頁 Web 應用：台北市 YouBike 2.0 即時站點查詢器。
核心需求：
- 用 python + uv
- 自動從政府 API 抓取 JSON 站點資訊。https://tcgbusfs.blob.core.windows.net/dotapp/youbike/v2/youbike_immediate.json
- 搜尋框：可依據「站點地址」或「名稱」過濾。
- 列表呈現：站點名稱、可用車輛、剩餘空位。
# 其他需求可繼續補充
/speckit.specify ...
# 使用 clarify 檢查 Spec 是否有問題，或是有不清楚的地方
# 如果有，agent 會提出問題，讓你補充資訊
/speckit.clarify
SDD 要求 Spec 盡量接近最終需求，避免在實作過程中頻繁修改需求，導致返工成本增加
# 本 workshop 可以選擇 Auto Approve
# VSCode Copilot 已設定基本 System Instruction：只允許本 workspace 資料夾的存取
# （不允許存取本機其他目錄）
# 讓 agent 可以自動執行 cmd，不需要每次都問
Allow all commands in this session
# 或修改 settings.json 保留設定
# 檢視目前的 setting，放在 .vscode/settings.json
Allow running command `xxx` in this workspace
# 設定 auto-approve 的原則
# 允許 readonly: git, bash, grep, ...
# write 只允許特定工具，arguments 也要限制
# 根據 agent 控制力，以及失控的損害程度，決定 auto-approve
# 清除之前的對話紀錄，讓 agent 從一個乾淨的狀態開始讀取 plan.md & tasks.md
# 可以每一步都清除一次，或是 agent 行為不符合預期時再清除
# 特別是 model 能力不足時（例如使用 nano），更需要頻繁清除，避免 context rot
/clear
# 在 Chat 輸入 /speckit.plan，讓 agent 根據 spec 產生實作計畫
# 預期會產生 specs/001-branch-name/plan.md
/speckit.plan
# 在 Chat 輸入 /speckit.tasks，讓 agent 根據 plan 產生實作任務
# 預期會產生 specs/001-branch-name/tasks.md
/speckit.tasks
# 在 Chat 輸入 /speckit.analyze，讓 agent 分析 plan 與 tasks 是否合理，是否有衝突
/speckit.analyze
# 根據分析結果，修改 plan 或是 tasks
# 不清楚的部分會導致 agent 實作出來的東西不符合預期，不建議直接進入 implement
# 可以直接請 agent 自己嘗試修復問題
根據建議修復
# 有調整後記得再次分析，看有無問題遺留
/speckit.analyze
# 確認 Spec、Plan、Tasks 都合理了之後，就可以開始實作了
# Agent 開始寫扣
/speckit.implement
# 實作過程中，agent 會持續根據 tasks.md 來產生程式碼，並且標記完成的 task
# 檢視實作過程中產生的程式碼，看看是否符合預期
# Agent 可能會做到一個段落就停下來，等待你確認是否繼續
繼續
# 或是直接讓 agent 自動繼續，直到完成
繼續直到完成可執行
# 完成後直接問 Agent 如何執行
如何執行
# agent 會遇到困難卡住，或是有疑問，會在流程中問你
I can’t start implementing yet because the repo is currently on main, and Spec Kit requires a feature branch for this workflow.
# 檢視 agent 想要執行的 cmd，覺得合理的話選擇 allow
# 可以自己判斷或是再問 agent，或是直接叫 agent 自己決定
# 有些流程是 spec-kit 設定的，例如 Spec-Kit 會要求 branch name
Please create or switch to a feature branch for 001-youbike-station-search using one of these patterns:
# 可以使用 /speckit.git.feature 切換
/speckit.git.feature
# Spec-kit 的流程中，agent 會遇到流程錯誤，導致走不下去
# 沒有滿足 plan 與 task，就無法 implement
# 沒有滿足 feature branch name 就無法 implement
# 可以請 agent 講 zh-tw 說明為什麼卡住了，該如何解決
# 某些情形會需要額外的清理
# 例如開了多個 spec/001 spec/002 資料夾與多個 feature branch
# 這時候可以請 agent 幫忙清理，或是自己手動刪除
# 「請協助 git reset spec 內容並清除 feature branch」
# 持續 implement 直到完成
/speckit.implement
# 新增新的 spec，或是修改 spec 來提高驗收標準
/speckit.specify 需要測試覆蓋率達到 80%，並且所有 lint 與 style 都必須通過
Spec-kit 的流程中，agent 會遇到各種錯誤，例如程式碼錯誤、測試失敗、驗收不過等等
# 發現錯誤是 Spec，請回到修改 Spec，例如
/speckit.specify 改用xxx
/speckit.tasks
# 如果錯誤無關 Spec，例如程式碼錯誤，直接貼錯誤讓 agent 修正程式碼
# 例如發現網頁呈現不正確，直接把內容丟給 Chat agent
YouBike2.0_捷運科技大樓站
地址復興南路二段235號前
可用車輛0
剩餘空位0
# 或是
Error: xxx
# 提供驗證方法給 agent，讓 agent 可以自己驗證是否修正成功
# Spec-kit 會自動產生一些驗收需求，但需要人類去描述更精確的驗收需求
透過內建瀏覽器檢查網站內容
# 也可補充是否驗證要包含測試覆蓋率
/speckit.specify 需要測試覆蓋率達到 80%
避免 Context rot，drift，Spec drift
「誒我去年為何會這樣寫啊（問旁邊」
Vibe Coding 就是療癒
# Prices per 1M tokens.
┌──────────────┬────────┬────────┬─────────┬────────┬────────┬─────────┐
│ Model │ Short │ Short │ Short │ Long │ Long │ Long │
│ │ Input │ Cached │ Output │ Input │ Cached │ Output │
│ │ │ Input │ │ │ Input │ │
├──────────────┼────────┼────────┼─────────┼────────┼────────┼─────────┤
│ gpt-5.4 │ $2.50 │ $0.25 │ $15.00 │ $5.00 │ $0.50 │ $22.50 │
│ gpt-5.4-mini │ $0.75 │ $0.075 │ $4.50 │ - │ - │ - │
│ gpt-5.4-nano │ $0.20 │ $0.02 │ $1.25 │ - │ - │ - │
│ gpt-5.4-pro │ $30.00 │ - │ $180.00 │ $60.00 │ - │ $270.00 │
└──────────────┴────────┴────────┴─────────┴────────┴────────┴─────────┘
# 只有 gpt-5.4 時，Spec-kit 請用 mini 或 nano
# Spec-kit 的核心流程（specify, plan, tasks）對於模型的能力要求不高
# 使用 mini 或 nano 就能達到 90% 的效果，但成本只有 10-20%，非常划算
90%+ 的 Coding/Tool-calling/Intelligence50%下午歡迎參考
喜歡這種內容歡迎來找我聊天