OpenSpec 完整教學指南

Chapter 01

OpenSpec 是什麼？

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

核心理念

先寫規格

產出格式

Markdown

設計取向

Brownfield

特性	說明
SDD 工具	規格驅動開發 — 先寫規格再寫程式，AI 不再通靈亂做
零外部依賴	不需要 API key、不需要雲端服務，所有產出都是本地 Markdown 檔案
廣泛支援	Claude Code、Cursor、GitHub Copilot、Gemini CLI、OpenAI Codex 等主流工具
適用場景	專為既有專案（1→N）設計，也適用全新專案（0→1），漸進式導入成本極低

SDD 工具比較

工具	適用場景	複雜度	特色
BMAD	大公司 / 大團隊	高	詳盡流程與角色分工，企業級協作
Spec Kit	全新專案 (0→1)	中	GitHub 官方推出，文件結構完整但較冗長
OpenSpec	既有專案 (1→N)	低	輕量快速，三招搞定：proposal → apply → archive

Chapter 02

安裝與初始化

1

安裝 OpenSpec（需 Node.js 20.19+）

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

2

在專案目錄初始化

cd your-project && openspec init → 選擇使用的 AI 工具

3

填寫專案資訊（貼給 AI 即可）

Please read openspec/config.yaml and help me fill it out

4

將 openspec/ 目錄加入版控 (Git)

保留歷史紀錄、支援多人協作

目錄結構

openspec/
├── config.yaml ← 專案設定（tech stack、慣例）
├── specs/ ← 系統真相（已上線的功能規格）
│   ├── auth/
│   │   └── spec.md
│   └── products/
│       └── spec.md
└── changes/ ← 進行中的變更提案
    ├── add-search/
    │   ├── proposal.md
    │   ├── tasks.md
    │   ├── design.md (選用)
    │   └── specs/
    └── archive/ ← 已完成的歷史紀錄

specs/ = 系統目前的真相來源（已部署）
changes/ = 正在進行的變更提案（尚未合併）
archive/ = 完成歸檔的歷史紀錄（含日期前綴）

Chapter 03

核心工作流程（OPSX 指令）

OpenSpec v1.0 採用靈活的 action-based 工作流程，不再是線性鎖死的三階段。

整體流程圖

想到新功能 / 需求

Stage 0

/opsx:explore

AI 反覆提問釐清需求細節

Stage 1 — 規劃

/opsx:new → /opsx:ff

建立變更 → 生成規劃 artifact

Stage 2 — 實作

/opsx:apply → /opsx:verify

依規格實作 → 驗證符合

Stage 3 — 歸檔

/opsx:archive

歸檔完成，specs/ 更新為最新狀態

指令	說明
`/opsx:explore`	自由發想，AI 會反覆提問釐清細節直到雙方有共識
`/opsx:new <name>`	建立新的變更資料夾，如 `/opsx:new add-search`
`/opsx:continue`	逐步建立 artifact（proposal → specs → design → tasks），可一一 review
`/opsx:ff`	快轉（fast-forward）— 一次生成所有規劃 artifact

continue vs ff：continue 適合需求不確定時逐步 review；ff 適合需求明確時快速產出。兩者產出結果完全相同。

AI 會在 openspec/changes/ 產出四個核心檔案：

proposal.md

Why / What / Impact

specs/

Delta 格式規格差異

tasks.md

Checkbox 待辦清單

指令	說明
`/opsx:apply`	AI 讀取 tasks.md，逐步實作並打勾，完成一項勾一項
`/opsx:verify`	驗證實作是否符合 specs/ 中定義的所有 Scenario

tasks.md 進度即時更新

- [x] 建立 favorites 資料表 migration
- [x] 建立 Favorite model 及關聯
- [x] 實作 POST /api/favorites（新增收藏）
- [ ] 實作 DELETE /api/favorites/:id（移除收藏） ← AI 正在做
- [ ] 實作 GET /api/users/:id/favorites（收藏清單）
- [ ] 撰寫測試

實作過程中發現規格有問題？直接修改 artifact 再繼續即可，不需要「回到上一個階段」。

指令	說明
`/opsx:archive`	歸檔變更，將 Delta 合併回 specs/ 並移至 archive/
`/opsx:sync`	預覽規格合併結果（不實際執行）

歸檔做兩件事：

動作 1：搬移並加日期前綴

changes/add-favorites/
→ archive/2026-04-10-add-favorites/

動作 2：合併 Delta 回 specs/

ADDED / MODIFIED / REMOVED 的差異合併回系統真相

歸檔後 specs/ 永遠反映系統「目前應有的行為」，archive/ 保留完整變更歷史。

Chapter 04

ff vs continue 深入比較

快速模式

`/opsx:ff`

Fast-forward — 一次全部生成

proposal.md

↓ 自動

specs/ (Delta)

↓ 自動

design.md

↓ 自動

tasks.md

全部一口氣產出，結束後再統一 review

逐步模式

`/opsx:continue`

一次建一個 artifact，逐步推進

proposal.md → 你 review

