前言

近兩年來，AI coding tools 變得隨處可見。無論是 GitHub Copilot、Claude Code 或各種 coding agent，都讓「說一句話就能生成程式碼」成為常見的工作方式。這些工具雖然便利，但在使用流程上仍有不少待改善之處。最明顯的問題是 AI 經常「忘記」先前的對話內容。可能前面才討論好某個設計方向，對話中途它就偏離軌道，生成出截然不同的程式碼。此外，生成的程式碼品質不夠穩定，表面看似正常，仔細檢查後卻發現存在安全漏洞或邏輯錯誤。相關研究也證實了這些問題的存在 [1], [2]。

雖然隨著模型持續改進，生成結果的品質也有所提升，但仍需要大量人工確認和驗證。開發者往往需要花費相當時間進行修改和驗證，有時甚至自己重寫還比較省時，這種情況下 AI 的協助反而增加了額外的工作負擔。無論採用 Prompt Engineering 或 Context Engineering 等技術來建立更穩定的協作方式，關鍵仍在於如何更清楚地表達需求，並建立結構化的工作流程，以提升 coding agent 的實際效益。

最近我接觸到 spec-kit 這個工具，它的核心概念是「規格驅動開發」。透過 /specify 指令將模糊的想法轉換成結構化的規格文件，再使用 /plan 指令制定明確的執行計劃。經過一段時間的實際使用，我發現 spec-kit 確實能夠改善與 AI 的協作品質。在這篇文章中，我想分享使用心得，以及這個工具如何幫助我建立更有效率的開發流程。

認識 spec-kit

spec-kit 是 GitHub 推出的開源工具包，核心理念是「規格驅動開發」（Specification-Driven Development, SDD）。與傳統開發模式不同，這種方法將規格文件作為開發的「唯一真相來源」，讓程式碼服務於規格，而非規格遷就程式碼。

spec-kit 提供三個主要指令來建立結構化的開發流程：

• /specify：將模糊的功能描述轉換成結構化的規格文件。這個指令會自動建立分支和文件，確保需求被完整記錄。規格文件包含專案目的、使用者體驗描述，以及核心功能的詳細說明。

• /plan ：根據規格文件產生實作計劃。它會將商業需求轉換成技術架構，定義技術棧、實作限制，並確保計劃與專案原則保持一致。

• /tasks：將實作計劃分解成可執行的具體任務。這些任務可以並行處理，並包含結構化的任務文件，讓開發團隊能夠按部就班地推進專案。

傳統的需求規格文件往往是靜態的，寫完後就被束之高閣，開發過程中逐漸與實際實作脫節。spec-kit 的規格文件則截然不同，它們是活的文件，能夠持續指導開發過程。這些規格文件不只是記錄，更是 AI coding agent 的直接輸入，確保生成的程式碼符合原始需求。當需求變更時，開發者可以直接修改規格文件，重新生成對應的計劃和程式碼，避免昂貴的重構成本。更重要的是，清晰的規格大幅降低了溝通成本，減少開發過程中的歧義，特別是在與 AI 工具協作時更顯重要。

在 Spec-driven development with AI: Get started with a new open source toolkit 中提到了 spec-kit 特別適合以下情境：

• 新專案開發：從零開始的專案能充分發揮規格驅動的優勢
• 功能擴展：為既有系統新增功能時，能確保新功能與整體架構的一致性
• 系統現代化：重構舊系統時，先建立清晰的規格再進行實作

這個工具的設計理念是讓開發者能夠專注於「要做什麼」的思考，而將「怎麼做」的細節交給 AI 來處理，從而提升開發效率和程式碼品質。

使用範例：Telegram Bookmark Bot

為了更具體地展示 spec-kit 的實際應用，我想分享一個最近開發的專案案例。這個專案的背景是我希望統一管理散落在各處的書籤：Twitter 收藏、Safari 書籤、偶然在聊天中分享的連結等等，都能集中存放到自架的 Linkding 書籤管理系統中。傳統的作法可能是直接開始思考技術架構，但使用 spec-kit 讓我能夠先專注於釐清需求本身。

使用 /specify 釐清需求

首先，我使用 /specify 指令來描述這個專案的核心需求：

這個規格的重點在於明確描述了「要做什麼」而不是「怎麼做」。我強調了標籤驗證的重要性，因為無限制的標籤增長會讓書籤系統變得難以管理。同時也說明了這個工具的最終目的：統一不同來源的書籤管理。

透過幾句口語話的需求描述，spec-kit 就能自動產生完整的產品規格文件。以下摘要幾個關鍵部分來展示其價值：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

**User Scenarios & Testing**：

"A user discovers an interesting article while browsing Twitter or Safari. Instead of saving it in multiple different bookmark systems, they open Telegram, send a `/bookmark` command with the URL and tags from their predefined tagging system, and the bot automatically saves the bookmark to their centralized Linkding instance with validated, consistent tags."

