OpenSpec 入門教學

什麼是 OpenSpec？

OpenSpec 是一個輕量級的 SDD (Spec-Driven Development) 工具，核心理念是：先談好規格，再動手寫 code，讓開發者與 AI 對「什麼叫做完成」有共同認知。

另外，OpenSpec 不需要 API key、不需要連線雲端服務，所有產出都是 Markdown 檔案。設計上採用 Brownfield-first 理念，專為既有專案設計，適合漸進式導入而非從零開始。工具支援也很廣泛，Claude Code、Cursor、GitHub Copilot、Gemini CLI 等主流 AI 工具都能使用。

安裝與初始化

1. 安裝

npm install -g @fission-ai/openspec@latest

確認安裝成功：

openspec --version

2. 初始化專案

cd your-project
openspec init

初始化時會問你使用哪些 AI 工具，選完後會自動設定對應的 slash command。

3. 填寫專案資訊

把以下內容貼給你的 AI coding 工具：

Please read openspec/config.yaml and help me fill it out
with details about my project, tech stack, and conventions

AI 會幫你填寫專案的 tech stack、開發慣例等資訊。新版的 config.yaml 會在每次規劃請求時自動帶入 context，確保 AI 隨時都能了解你的專案慣例。

4. 目錄結構

初始化完成後的結構：

├── CLAUDE.md              # Claude Code 的 prompt (或其他工具對應的檔案)
└── openspec/
    ├── config.yaml        # 專案設定，context 會自動帶入每次規劃請求
    ├── specs/             # 目前系統的規格
    └── changes/           # 進行中的變更提案
        └── archive/       # 已完成的變更歷史

💡 整個 openspec 目錄應該進版控，這樣才能保留歷史紀錄和支援多人協作。

核心流程：OPSX 指令

OpenSpec v1.0 從原本固定的三階段流程，改為更靈活的 action-based 工作流程。核心理念是：工作不是線性的，OPSX 不再假裝它是。

主要指令：

其他實用指令：

Stage 1：Start a Change (開始變更)

當你想要新增功能、做破壞性變更或改動架構時，第一步是建立變更：

/opsx:new 新增使用者搜尋功能

或用自然語言：

幫我建立一個 OpenSpec 變更，我想新增使用者搜尋功能

接著用 /opsx:continue 逐步建立各個 artifact，或用 /opsx:ff 一次全部產生：

/opsx:ff

AI 會在 openspec/changes/ 建立：

💡 /opsx:continue 和 /opsx:ff 的差別：continue 一次建一個 artifact，讓你可以逐步 review；ff 則一口氣全部產生，適合需求明確的情況。

Stage 2：Implement (實作)

規劃確認沒問題後，開始實作：

/opsx:apply

AI 會自動判斷要實作哪個變更，依照 tasks.md 逐步完成，每完成一項就打勾：

- [x] 建立資料表 migration
- [x] 建立 Model
- [ ] 實作 API endpoint

💡 如果 AI 想做規格外的事，可以提醒它：「這不在提案範圍內，請專注在 tasks.md 的項目。」

實作完成後，可以用 /opsx:verify 驗證實作是否符合規格。

Stage 3：Archive (歸檔)

所有任務完成、測試通過後：

/opsx:archive

歸檔會做兩件事：

1. 把變更目錄移到 changes/archive/ 下
2. 把規格差異合併回 specs/ 目錄

流程總覽

接著先來複習一下，整個開發流程會變成怎樣？

想到新功能
    ↓
/opsx:new → 開始變更
    ↓
/opsx:continue 或 /opsx:ff → 建立規劃 artifact
    ↓
Review & 調整 ← 跟 AI 來回討論（可隨時修改任何 artifact）
    ↓
/opsx:apply → AI 照規格實作
    ↓
/opsx:verify → 驗證實作符合規格
    ↓
測試通過
    ↓
/opsx:archive → 歸檔，更新系統真相