↓ 再呼叫一次

specs/ → 你 review

↓ 再呼叫一次

design.md → 你 review

↓ 再呼叫一次

tasks.md → 你 review

每一步都停下來讓你確認再繼續

指令	適用情境	原因
`ff`	需求已經很明確 / 小功能	前面做過 explore 或需求單純，一次產出最有效率
`continue`	需求有不確定性 / 複雜變更	影響範圍大，每步都值得仔細檢視

Chapter 05

spec.md 規格檔案格式

格式規則	說明
Requirement 標題	使用 `### Requirement: 名稱`，每個至少要有一個 Scenario
Scenario 標題	必須使用 `#### Scenario: 名稱`，不是 `###` 或 bullet point
需求描述關鍵字	使用 `SHALL` 或 `MUST` 表達必要性（源自 RFC 2119）
Scenario 內容	使用 `- WHEN` / `- THEN` / `- AND` 描述條件與結果

範例

### Requirement: User Login

使用者 SHALL 能夠使用 Email 和密碼登入系統。

#### Scenario: 登入成功
- WHEN 使用者輸入正確的 Email 和密碼
- THEN 系統回傳 JWT token
- AND 記錄登入時間

#### Scenario: 密碼錯誤
- WHEN 使用者輸入錯誤的密碼
- THEN 系統回傳 401 錯誤
- AND 增加失敗次數記錄
  

Delta 格式（變更提案用）

變更提案的 specs/ 不寫完整規格，而是寫「跟現有規格相比，這次要改什麼」：

標記	操作	注意事項
`## ADDED`	新增	寫入完整的新需求內容及所有 Scenario
`## MODIFIED`	修改	必須放「修改後的完整內容」，不能只寫差異部分
`## REMOVED`	移除	須附 Reason（原因）與 Migration（替代方案）
`## RENAMED`	更名	重新命名需求

MODIFIED 特別重要！歸檔時會用提供的內容「整個取代」原本的需求。如果只寫差異，原本的內容會消失！

Chapter 06

什麼時候不需要建提案？

判斷原則：這次改動會不會讓系統行為跟 specs/ 裡定義的不一樣？

情況	需要提案？	理由
修 Bug	不需要	讓程式符合規格，不是改變規格
修錯字 / 改註解	不需要	不影響系統行為
更新套件（非破壞性）	不需要	不是 breaking change
調整設定	不需要	不改變系統行為規格
補寫測試	不需要	驗證現有規格，不是改規格
新增功能	需要	系統行為將與 specs/ 不一致
破壞性變更	需要	改變既有系統行為
架構調整	需要	影響範圍大，需記錄決策脈絡

Chapter 07

常用 CLI 指令一覽

指令	用途
`openspec init`	初始化專案，設定 AI 工具
`openspec list`	列出進行中的變更（加 `--specs` 列出現有規格）
`openspec show <name>`	顯示變更或規格詳情（加 `--json` 輸出 JSON）
`openspec validate <name> --strict`	驗證格式（Scenario、SHALL 關鍵字、Delta 格式）
`openspec archive <name>`	歸檔變更（加 `--yes` 跳過確認）
`openspec view`	互動式 Dashboard，瀏覽所有 specs 與 changes

Chapter 08

實戰範例：新增商品收藏功能

1

explore 需求探索

/opsx:explore → AI 反覆提問釐清細節（收藏上限？重複行為？）

2

new 建立變更

/opsx:new add-favorites → 建立 openspec/changes/add-favorites/

3

ff 快速生成規劃文件

/opsx:ff → 生成 proposal.md、specs/、design.md、tasks.md

4

review 檢視並調整

跟 AI 討論：「收藏要有上限 100 個」→ AI 更新 spec 新增 Scenario

5

apply 依規格實作

/opsx:apply → AI 照 tasks.md 逐步實作，完成一項勾一項

6

verify 驗證實作

/opsx:verify → 確認程式碼符合所有 Scenario 定義

7

archive 歸檔完成

/opsx:archive → specs/ 更新為最新狀態，歷史保存在 archive/

Chapter 09

design.md 使用時機

design.md 是選用的檔案，用來記錄技術決策。以下場景建議使用：

場景	design.md 的作用
跨系統 / 跨模組變更	說明模組間如何互動
引入新的外部依賴	記錄為何選擇它、替代方案有哪些
安全性 / 效能考量	記錄策略與取捨 (trade-offs)
需要 Migration	說明資料遷移計畫與部署步驟

簡單的變更不需要建立 design.md，OpenSpec 不會強制要求這個檔案存在。

Chapter 10

核心價值總結

規格先行

AI 不再通靈亂做，有明確標準驗收產出

驗收標準

每個 Requirement 都有 Scenario，知道何時算「完成」

歷史追溯

每次變更保留在 archive/，知道為何這樣設計

多人協作

不同提案在不同目錄，specs 不重疊就不會踩到

可重來性

AI 做歪了可以回到修改前狀態，換另一個 Agent 來做

低導入成本

裝 npm、跑 init、填 config，就能開始使用