**Primary User Story**：

- **Given** user has access to the Telegram bot and valid predefined tags, **When** user sends `/bookmark https://example.com tech programming`, **Then** the system validates tags against the predefined list and saves the URL to Linkding with approved tags
- **Given** user sends a bookmark command with invalid tags, **When** the command includes tags not in the predefined system, **Then** the system rejects the bookmark and suggests valid alternative tags

**Functional Requirements**：

- **FR-002**: System MUST validate all provided tags against a predefined tagging system stored in the codebase
- **FR-008**: System MUST provide specific error messages for tag validation failures with suggested alternatives
- **FR-012**: System MUST prevent uncontrolled tag growth by only accepting predefined tags

使用 /plan 制定技術計劃

基於上述規格，接下來使用 /plan 指令來制定具體的技術實作計劃：

基於規格文件搭配/plan 指令自動產生了詳細的技術實作計劃。以下摘要關鍵部分：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# Implementation Plan: Telegram Bookmark Bot with Predefined Tagging

## Summary

Telegram bot for saving bookmarks to self-hosted Linkding instance with controlled tagging system.
Bot validates tags against predefined list, prevents tag sprawl, and integrates with Linkding API.
Implemented as Cloudflare Worker using grammY framework.

## Technical Context

Language/Version: TypeScript/Node.js 18+ (Cloudflare Worker runtime)
Primary Dependencies: grammY Telegram bot framework, Cloudflare Workers API, Linkding REST API client
Performance Goals: <200ms message processing, <500ms API responses
Scale/Scope: Personal use (single user), ~1000 bookmarks/month, 2 commands

## Constitution Check

✅ Code Quality & Standards: TypeScript, ESLint/Prettier, modular design
✅ Testing-First Development: Contract tests, integration tests, 80% coverage target
✅ User Experience Consistency: Standardized commands, consistent error messaging
✅ Performance Requirements: <200ms processing, <100MB memory usage

## Phase 1: Design & Contracts

- Extract entities from feature spec → data-model.md
- Generate API contracts from functional requirements
- Generate contract tests, Extract test scenarios from user stories

## Phase 2: Task Planning Approach

Task Categories: Setup, Configuration, Models, API Integration, Bot Commands, Testing, Deployment
Estimated Output: 20-25 numbered, ordered tasks in tasks.md

這個例子很好地說明了 spec-kit 如何幫助開發者從模糊的想法進展到明確的實作計劃。在 /specify 階段，我專注於釐清使用場景和功能需求，不需要考慮技術細節。到了 /plan 階段，才開始思考如何用具體的 tech stacks 來實現這些需求。這種分離讓整個開發過程更有條理，也減少了在需求不明確的情況下就急於選擇技術方案的風險。

接續就是執行 /tasks, /implement 的流程讓整個開發過程變得高度自動化。/tasks 指令會讀取實作計劃和相關文件，將技術方案分解成具體可執行的任務清單。這些任務會標示並行處理的可能性（以 [P] 標記），讓開發團隊能夠平行推進不同模組的開發。

以 Telegram Bookmark Bot 為例，/tasks 產生了約 32 個結構化任務，涵蓋環境設定、資料模型定義、API 整合、命令實作、測試撰寫到部署流程。每個任務都包含明確的輸入、輸出和驗收標準，確保實作過程不會偏離原始規格。spec-kit 強調「測試優先」的開發方法。在 /tasks 階段就會產生對應的測試計劃，包含合約測試（contract tests）和整合測試，確保每個功能都有適當的驗證機制。

完成任務規劃後，就能使用 /implement 或其他 coding agent 根據任務清單逐步實作功能。由於每個任務都有明確的規格和測試標準，AI 生成的程式碼品質明顯提升，需要人工修正的部分也大幅減少。

spec-kit 的優點

使用 spec-kit 後，我發現它最大的價值在於強制分離思考層次。傳統開發中，我們經常一邊思考「要解決什麼問題」，一邊就開始考慮「用什麼技術實作」。這種混合思考容易導致過早陷入技術細節，或者受限於熟悉的技術而錯失更好的解決方案。spec-kit 讓我在 /specify 階段只需專注於描述問題和期望結果，這種限制反而釋放了創造力，讓我能更深入思考使用者的真正需求、預期解決什麼問題。

最讓我印象深刻的是它能夠將幾句簡單描述，自動擴展成包含使用者故事、驗收標準、邊界情況的完整規格。這不只是格式化，而是真正的思考輔助。舉例來說，我只提到「標籤驗證」，但 spec-kit 自動產生了「標籤拼寫錯誤怎麼處理」、「API 失效時如何回應」等邊界情況。這些是我手動寫規格時常常遺漏的細節，但對 system robustness 卻很重要。

