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/project.md and help me fill it out
with details about my project, tech stack, and conventions

AI 會幫你填寫專案的技術棧、開發慣例等資訊。

4. 目錄結構

初始化完成後的結構：

├── CLAUDE.md              # Claude Code 的提示詞 (或其他工具對應的檔案) 
└── openspec/
    ├── AGENTS.md          # 給 AI 讀的工作流程說明
    ├── project.md         # 專案基本資訊、技術棧、慣例
    ├── specs/             # 目前系統的規格
    └── changes/           # 進行中的變更提案
        └── archive/       # 已完成的變更歷史

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

核心流程：三個指令

OpenSpec 的工作流程只有三個階段：

proposal → apply → archive

Stage 1：Draft Proposal (草擬提案)

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

/openspec:proposal 新增使用者搜尋功能

或用自然語言：

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

AI 會在 openspec/changes/ 建立：

建立後記得驗證格式：

openspec validate add-user-search --strict

Stage 2：Implement (實作)

提案確認沒問題後，開始實作：

/openspec:apply add-user-search

AI 會依照 tasks.md 逐步完成，每完成一項就打勾：

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

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

Stage 3：Archive (歸檔)

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

/openspec:archive add-user-search

歸檔會做兩件事：

1. 把變更目錄移到 changes/archive/2026-01-22-add-user-search/
2. 把規格差異合併回 specs/ 目錄

流程總覽

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

想到新功能
    ↓
/openspec:proposal → 建立提案、定義規格
    ↓
Review & 調整規格 ← 跟 AI 來回討論
    ↓
openspec validate → 確認格式正確
    ↓
/openspec:apply → AI 照規格實作
    ↓
測試通過
    ↓
/openspec:archive → 歸檔，更新系統真相

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

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

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

Step 1：建立提案

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

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：驗證格式

openspec validate add-product-favorites --strict

Step 4：開始實作

/openspec:apply add-product-favorites

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

Step 5：測試驗收

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

Step 6：歸檔

/openspec:archive add-product-favorites

完成！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/ 定義的不一樣？ 如果會 → 需要建提案。反之，不會 → 直接改