跟舊版最大的差別是，新版的流程不再是線性鎖死的。實作過程中發現設計有問題？直接改 artifact 再繼續就好，不用「回到上一個階段」。

這樣做的好處是，當 AI 做歪的時候，你有明確的標準可以打槍它；當需求不夠清楚的時候，建立提案的過程會逼你把需求想清楚。

情境題：新增商品收藏功能

接著我們用一個情境來跑一次看看，假設我們有一個電商網站，老闆說要「新增商品收藏功能」。

Step 1：開始變更

/opsx:new 新增商品收藏功能，讓使用者可以收藏喜歡的商品

接著快轉產生所有規劃 artifact：

/opsx:ff

AI 產生的 proposal.md：

# Add Product Favorites

## Why
使用者希望能收藏感興趣的商品，方便日後購買。

## What Changes
- 新增收藏 API endpoints
- 使用者可以新增/移除收藏
- 可以查看收藏清單

## Impact
- Affected specs: users, products
- Affected code: controllers/, models/, routes/

AI 產生的 tasks.md：

- [ ] 建立 favorites 資料表 migration
- [ ] 建立 Favorite model 及關聯
- [ ] 實作 POST /api/favorites  (新增收藏) 
- [ ] 實作 DELETE /api/favorites/:id  (移除收藏) 
- [ ] 實作 GET /api/users/:id/favorites  (取得收藏清單) 
- [ ] 撰寫測試

AI 產生的 specs/favorites/spec.md (Delta 格式) ：

## ADDED Requirements

### Requirement: Add to Favorites

使用者 SHALL 能夠將商品加入收藏清單。

#### Scenario: 收藏成功

- WHEN 使用者對商品點擊收藏
- THEN 系統建立收藏記錄
- AND 回傳 201 Created

#### Scenario: 重複收藏

- WHEN 使用者收藏已收藏的商品
- THEN 系統回傳 409 Conflict

Step 2：Review 並調整規格

跟 AI 討論：

等等，收藏應該要有上限，一個使用者最多收藏 100 個商品

AI 會更新 spec，新增 Scenario：

#### Scenario: 超過收藏上限

- WHEN 使用者已有 100 個收藏
- AND 嘗試新增收藏
- THEN 系統回傳 422 錯誤
- AND 錯誤訊息為「收藏數量已達上限」

Step 3：開始實作

/opsx:apply

AI 照著 tasks 逐步實作，完成一項就打勾。

Step 4：驗證實作

/opsx:verify

驗證實作是否符合 spec 定義的 scenarios。

Step 5：測試驗收

跑測試確認實作符合 spec 定義的 scenarios。

Step 6：歸檔

/opsx:archive

完成！specs/ 現在是系統的最新真相。

規格檔案格式

spec.md 結構

# Feature Name Specification

## Purpose
功能的目的說明。

## Requirements

### Requirement: 需求名稱

需求描述，使用 SHALL 或 MUST 表達規範性需求。

#### Scenario: 情境名稱

- WHEN 某個條件
- THEN 預期結果
- AND 其他結果

格式重點

Delta 格式 (變更提案用)

變更提案的 specs 不寫完整規格，而是寫「差異」：

## ADDED Requirements
 (新增的需求) 

## MODIFIED Requirements
 (修改的需求，要放完整修改後的內容) 

## REMOVED Requirements
 (移除的需求，要說明原因和轉移方式)

什麼時候不需要建提案？

以下情況可以直接改程式碼：

• ✅ 修 bug：讓程式符合規格，不是改規格
• ✅ 修錯字、調格式、改註解：不影響系統行為
• ✅ **更新套件 (非破壞性) **：不是 breaking change
• ✅ 調整設定：不改變系統行為
• ✅ 補測試：驗證現有規格，不是改規格

我自己的判斷原則是：這次改動會不會讓系統行為跟 specs/ 裡定義的不一樣？ 如果會 → 需要建提案；不會 → 直接改就好