另外，spec-kit 也會透過 [NEEDS CLARIFICATION] 標記主動停下來與使用者釐清模糊的需求，防止 AI 盲目推進或用自己的假設來實作。這個機制特別重要，因為傳統的 AI coding tools 往往會在遇到不明確的需求時自行做出假設，導致最終產出與使用者期望產生落差。

舉例來說，當我在規格中提到「標籤驗證」時，spec-kit 會標記 [NEEDS CLARIFICATION: How should the system handle partial tag matches or typos?]，強制我思考邊界情況。這種互動式的澄清過程確保規格文件的完整性，避免了後續實作階段才發現需求定義不清的問題。相較於事後修補，這種前置的需求澄清大幅降低了開發成本和時間。

對於 AI 協作而言，spec-kit 解決了最大的痛點 —— Contextual Consistency。對話進行一段時間後，AI 會「忘記」先前的設計決策，但規格文件就像與 AI 溝通的 contract，確保生成的程式碼始終符合原始需求。更重要的是，相比模糊的自然語言描述，明確的功能需求（如 FR-002: System MUST validate all provided tags）能讓 AI 產生更精確的程式碼。需求變更時，我可以直接修改規格文件，重新執行 /plan 來生成更新的技術計劃，確保新需求與既有架構的一致性。

這次試用下來，我發現自己的需求分析思維變得更加系統化。即使不使用工具，我也會自然地思考使用者故事、邊界情況和驗收標準。這種結構化思考的習慣不僅適用於程式開發，在日常工作的問題分析和解決方案設計上也很有幫助。可以說，spec-kit 不只是工具，更像是思維訓練器。

使用過程中的挑戰與限制

儘管 spec-kit 帶來不少效益，但在實際使用過程中也遇到一些挑戰。最明顯的限制是需 求變動時的處理方式，依照 spec-kit 的設計邏輯，新的需求變動需要重新展開完整的 /specify → /plan → /tasks → /implement 流程。這在小幅功能調整時可能顯得過於繁重，特別是當只想新增一個簡單的 API endpoint 或修改現有功能的行為時。目前我的做法是直接重新進行一次完整的 spec-kit 流程來添加新功能，雖然依照現有架構進行新 feature 迭代開發確實比較少需要人工確 認，但這種「重新來過」的方式在敏捷開發環境中可能不夠靈活。

雖然整體而言 spec-kit 大幅提升了 AI 生成程式碼的品質，但仍有不如預期的實作部分需要人為確認。舉例來說，第一次實作 Telegram Bookmark Bot 時，儘管我在規格中明確標明要使用 grammY 作為實作框架，實際開始實作後卻出現並未使用該框架的現象，或是某些功能未如預期且無法自動修正的情況。不過，相較於過往單純使用 coding agent 的經驗，透過 spec-kit 實作後的第一輪結果，通常只需要兩三輪的修正就能正常運作，整體效率仍然比原先的開發方式提升許多。

相關文章 GitHub Spec Kit Experiment: ‘A Lot of Questions’ 也指出 spec-kit 目前仍處於早期開發階段。從 GitHub 社群中活躍的 issues 和 discussions 可以看出，使用者持續提出各種功能改進需求，顯示這個工具確實還有不少精進空間。這也解釋了為什麼在實際使用中會遇到一些不如預期的情況，但同時也讓人對未來的發展抱持樂觀態度。

結語

經過一段時間的實際使用，我認為 spec-kit 代表了 AI 協作開發的重要方向。雖然目前仍處於早期階段，但它所提出的「spec-driven development」理念確實能夠改善與 AI 工具的協作品質。我個人看好這類開發工具的發展，相信未來會有更多類似的解決方案出現，幫助開發者更有效地運用 AI 進行開發協作。

從使用場景來看，spec-kit 在新專案開發和功能擴展時幫助最大，特別是需要從零開始建 立完整需求規格的情境。對於小幅度的功能調整或 bug 修復，傳統的開發方式可能更為直接。總體而言，這個工具最大的價值在於強制建立結構化的思考流程，即使不使用工具本身，這種需求分析方法也值得採用。

目前我主要以 Claude Code 來試用 spec-kit，與其他工具的結合尚待嘗試。不過根據官方文件，spec-kit 與許多主流開發工具都有串接支援，適用性相當高。值得一提的是，GitHub discussions 中有社群成員製作的 workflow，對於理解 spec-kit 的實際應用流程非常有幫助。對於想要嘗試的開發者，建議可以閱讀 spec-kit 提供的 完整文章 來了解核心理念，但更重要的是實際用它開 發一個完整的小專案，這樣能更快理解工具的使用方式和價值所在。

期待未來 spec-kit 能支援更輕量的增量式需求更新，而不需要重新走完整流程。最重要的是，這個工具已經幫助我在需求分析上建立更完善的思考框架，讓我能夠更系統化地思考邊界案例，並以結構化的方式處理實際的使用需求。這種思維方式的改變，可能是比工具本身更長遠的收穫。

Photo by Brett Jordan on Unsplash